Identificare i blocchi di riattivazione creati da altre API

Diverse librerie e API di sistema possono acquisire wake lock attribuibili alla tua app. Ciò può rendere difficile identificare un wake lock nella tua app che potrebbe causare un problema. Se utilizzi in modo improprio un'API, la tua app potrebbe mantenere un wake lock troppo a lungo, anche se non chiami direttamente le API wake lock.

Questo documento elenca alcuni nomi di wakelock comuni che potresti visualizzare quando utilizzi gli strumenti di debug wakelock. Potresti anche vedere questi nomi in un report di Android vitals. In alcuni casi, il blocco della riattivazione potrebbe essere stato creato da una libreria o da un'API di sistema. In altri casi, esiste un motivo per cui lo strumento offusca il nome del wake lock utilizzato nell'app. Puoi utilizzare gli strumenti di debug per identificare i wake lock che non funzionano correttamente, quindi cercare il nome del wake lock in questo documento per identificare l'API che potrebbe causare il problema e come risolverlo.

Questo documento descrive gli scenari in cui potrebbero essere creati i wake lock. In ogni caso, anche se il wake lock potrebbe essere creato da un'altra libreria o API, il blocco viene attribuito all'app che ha chiamato l'API.

AlarmManager

AlarmManager acquisisce i wake lock e li attribuisce all'app chiamante. AlarmManager acquisisce il wake lock quando scatta la sveglia e lo rilascia al termine dell'esecuzione del metodo onReceive() della trasmissione della sveglia.

Nomi dei wakelock

AlarmManager crea wake lock con il nome *alarm*. (Gli asterischi fanno parte del nome del blocco di riattivazione, non rappresentano caratteri jolly.)

Consiglio

Ti consigliamo le seguenti pratiche per ottimizzare il comportamento degli allarmi:

  • Utilizza AlarmManager per ottimizzare la frequenza di programmazione degli allarmi.
  • Utilizza le sveglie RTC_WAKEUP (che riattivano il dispositivo) solo quando necessario.
  • Riduci al minimo l'uso di allarmi ed evita di svolgere lavori lunghi con il metodo onReceive().

Audio e contenuti multimediali

Le API multimediali possono acquisire wake lock durante la registrazione o la riproduzione di audio. I wake lock sono attribuiti all'app di chiamata.

Nomi dei wakelock

Le API per il settore dei media acquisiscono wakelock con vari nomi che iniziano con Audio:

  • AudioBitPerfect: utilizzato per la riproduzione audio USB lossless.
  • AudioDirectOut: utilizzato per la riproduzione audio lossless su una TV o un dispositivo speciale.
  • AudioDup: utilizzato per la riproduzione delle notifiche quando è connesso tramite Bluetooth o USB.
  • AudioIn: utilizzato per l'acquisizione audio in modalità videocamera mentre il microfono è attivo.
  • AudioMix: utilizzato per la riproduzione audio su un dispositivo comune.
  • AudioOffload: utilizzato per la riproduzione di sola musica a lungo termine, per le app che supportano questa modalità.
  • AudioSpatial: utilizzato per la riproduzione di audio multicanale di film o musica su dispositivi che supportano l'audio spaziale.
  • AudioUnknown: utilizzato quando le altre situazioni non si applicano.
  • MmapCapture: utilizzato per l'acquisizione audio a bassa latenza.
  • MmapPlayback: utilizzato per la riproduzione a bassa latenza, ad esempio per i giochi o per applicazioni audio professionali.

Consiglio

Ti consigliamo di seguire queste pratiche:

  • Non utilizzare nomi wakelock che iniziano con Audio.
  • Se utilizzi le API multimediali, non dovresti dover acquisire direttamente i wake lock. Puoi fare affidamento sulle API per acquisire i wake lock necessari.
  • Quando utilizzi le API multimediali, termina la sessione multimediale quando non ti serve più.

Firebase Cloud Message (FCM)

GCM acquisisce un wake lock durante la distribuzione di una trasmissione Firebase Cloud Message (FCM) all'app. Il wake lock viene rilasciato al termine dell'esecuzione del metodo di trasmissione FCM onMessageReceived().

Nomi dei wakelock

GCM acquisisce un wake lock con il nome GOOGLE_C2DM.

Consiglio

Per ottimizzare il comportamento di FCM, ti consigliamo le seguenti pratiche:

  • Ottimizza la frequenza di invio di FCM.
  • Non utilizzare FCM ad alta priorità a meno che il messaggio non debba essere recapitato immediatamente.
  • Completa il metodo onMessageReceived() il più rapidamente possibile. Per saperne di più, consulta le linee guida di Firebase.

JobScheduler

I job di JobScheduler acquisiscono wakelock durante l'esecuzione delle attività in background. I wake lock vengono attribuiti all'app che ha creato i worker.

Nomi dei wakelock

