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.

Negli scenari in cui un wake lock viene acquisito da altre API, devi evitare l'acquisizione manuale del wake lock.

Questo documento elenca alcuni nomi di wakelock comuni che potresti visualizzare quando utilizzi gli strumenti di debug wakelock. Potresti anche visualizzare questi nomi in un report di 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 che utilizzi 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 tratta gli scenari in cui potrebbero essere creati blocchi di riattivazione. 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() 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

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

  • Utilizza AlarmManager per ottimizzare la frequenza di programmazione degli allarmi.
  • Utilizza le sveglie di tipo RTC_WAKEUP (che riattivano il dispositivo) solo quando necessario.
  • Riduci al minimo l'uso di allarmi ed evita di svolgere lavori lunghi nel 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 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 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ù.

Bluetooth

Le API Bluetooth della piattaforma non mantengono alcun wake lock attribuibile all'applicazione durante le azioni Bluetooth. Per verificare che il trasporto Bluetooth avvenga in background, pianifica un'attività utilizzando WorkManager.

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 comunicare in background per capire come eseguire la comunicazione Bluetooth in background.
  • Se un wake lock manuale è ritenuto necessario, mantienilo attivo solo per la durata dell'azione Bluetooth.

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 Connessione Salute in combinazione con WorkManager per recuperare 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 i dati.

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 il monitoraggio passivo dei sensori su Wear OS, utilizza Wear Health Services per ottimizzare l'utilizzo della batteria.
  • Riduci la frequenza del sensore a meno di 200 Hz.
  • 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.
  • Evita di mantenere un wake lock a lungo per l'intera durata del monitoraggio dei sensori, pianifica invece gli allarmi utilizzando AlarmManager per eseguire il polling dei dati dei sensori ogni 30 secondi o più.

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

Viene acquisita una sospensione della riproduzione 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 pattern:

*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 blocco di riattivazione si chiamerebbe:

*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.
  • Se utilizzi le API di localizzazione, non devi acquisire direttamente i wake lock. Puoi fare affidamento sulle API per acquisire i wake lock necessari.

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 blocco di riattivazione si chiamerebbe:

*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

_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.