Identificare e ottimizzare i casi d'uso di wake lock

Questo documento ti aiuta a identificare e ottimizzare i casi d'uso dei wakelock nella tua app, nonché a evidenziare se esistono wakelock acquisiti da altre librerie o API di sistema associati a questo caso d'uso. Poiché questi wakelock sono attribuibili alla tua app, può essere difficile individuare l'origine di un wakelock problematico. Un utilizzo errato dell'API può causare la segnalazione della tua app per un utilizzo eccessivo dei wakelock, anche se non li acquisisci esplicitamente.

Questo documento elenca alcuni nomi di wakelock comuni che potresti incontrare quando utilizzi gli strumenti di debug dei wakelock o nei report di Vitals. Questi nomi possono provenire da una libreria o da un'API di sistema oppure possono essere offuscati. Utilizzando gli strumenti di debug per identificare i wakelock che non funzionano correttamente e poi cercando il nome del wakelock in questo documento, puoi determinare quale API potrebbe causare il problema e trovare consigli su come ottimizzarne l'utilizzo.

Questo documento descrive i casi d'uso comuni per l'acquisizione dei wakelock, illustra i nomi dei wakelock utilizzati da varie API e librerie e fornisce consigli e best practice per ottimizzare e ridurre l'utilizzo dei wakelock.

AlarmManager

AlarmManager acquisisce i wakelock e li attribuisce all'app chiamante. AlarmManager acquisisce il wakelock quando l'allarme si attiva e rilascia il wakelock al termine dell'esecuzione del metodo onReceive() della trasmissione dell'allarme.

Nomi dei wakelock

AlarmManager crea wakelock con il nome *alarm*. (Gli asterischi fanno parte del nome del wakelock, non rappresentano caratteri jolly.)

Suggerimento

Ti consigliamo di seguire queste pratiche per ottimizzare il comportamento degli allarmi:

  • Consulta la sezione Scegliere il tipo di allarme per decidere tra un allarme inesatto o esatto. Se l'allarme non deve essere preciso, utilizza allarmi inesatti per dare al sistema maggiore flessibilità nella pianificazione, il che può migliorare la durata della batteria.
  • Tieni presente le quote di allarmi imposte dal sistema e progetta la tua app in modo che le rispetti.
  • Evita di eseguire lavori lunghi nel metodo onReceive() e pianifica i worker se è necessaria un'ulteriore elaborazione dopo l'allarme.

Audio e contenuti multimediali

Le API per i contenuti multimediali possono acquisire wakelock durante la registrazione o la riproduzione dell'audio. I wakelock vengono attribuiti all'app di chiamate.

Nomi dei wakelock

Le API per i contenuti multimediali acquisiscono wakelock con vari nomi che iniziano con Audio:

  • AudioBitPerfect: utilizzato per la riproduzione audio USB senza perdita di dati.
  • AudioDirectOut: utilizzato per la riproduzione audio senza perdita di dati su una TV o un dispositivo speciale.
  • AudioDup: utilizzato per la riproduzione delle notifiche durante la connessione tramite Bluetooth o USB.
  • AudioIn: utilizzato per l'acquisizione audio in modalità videocamera quando 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 di film o musica multicanale 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 le applicazioni audio professionali.

Suggerimento

Ti consigliamo di seguire queste pratiche:

  • Non dichiarare nomi di wakelock che iniziano con Audio.
  • Se utilizzi le API per i contenuti multimediali, non dovresti aver bisogno di acquisire direttamente i wakelock; puoi fare affidamento sulle API per acquisire i wakelock necessari.
  • Quando utilizzi le API per i contenuti multimediali, termina la sessione multimediale e il servizio in primo piano associato quando non ne hai più bisogno.

Bluetooth

Le API Bluetooth della piattaforma mantengono principalmente i wakelock del kernel durante le azioni Bluetooth, che non sono attribuibili all'applicazione.

Suggerimento

  • Utilizza l'accoppiamento dei dispositivi complementari per accoppiare i dispositivi Bluetooth ed evitare di acquisire un wakelock manuale durante l'accoppiamento Bluetooth.
  • Consulta le linee guida per la comunicazione in background per capire come eseguire la comunicazione Bluetooth in background.
  • L'utilizzo di WorkManager è spesso sufficiente se non c'è alcun impatto sull'utente per una comunicazione ritardata. Se si ritiene necessario un wakelock manuale, mantienilo solo per la durata dell'attività Bluetooth o dell'elaborazione dei dati dell'attività.

Sensori del dispositivo

Esistono diversi metodi per monitorare i dati dei sensori del dispositivo, come il conteggio dei passi, i dati dell'accelerometro o del giroscopio.

