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. L'utilizzo errato dell'API può causare il flagging della tua app per l'utilizzo eccessivo di wakelock, anche se non acquisisci esplicitamente wakelock.

Questo documento elenca alcuni nomi comuni di wakelock che potresti riscontrare quando utilizzi gli strumenti di debug dei wakelock o nei report di Vitals. Questi nomi possono provenire da un'API di sistema o di libreria oppure potrebbero essere offuscati. Utilizzando gli strumenti di debug per identificare i wakelock che non funzionano correttamente e 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 di wakelock, fornendo dettagli sui nomi dei wakelock utilizzati da varie API e librerie e fornendo 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 la sveglia suona e lo rilascia al termine dell'esecuzione del metodo onReceive() di trasmissione della sveglia.

Nomi dei wakelock

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

Suggerimento

Per ottimizzare il comportamento degli allarmi, ti consigliamo di procedere come segue:

  • Consulta la sezione Scegliere il tipo di sveglia per decidere tra una sveglia approssimativa o esatta. Se la sveglia non deve essere precisa, utilizza sveglie non esatte per dare al sistema più flessibilità nella pianificazione, il che può migliorare la durata della batteria.
  • Tieni presente le quote di sveglie imposte dal sistema e progetta la tua app in modo che le rispetti.
  • Evita di eseguire operazioni lunghe nel metodo onReceive() e pianifica i worker se è necessaria un'elaborazione aggiuntiva dopo la sveglia.

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 sono applicabili.
  • 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.

Suggerimento

Ti consigliamo di procedere come segue:

  • Non dichiarare nomi wakelock che iniziano con Audio.
  • Se utilizzi le API media, 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 e il servizio in primo piano associato quando non ne hai più bisogno.

Bluetooth

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

Suggerimento

  • Utilizza l'accoppiamento del dispositivo complementare per accoppiare i dispositivi Bluetooth ed evitare di acquisire un blocco di riattivazione manuale durante l'accoppiamento Bluetooth.
  • Consulta le indicazioni per comunicare in background per capire come eseguire la comunicazione Bluetooth in background.
  • L'utilizzo di WorkManager è spesso sufficiente se non vi è alcun impatto sugli utenti in caso di comunicazione ritardata. Se un wakelock manuale è ritenuto necessario, mantienilo solo per la durata dell'attività Bluetooth o dell'elaborazione dei dati dell'attività.

Sensori 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 acquisire dati del dispositivo come altitudine, battito cardiaco e distanza percorsa.

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

Per scenari come il monitoraggio della variazione di passi o della distanza percorsa, puoi utilizzare l'API Recording su dispositivi mobili 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 determinate situazioni, potrebbe essere necessario il monitoraggio personalizzato dei sensori del dispositivo utilizzando SensorManager. SensorManager non acquisisce wake lock 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 registrare a frequenze di campionamento elevate può scaricare notevolmente la batteria. Ecco alcuni suggerimenti per ridurre il consumo della batteria e l'utilizzo del blocco di riattivazione:

  • Se monitori il numero di passi o la distanza percorsa, utilizza l'API Recording per registrare i dati in modo efficiente dal punto di vista del consumo 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 aggregato.
  • Per il monitoraggio passivo dei sensori su Wear OS, utilizza Wear Health Services per ottimizzare l'utilizzo della batteria.
  • Quando registri un sensore con SensorManager, definisci un maxReportLatencyUs superiore a 30 secondi per utilizzare la logica di raggruppamento 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 invia immediatamente i dati dei sensori memorizzati nella cache.
  • Se la tua app richiede sia i dati sulla posizione sia quelli dei sensori, sincronizza il recupero e l'elaborazione degli eventi. Unendo le letture dei sensori al wakelock breve che il sistema mantiene per gli aggiornamenti della posizione, eviti di dover utilizzare 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 Message (FCM)

