Identificare e ottimizzare i casi d'uso di wake lock

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

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 wake lock che non funzionano correttamente e cercando il nome del wake lock 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 wake lock, fornendo dettagli sui nomi dei wake lock utilizzati da varie API e librerie e fornendo consigli e best practice per ottimizzare e ridurre l'utilizzo dei wake lock.

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() di 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

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 l'allarme.

Audio e contenuti multimediali

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

Nomi dei wakelock

Le API 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.

Consiglio

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.

Consiglio

  • 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 la comunicazione 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 wake lock manuale è ritenuto necessario, 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 acquisire dati del dispositivo come altitudine, battito cardiaco e distanza percorsa.

Se i dati vengono raccolti da altre applicazioni, puoi utilizzare Connessione Salute 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), Connessione Salute 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.

Consiglio

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 Connessione Salute 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 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 pianificato, 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 breve wakelock 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 wake lock di breve durata per gestire il caricamento e l'elaborazione di questi dati combinati.

Firebase Cloud Message (FCM)

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

Nomi dei wakelock

Quando un messaggio FCM viene ricevuto sul dispositivo, viene mantenuta una breve sospensione con il nome GOOGLE_C2DM. Su Android 16 e versioni successive, il nome della sospensione è GCM_MESSAGE.

Consiglio

Per ottimizzare il comportamento di FCM, ti consigliamo di adottare 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 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 pattern:

*job*/@<name_space>@/<package_name>/<classname>
Android 16.1 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 blocco di riattivazione si chiamerà:

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

Sui dispositivi con Android 16.1 o versioni successive, il wake lock si chiamerà:

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

Consiglio

  • Non acquisire un wake lock 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 wake lock creati da JobScheduler con un utilizzo elevato dei wake lock, 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à.

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

  • 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 aggiornamenti passivi della posizione.
  • Evita di acquisire un blocco di riattivazione 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, influenzando potenzialmente l'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 wake lock del kernel non sono attribuiti all'app, non sono presenti nomi di wake lock associati da elencare qui.

Consiglio

  • 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 wake lock per ascoltare le 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 wake lock del kernel. A questo punto, puoi scegliere di pianificare un worker o acquisire un wake lock per elaborare i dati.
  • Ad esempio, se utilizzi ktor-network per ascoltare i pacchetti di dati su un socket di rete, devi acquisire un wake lock solo quando i pacchetti sono stati inviati al client.

WorkManager

I worker 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 in esecuzione.

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.1 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 blocco di riattivazione si chiamerà:

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

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

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

Consiglio

  • Esegui l'upgrade della versione di WorkManager all'ultima versione stabile per rendere i tag di wake lock più dettagliati su Android 16.1 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 di riattivazione su Android 16.1 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 wake lock creati da WorkManager con un utilizzo elevato, 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, in particolare se riscontri 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 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.