Su Wear OS, utilizza Wear Health Services per recuperare i dati sul dispositivo, come l'altitudine, la frequenza cardiaca e la distanza percorsa.

Se i dati vengono raccolti da altre applicazioni, puoi utilizzare Health Connect in combinazione con WorkManager per recuperarli periodicamente.

Per scenari come il monitoraggio della differenza di passi o della distanza percorsa, puoi utilizzare l'API Recording su mobile in combinazione con WorkManager per recuperare periodicamente i dati. Per accedere ai dati storici sui passi (ad esempio il totale dei passi giornalieri o i passi nelle ultime 6 ore), Health Connect supporta anche il monitoraggio dei passi sul dispositivo per i dispositivi con Android 14 o versioni successive.

In alcune situazioni, potrebbe essere necessario il monitoraggio personalizzato dei sensori del dispositivo utilizzando SensorManager. SensorManager non acquisisce wakelock per conto dell'app, a meno che il sensore non sia un sensore di riattivazione, che può essere identificato utilizzando l'API isWakeUpSensor.

Suggerimento

L'utilizzo dei sensori per la registrazione a frequenze di campionamento elevate può causare un consumo eccessivo della batteria. Ecco alcuni consigli per ridurre il consumo eccessivo della batteria e l'utilizzo dei wakelock:

  • Se monitori il conteggio dei passi o la distanza percorsa, utilizza l' API Recording per registrare i dati in modo efficiente dal punto di vista della batteria. Per i dispositivi con Android 14 o versioni successive, valuta la possibilità di utilizzare Health Connect per accedere ai dati storici del dispositivo e al conteggio dei passi aggregati.
  • Per il monitoraggio passivo dei sensori su Wear OS, utilizza Servizi per la salute di Wear per ottimizzare l'utilizzo della batteria.
  • Quando registri un sensore con SensorManager, definisci un maxReportLatencyUs superiore a 30 secondi per utilizzare la logica di batching dei sensori e ridurre il numero di interruzioni ricevute dall'applicazione. Quando il dispositivo viene riattivato da un altro trigger, ad esempio un'interazione utente, il recupero della posizione o un job programmato, il sistema invierà immediatamente i dati dei sensori memorizzati nella cache.
  • Se la tua app richiede sia i dati sulla posizione sia i dati dei sensori, sincronizza il recupero e l'elaborazione degli eventi. Unendo le letture dei sensori nel breve wakelock mantenuto dal sistema per gli aggiornamenti della posizione, eviti di aver bisogno di un wakelock per mantenere la CPU attiva. Utilizza un worker o un wakelock di breve durata per gestire il caricamento e l'elaborazione di questi dati combinati.

Firebase Cloud Messaging (FCM)

Un wakelock viene acquisito durante la trasmissione di Firebase Cloud Messaging (FCM) all'app. Il wakelock viene rilasciato al termine dell'esecuzione del metodo onMessageReceived() della trasmissione FCM.

Nomi dei wakelock

Quando un messaggio FCM viene ricevuto sul dispositivo, viene mantenuto un breve wakelock con il nome GOOGLE_C2DM. Su Android 16 e versioni successive, il nome del wakelock è GCM_MESSAGE.

Suggerimento

Ti consigliamo di seguire queste pratiche per ottimizzare il comportamento di FCM:

  • Ottimizza la frequenza di invio di FCM.
  • Non utilizzare FCM ad alta priorità a meno che il messaggio non debba essere recapitato immediatamente.
  • Fai in modo che il metodo onMessageReceived() venga completato il più rapidamente possibile o pianifica un worker per continuare l'attività se è necessaria un'ulteriore elaborazione. Per ulteriori informazioni, consulta le linee guida di Firebase.

JobScheduler

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

Nomi dei wakelock

I nomi dei wakelock 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 wakelock con nomi che seguono questo pattern:

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

Gli altri job utilizzano questo pattern:

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

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

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

I job con esecuzione rapida utilizzano questo pattern:

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

I job normali utilizzano questo pattern:

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

Supponiamo che esista un processo 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 wakelock avrebbe il seguente nome:

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

Sui dispositivi con Android 16 QPR2 o versioni successive, il wakelock avrebbe il seguente nome:

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

Suggerimento

  • Non acquisire un wakelock manuale per i casi d'uso di download/ caricamento avviati dall'utente. Utilizza invece l'API User-Initiated Data Transfer (UIDT). Questo è il percorso designato per le attività di trasferimento di dati a lunga esecuzione avviate dall'utente.
  • Se identifichi i wakelock creati da JobScheduler con un elevato utilizzo dei wakelock, potrebbe essere perché hai configurato in modo errato il job in modo che non venga completato in determinati scenari. Valuta la possibilità di analizzare i motivi di interruzione del job, soprattutto se riscontri un'elevata frequenza di STOP_REASON_TIMEOUT.
  • Controlla l'utilizzo delle attività di JobScheduler. In particolare, segui le nostre linee guida per l'ottimizzazione dell'utilizzo della batteria per le API di pianificazione delle attività.