Un wakelock viene acquisito durante la distribuzione di una trasmissione Firebase Cloud Messaging (FCM) all'app. Il wakelock viene rilasciato al termine dell'esecuzione del metodo onMessageReceived() di 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

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.
  • 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 saperne di più, consulta le indicazioni di Firebase.

JobScheduler

I job 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 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 wake lock con nomi che seguono questo pattern:

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

Altri lavori utilizzano questo pattern:

*job*/@<name_space>@/<package_name>/<classname>
Android 16 QPR2 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 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 si chiamerà:

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

Sui dispositivi con Android 16 QPR2 o versioni successive, il wakelock si chiamerà:

*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 dei dati a esecuzione prolungata avviate dall'utente.
  • Se identifichi wakelock creati da JobScheduler con un utilizzo elevato 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'alta frequenza di STOP_REASON_TIMEOUT.
  • 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à.

Località

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*

Suggerimento

  • Consulta le nostre linee guida per ottimizzare l'utilizzo della posizione. Valuta la possibilità di implementare timeout, utilizzare il batching delle richieste di localizzazione 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 localizzazione. Memorizza invece gli eventi di localizzazione nella memoria o nell'archivio ed elaborali periodicamente utilizzando WorkManager.

Messaggistica remota

Questa sezione descrive scenari che coinvolgono la messaggistica remota in cui le app potrebbero dover mantenere le connessioni o reagire a eventi provenienti da altri dispositivi, con un potenziale impatto sull'utilizzo del wake lock. I casi d'uso comuni includono:

  • App complementari di monitoraggio 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 dei risvegli in questi scenari di messaggistica remota sono blocchi di riattivazione 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 lato server, utilizza FCM per ricevere informazioni sul client. Puoi scegliere di pianificare un worker rapido se è necessario un ulteriore trattamento dei dati FCM.
  • Se gli eventi devono essere elaborati lato client utilizzando una connessione socket, non è necessario un wakelock per rimanere in ascolto delle interruzioni degli eventi. Quando i pacchetti di dati arrivano alla radio Wi-Fi o cellulare, l'hardware della radio attiva un interrupt sotto forma di blocco di riattivazione del kernel. A questo punto, puoi scegliere di pianificare un worker o acquisire un wakelock per elaborare i dati.
  • Ad esempio, se utilizzi ktor-network per rimanere in ascolto dei pacchetti di dati su un socket di rete, devi acquisire un wakelock solo quando i pacchetti sono stati inviati al client.

WorkManager

I worker di WorkManager 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 wakelock acquisiti da WorkManager dipendono dalla versione del sistema Android su cui vengono eseguiti.

Android 15 e versioni precedenti

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

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

Le attività rapide creano wake lock 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 denominato BackupFileWorker. Il nome del pacchetto è com.example.app.

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

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

Sui dispositivi con Android 16 QPR2 o versioni successive che utilizzano WorkManager 2.10.0+, il wakelock verrà denominato:

*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 di wakelock più dettagliati su Android 16 QPR2 o versioni successive.
  • Controlla l'utilizzo dei worker WorkManager. In particolare, verifica che segua le nostre indicazioni per ottimizzare l'utilizzo della batteria per le API di pianificazione delle attività. Per rendere più dettagliati i tag wakelock su Android 16 QPR2 o versioni successive, utilizza il metodo setTraceTag sul worker per aggiungere ulteriori informazioni di debug, ad esempio la classe che ha pianificato il worker.
  • Se identifichi wakelock creati da WorkManager con un utilizzo elevato, il problema potrebbe essere dovuto a una configurazione errata del worker che non viene completato in determinati scenari. Valuta la possibilità di analizzare i motivi di interruzione del worker, soprattutto se noti un'alta frequenza di STOP_REASON_TIMEOUT.
  • Oltre a registrare i motivi di interruzione dei 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 acquisite e rilasciate le sveglie.

_UNKNOWN

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

Suggerimento

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