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 associate 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 delle 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 comuni di wakelock 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 la sveglia suona e lo rilascia quando l'esecuzione del metodo onReceive() della trasmissione della sveglia termina.

Nomi dei wakelock

AlarmManager crea wakelock 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 seguire queste pratiche:

  • Consulta la sezione Scegli il tipo di sveglia per decidere tra una sveglia imprecisa o esatta. Se la sveglia non deve essere precisa, utilizza sveglie imprecise per offrire al sistema una maggiore flessibilità nella programmazione, 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'ulteriore elaborazione dopo la sveglia.

Audio e contenuti multimediali

Le API multimediali possono acquisire wakelock durante la registrazione o la riproduzione di audio. I wakelock sono attribuiti all'app di chiamate.

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 il dispositivo è 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 prolungata di sola musica, 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 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 le applicazioni audio professionali.

Suggerimento

Consigliamo le seguenti pratiche:

  • Non dichiarare nomi di wakelock che iniziano con Audio.
  • Se utilizzi le API Media, non dovresti aver bisogno di acquisire i wakelock direttamente; puoi fare affidamento sulle API per acquisire i wakelock necessari per te.
  • 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 wakelock del kernel durante le azioni Bluetooth, che non sono attribuibili all'applicazione.

Suggerimento

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

Sensori del dispositivo

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

Su Wear OS, utilizza Servizi per la salute di Wear per acquisire dati del dispositivo come altitudine, frequenza cardiaca e 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 variazione dei 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 wakelock per conto dell'app, a meno che il sensore non sia un sensore di attivazione, che può essere identificato utilizzando l'API isWakeUpSensor.

Suggerimento

L'utilizzo di sensori per registrare a frequenze di campionamento elevate può consumare notevolmente la batteria. Ecco alcuni consigli per ridurre il consumo 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 da ottimizzare il consumo della batteria. Per i dispositivi con Android 14 o versioni successive, valuta l'utilizzo di 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 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 raggruppamento dei sensori e ridurre il numero di interruzioni ricevute dall'applicazione. Quando il dispositivo viene successivamente riattivato da un altro trigger, ad esempio un'interazione dell'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 attiva la CPU. 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 un messaggio Firebase Cloud Messaging (FCM) all'app. Il wakelock viene rilasciato al termine dell'esecuzione del metodo di trasmissione FCM onMessageReceived().

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 di seguire queste 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 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 di attività in background. I wakelock sono 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 sono in esecuzione 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>

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 processi rapidi 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 wake lock si chiamerebbe:

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

Sui dispositivi con Android 16 QPR2 o versioni successive, il wake lock 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 di dati di lunga durata avviate dall'utente.
  • Se identifichi wakelock creati da JobScheduler con un utilizzo elevato, è possibile che tu abbia 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, in particolare se riscontri un numero elevato di occorrenze di STOP_REASON_TIMEOUT.
  • Controlla l'utilizzo delle attività di 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 wakelock per acquisire e fornire la posizione del dispositivo. I wakelock 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 indicazioni per ottimizzare l'utilizzo della posizione. Valuta la possibilità di implementare i timeout, sfruttare il raggruppamento delle richieste di posizione o utilizzare gli aggiornamenti della posizione passivi.
  • Evita di acquisire un wakelock separato e continuo 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 l'attivazione del dispositivo durante il callback dell'evento di posizione. Archivia invece gli eventi di geolocalizzazione in memoria o nello spazio di archiviazione ed elaborali periodicamente utilizzando WorkManager.

Messaggistica remota

Questa sezione illustra gli scenari che coinvolgono la messaggistica remota in cui le app potrebbero dover mantenere le connessioni o reagire agli eventi di altri dispositivi, con un potenziale impatto sull'utilizzo dei wakelock. 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 per computer.

La maggior parte dei wakeup 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 lato server, utilizza FCM per ricevere informazioni sul client. Puoi scegliere di pianificare un worker accelerato 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 al segnale radio Wi-Fi o cellulare, l'hardware del segnale 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 i wakelock durante l'esecuzione delle attività in background. I wakelock sono 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 sono in esecuzione.

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à accelerate creano wakelock 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 worker con priorità alta denominato BackupFileWorker. Il nome del pacchetto è com.example.app.

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

*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 wake lock si chiamerà:

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

Suggerimento

  • Esegui l'upgrade della versione di WorkManager alla versione stabile più recente per rendere i tag di wakelock più dettagliati su Android 16 QPR2 o versioni successive.
  • Controlla l'utilizzo dei worker di WorkManager. In particolare, verifica che segua le nostre indicazioni per l'ottimizzazione dell'utilizzo della batteria per le API di pianificazione delle attività. Per rendere i tag di wakelock più dettagliati su Android 16 QPR2 o versioni successive, utilizza il metodo setTraceTag sul worker per aggiungere ulteriori informazioni di debug, ad esempio quale classe ha pianificato il worker.
  • Se identifichi wakelock creati da WorkManager con un utilizzo elevato, è possibile che tu abbia configurato in modo errato il worker in modo che non venga completato in determinati scenari. Valuta la possibilità di analizzare i motivi dell'arresto dei worker, in particolare se riscontri un numero elevato di occorrenze di STOP_REASON_TIMEOUT.
  • Oltre a registrare i motivi dell'arresto dei worker, consulta la nostra documentazione sul debug dei worker. Inoltre, valuta la possibilità di raccogliere e analizzare il tracciamento del sistema per capire quando i wakelock vengono acquisiti e rilasciati.

_UNKNOWN

Se gli strumenti di debug ritengono che il nome di un wakelock contenga informazioni che consentono l'identificazione personale (PII), non mostrano 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.