Località

LocationManager e FusedLocationProviderClient utilizzano i wakelock per acquisire e fornire la posizione del dispositivo. I wakelock vengono 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*

Suggerimento

  • Consulta le nostre linee guida per ottimizzare l'utilizzo della posizione. Valuta la possibilità di implementare timeout, sfruttare il batching delle richieste di posizione o utilizzare gli aggiornamenti passivi della posizione.
  • Evita di acquisire un wakelock continuo separato per la memorizzazione nella cache dei dati sulla posizione, in quanto è ridondante e deve essere rimosso. Quando richiedi aggiornamenti della posizione utilizzando le API FusedLocationProvider o LocationManager, il sistema attiva automaticamente la riattivazione del dispositivo durante il callback dell'evento di posizione. Memorizza invece gli eventi di posizione in memoria o nell'archiviazione ed elaborali periodicamente utilizzando WorkManager.

Messaggistica remota

Questa sezione descrive gli scenari che coinvolgono la messaggistica remota in cui le app potrebbero dover mantenere le connessioni o reagire agli eventi di altri dispositivi, il che potrebbe influire sull'utilizzo dei wakelock. I casi d'uso comuni includono:

  • App complementari per il monitoraggio di video o audio che devono monitorare gli eventi che si verificano su un dispositivo esterno connesso tramite una rete locale.
  • App di messaggistica che mantengono una connessione socket di rete con una variante desktop.

La maggior parte delle riattivazioni in questi scenari di messaggistica remota sono wakelock del kernel. Poiché i wakelock del kernel non sono attribuiti all'app, non sono presenti nomi di wakelock associati da elencare qui.

Suggerimento

  • Se gli eventi di rete possono essere elaborati sul lato server, utilizza FCM per ricevere informazioni sul client. Puoi scegliere di pianificare un worker con esecuzione rapida se è necessaria un'ulteriore elaborazione dei dati FCM.
  • Se gli eventi devono essere elaborati sul lato client utilizzando una connessione socket, non è necessario un wakelock per ascoltare le interruzioni degli eventi. Quando i pacchetti di dati arrivano alla radio Wi-Fi o cellulare, l'hardware della radio attiva un'interruzione sotto forma di wakelock del kernel. Puoi quindi scegliere di pianificare un worker o acquisire un wakelock per elaborare i dati.
  • Ad esempio, se utilizzi ktor-network per ascoltare i pacchetti di dati su un socket di rete, devi acquisire un wakelock solo quando i pacchetti sono stati consegnati al client.

WorkManager

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

Nomi dei wakelock

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

Android 15 e versioni precedenti

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

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

Le attività con esecuzione rapida creano wakelock con nomi che seguono questo pattern:

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

Le attività normali seguono questo pattern:

*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 worker con esecuzione rapida denominato BackupFileWorker. Il nome del pacchetto è com.example.app.

Sui dispositivi con Android 15 o versioni precedenti, il wakelock avrebbe il seguente nome:

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

Sui dispositivi con Android 16 QPR2 o versioni successive e che utilizzano WorkManager 2.10.0+, il wakelock avrebbe il seguente nome:

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

Suggerimento

  • Esegui l'upgrade della versione di WorkManager all'ultima versione stabile per rendere i tag dei wakelock più dettagliati su Android 16 QPR2 o versioni successive.
  • Controlla l'utilizzo dei worker di WorkManager. In particolare, verifica che segua le nostre linee guida per l'ottimizzazione dell'utilizzo della batteria per le API di pianificazione delle attività. Per rendere i tag dei wakelock più dettagliati su Android 16 QPR2 o versioni successive, utilizza il setTraceTag metodo sul worker per aggiungere ulteriori informazioni di debug, ad esempio la classe che ha pianificato il worker.
  • Se identifichi i wakelock creati da WorkManager con un elevato utilizzo dei wakelock, potrebbe essere perché hai configurato in modo errato il worker in modo che non venga completato in determinati scenari. Valuta la possibilità di analizzare i motivi di interruzione del worker, soprattutto se riscontri un'elevata frequenza di STOP_REASON_TIMEOUT.
  • Oltre a registrare i motivi di interruzione del worker, consulta la nostra documentazione sul debug dei worker. Inoltre, valuta la possibilità di raccogliere e analizzare le tracce di sistema per capire quando vengono acquisiti e rilasciati i wakelock.

_UNKNOWN

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

Suggerimento

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