I nomi dei wake lock acquisiti da JobScheduler dipendono dalla versione del sistema Android su cui vengono eseguiti e dallo scopo del job.

Gli elementi racchiusi tra parentesi angolari sono variabili. Ad esempio, "<package_name>" è il nome del pacchetto della tua app, non il testo letterale <package name>. Tuttavia, *job* è la sequenza di caratteri *job*, con asterischi; gli asterischi non vengono utilizzati come caratteri jolly.

Android 15 e versioni precedenti

I job avviati dall'utente creano wake lock con nomi che seguono questo pattern:

*job*u/@<name_space>@/<package_name>/<classname>

Altri lavori utilizzano questo modello:

*job*/@<name_space>@/<package_name>/<classname>
Android 16 e versioni successive

I job avviati dall'utente creano wake lock con nomi che seguono questo pattern:

*job*u/@<name_space>@/#<trace_tag>#/<package_name>/<classname>

I job urgenti utilizzano questo pattern:

*job*e/@<name_space>@/#<trace_tag>#/<package_name>/<classname>

I job regolari utilizzano questo pattern:

*job*r/@<name_space>@/#<trace_tag>#/<package_name>/<classname>
Esempio

Supponiamo che esista un job rapido con lo spazio dei nomi backup e il tag di traccia started. Il nome del pacchetto è com.example.app e la classe che ha creato il job è com.backup.BackupFileService.

Sui dispositivi con Android 15 o versioni precedenti, il wake lock si chiamerà:

*job*/@backup@/com.example.app/com.backup.BackupFileService

Sui dispositivi con Android 16 o versioni successive, il blocco della riattivazione si chiamerà:

*job*e/@backup@/#started#/com.example.app/com.backup.BackupFileService

Consiglio

Controlla l'utilizzo delle attività JobScheduler. In particolare, segui le nostre indicazioni per ottimizzare l'utilizzo della batteria per le API di pianificazione delle attività.

Posizione

LocationManager e FusedLocationProviderClient utilizzano i wake lock per acquisire e fornire la posizione del dispositivo. I wake lock sono attribuiti all'app che ha chiamato queste API.

Nomi dei wakelock

I servizi di localizzazione utilizzano i seguenti nomi:

  • CollectionLib-SigCollector
  • NetworkLocationLocator
  • NetworkLocationScanner
  • NlpCollectorWakeLock
  • NlpWakeLock
  • *location*

Consiglio

Ottimizzare l'utilizzo della posizione. Ad esempio, imposta timeout, richieste di localizzazione batch o utilizza aggiornamenti passivi della posizione.

WorkManager

I worker di WorkManager acquisiscono i wakelock durante l'esecuzione delle attività in background. I wake lock vengono attribuiti all'app che ha creato i worker.

Nomi dei wakelock

I nomi dei wake lock acquisiti da WorkManager dipendono dalla versione del sistema Android su cui vengono eseguiti.

Android 15 e versioni precedenti

Le attività di WorkManager creano wake lock con nomi che seguono questo pattern:

*job*/<package_name>/androidx.work.impl.background.systemjob.SystemJobService
Android 16 e versioni successive

Le attività rapide creano blocchi di riattivazione con nomi che seguono questo pattern:

*job*e/#<trace_tag>#/<package_name>/androidx.work.impl.background.systemjob.SystemJobService

Le attività regolari seguono questo schema:

*job*r/#<trace_tag>#/<package_name>/androidx.work.impl.background.systemjob.SystemJobService

Per impostazione predefinita, <trace_tag> è il nome del worker.

Esempio

Supponiamo che esista un lavoratore con procedura rapida di nome BackupFileWorker. Il nome del pacchetto è com.example.app.

Sui dispositivi con Android 15 o versioni precedenti, il wake lock si chiamerà:

*job*/com.example.app/androidx.work.impl.background.systemjob.SystemJobService

Sui dispositivi con Android 16 o versioni successive, il blocco della riattivazione si chiamerà:

*job*e/#BackupFileWorker#/com.example.app/androidx.work.impl.background.systemjob.SystemJobService

Consiglio

Esegui l'audit dell'utilizzo dei worker WorkManager. In particolare, segui le nostre indicazioni per ottimizzare l'utilizzo della batteria per le API di pianificazione delle attività.

_UNKNOWN

Se gli strumenti di debug ritengono che il nome di un wake lock contenga informazioni che consentono l'identificazione personale (PII), non visualizzano il nome effettivo del wake lock. ma etichettano il wake lock come _UNKNOWN. Ad esempio, gli strumenti potrebbero farlo se il nome del wake lock contiene un indirizzo email.

Consiglio

Segui le best practice per la denominazione dei wakelock ed evita di utilizzare PII nel nome del wakelock. Se trovi un wake lock denominato _UNKNOWN attribuito alla tua app, prova a identificare di quale wake lock si tratta e assegnagli un nome diverso.