Ottimizza la batteria della tua app utilizzando la metrica wakelock di Android vitals

La durata della batteria è un aspetto fondamentale dell'esperienza utente e i wake lock svolgono un ruolo importante. Li utilizzi in modo eccessivo? In questo post del blog esploreremo cosa sono i wake lock, quali sono alcune best practice per utilizzarli e come puoi comprendere meglio il comportamento della tua app con la metrica di Play Console.

Utilizzo eccessivo di wakelock parziali in Android vitals

Play Console ora monitora il consumo della batteria, con particolare attenzione all'utilizzo eccessivo di wakelock parziali, come indicatore chiave di rendimento.

Questa funzionalità aumenta l'importanza dell'efficienza della batteria insieme agli indicatori di stabilità delle metriche principali esistenti: arresti anomali ed errori ANR percepiti dall'utente eccessivi. Abbiamo definito una soglia relativa alle prestazioni scadenti per i wakelock eccessivi. A partire dal 1° marzo 2026, se il tuo titolo non soddisfa questa soglia di qualità, potremmo escluderlo dalle piattaforme di scoperta in primo piano, come i consigli. In alcuni casi, potremmo visualizzare un avviso nella scheda dello Store per indicare agli utenti che la tua app potrebbe causare un consumo eccessivo della batteria.

L'avviso di blocco della riattivazione eccessivo nella panoramica di Android vitals.

Per i dispositivi mobili, la metrica Android vitals si applica ai wakelock non esenti acquisiti mentre lo schermo è spento e l'app è in background o esegue un servizio in primo piano. Android vitals considera eccessivo l'utilizzo di wakelock parziali se:

• I wake lock vengono mantenuti per almeno due ore in un periodo di 24 ore.
• Influisce su più del 5% delle sessioni della tua app, in media su 28 giorni.

I wake lock creati dalle API avviate dall'utente per audio, posizione e JobScheduler sono esenti dal calcolo dei wake lock.

Informazioni sui wakelock

Un wake lock è un meccanismo che consente a un'app di mantenere in esecuzione la CPU di un dispositivo anche quando l'utente non interagisce attivamente con il dispositivo. 

Un wakelock parziale mantiene la CPU in esecuzione anche se lo schermo è spento, impedendo alla CPU di entrare in uno stato di "sospensione" a basso consumo energetico. Un wakelock completo mantiene in esecuzione sia lo schermo che la CPU.

Esistono due metodi per acquisire i wakelock parziali:

• L'app acquisisce e rilascia manualmente il wake lock utilizzando le API PowerManager per un caso d'uso specifico. Spesso, questo viene acquisito insieme a un servizio in primo piano, un'API del ciclo di vita della piattaforma destinata a un'operazione percepibile dall'utente.
• In alternativa, il blocco di riattivazione viene acquisito da un'altra API e attribuito all'app a causa dell'utilizzo dell'API. Scopri di più nella sezione delle best practice.

Sebbene i wake lock siano necessari per attività come il completamento del download avviato dall'utente di un file di grandi dimensioni, il loro utilizzo eccessivo o improprio può causare un consumo significativo della batteria. Abbiamo riscontrato casi in cui le app mantengono i wake lock per ore o non li rilasciano correttamente, il che ha portato a reclami degli utenti per un consumo significativo della batteria anche quando non interagiscono con l'app.

Best practice per l'utilizzo dei wakelock

Prima di esaminare come eseguire il debug dell'utilizzo eccessivo di wake lock, assicurati di seguire le best practice per i wake lock. 

Considera queste quattro domande fondamentali.

1. Hai preso in considerazione opzioni alternative di riattivazione?

Prima di prendere in considerazione l'acquisizione di un wake lock parziale manuale, segui questo diagramma di flusso decisionale:

Diagramma di flusso per decidere quando acquisire manualmente un wake lock

1. Lo schermo deve rimanere acceso?
   • Sì: consulta la documentazione relativa alla funzionalità Mantieni schermo attivo
2. L'applicazione esegue un servizio in primo piano?
   • No: non è necessario acquisire manualmente un wake lock.
3. È dannoso per l'esperienza utente se il dispositivo viene sospeso?
   • No: ad esempio, l'aggiornamento di una notifica dopo il riattivazione del dispositivo non richiede un wake lock.
   • Sì: se è fondamentale impedire la sospensione del dispositivo, ad esempio per la comunicazione continua con un dispositivo esterno, procedi.
4. Esiste già un'API che mantiene attivo il dispositivo per tuo conto?
   • Puoi utilizzare la documentazione Identificare i wakelock creati da altre API per identificare gli scenari in cui i wakelock vengono creati da altre API, ad esempio LocationManager.
   • Se non esistono API, vai alla domanda finale.
5. Se hai risposto a tutte queste domande e hai stabilito che non esiste un'alternativa, devi procedere con l'acquisizione manuale di un wake lock.

2. Stai assegnando il nome al wakelock correttamente?

Quando acquisisci manualmente i wake lock, la denominazione corretta è importante per il debug:

• Non includere informazioni che consentono l'identificazione personale (PII) nel nome, ad esempio indirizzi email. Se vengono rilevate informazioni di identificazione personale, il wake lock viene registrato come _UNKNOWN, ostacolando il debug.
• Non assegnare un nome al wake lock in modo programmatico utilizzando nomi di classi o metodi, in quanto questi possono essere offuscati da strumenti come Proguard. Utilizza invece una stringa hardcoded.
• Non aggiungere contatori o identificatori unici ai tag di riattivazione. Lo stesso tag deve essere utilizzato ogni volta che viene eseguito il wake lock per consentire al sistema di aggregare l'utilizzo per nome, rendendo più facile il rilevamento di comportamenti anomali.

3. Il wake lock acquisito viene sempre rilasciato?

Se acquisisci un wakelock manualmente, assicurati che il rilascio del wakelock venga sempre eseguito. Se non viene rilasciato un wake lock, la batteria può scaricarsi rapidamente. 

Ad esempio, se viene generata un'eccezione non rilevata durante processingWork(), la chiamata release() potrebbe non verificarsi mai. In alternativa, puoi utilizzare un blocco try-finally per garantire il rilascio del wakelock, anche se si verifica un'eccezione.

Inoltre, puoi aggiungere un timeout al wake lock per assicurarti che venga rilasciato dopo un periodo specifico, impedendone la detenzione a tempo indeterminato.

fun processingWork() {
    wakeLock.apply {
        try {
            acquire(60 * 10 * 1000) // timeout after 10 minutes
            doTheWork()
        } finally {
            release()
        }
    }
}

4. Puoi ridurre la frequenza di riattivazione?

Per le richieste di dati periodiche, ridurre la frequenza con cui l'app riattiva il dispositivo è fondamentale per l'ottimizzazione della batteria. Alcuni esempi di riduzione della frequenza di riattivazione includono:

• WorkManager:aumenta l'intervallo periodico in PeriodicWorkRequest.
• SensorManager: sfrutta il batch specificando maxReportLatencyMs durante la registrazione del listener.
• Fused Location Provider:
  • Riduci la frequenza di recupero della posizione utilizzando getLastLocation per la posizione più recente memorizzata nella cache.
  • Utilizza setPriority(PRIORITY_PASSIVE) per un metodo di aggiornamento che consuma meno batteria.
  • Inoltre, puoi sfruttare il meccanismo di raggruppamento delle posizioni impostando un intervallo di aggiornamento minimo con setMinUpdateIntervalMillis.

Per ulteriori dettagli, consulta la documentazione sulle best practice per i wakelock.

Debug dell'utilizzo eccessivo dei wakelock

Anche con le migliori intenzioni, può verificarsi un utilizzo eccessivo del blocco riattivazione. Se la tua app viene segnalata in Play Console, ecco come eseguire il debug:

Identificazione iniziale con Play Console

La dashboard dei wake lock parziali eccessivi di Android vitals fornisce suddivisioni dei nomi dei wake lock non esenti associati alla tua app, mostrando le sessioni e le durate interessate. Ti ricordiamo di utilizzare la documentazione per identificare se il nome del wakelock è detenuto dall'app o da un'altra API.

La dashboard Android vitals per i wakelock parziali eccessivi è stata spostata verso il basso fino alla sezione delle suddivisioni per visualizzare i tag dei wakelock eccessivi.

Debug dei wake lock eccessivi mantenuti da worker/job

Puoi identificare i wake lock mantenuti dal worker con questo nome:

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

L'elenco completo delle varianti dei nomi dei wake lock mantenuti dal worker è disponibile nella documentazione. Per eseguire il debug di questi wake lock, puoi utilizzare lo strumento di controllo delle attività in background per eseguire il debug in locale o sfruttare getStopReason per eseguire il debug dei problemi sul campo. 

Android Studio Background Task Inspector

Acquisizione dello schermo di Background Task Inspector, in cui è stato possibile identificare un worker "WeatherSyncWorker" che ha eseguito di frequente nuovi tentativi senza esito.

Per il debug locale dei problemi di WorkManager, utilizza questo strumento su un emulatore o un dispositivo connesso (livello API 26+). Mostra un elenco di worker e i relativi stati (terminato, in esecuzione, in coda), consentendoti di esaminare i dettagli e comprendere le catene di worker. 

Ad esempio, può rivelare se un worker non funziona correttamente o riprova spesso a causa di limitazioni del sistema. 

Per ulteriori dettagli, consulta la documentazione di Background Task Inspector.

WorkManager getStopReason

Per il debug sul campo dei worker con blocchi di riattivazione eccessivi, utilizza WorkInfo.getStopReason() su WorkManager 2.9.0 o versioni successive oppure per JobScheduler, JobParameters.getStopReason() disponibile su SDK 31 e versioni successive. 

Questa API consente di registrare il motivo per cui un worker si è arrestato (ad es. STOP_REASON_TIMEOUT, STOP_REASON_QUOTA), individuando problemi come timeout frequenti dovuti all'esaurimento della durata del runtime.

backgroundScope.launch {
    WorkManager.getInstance(context)
        .getWorkInfoByIdFlow(workRequest.id)
        .collect { workInfo ->
            logStopReason(workRequest.id, workInfo?.stopReason)
        }
}

Per maggiori dettagli, consulta Ottimizzare l'utilizzo della batteria per le API di pianificazione delle attività.

Debug di altri tipi di wakelock eccessivi

Per scenari più complessi che coinvolgono wake lock mantenuti manualmente o API che mantengono il wake lock, ti consigliamo di utilizzare la raccolta delle tracce di sistema per il debug.

Raccolta delle tracce di sistema

Una traccia di sistema è un potente strumento di debug che acquisisce un record dettagliato dell'attività di sistema in un periodo di tempo, fornendo informazioni sullo stato della CPU, sull'attività dei thread, sull'attività di rete e su metriche relative alla batteria come la durata del job e l'utilizzo del wake lock.

Puoi acquisire una traccia di sistema utilizzando diversi metodi: 

• Utilizzo dello strumento a riga di comando system trace
• Utilizzo di Android Studio CPU Profiler
• Utilizzo della UI di Perfetto
• Registrazione manuale di una traccia sul dispositivo direttamente dalle opzioni sviluppatore. 

Attiva la categoria Atrace "power:PowerManagement" nell'interfaccia utente di Perfetto nella scheda App e servizi Android. 

Indipendentemente dal metodo scelto, è fondamentale assicurarsi di raccogliere la categoria Atrace "power:PowerManagement" per consentire la visualizzazione delle tracce dello stato del dispositivo. 

Perfetto UI inspection and SQL analysis

Le tracce di sistema possono essere aperte e ispezionate nell'interfaccia utente di Perfetto. Quando apri la traccia, visualizzi una visualizzazione di vari processi su una sequenza temporale. Le tracce su cui ci concentreremo in questa guida sono quelle in "Stato del dispositivo".

Blocca le tracce in "Stato dispositivo", ad esempio "App principale", "Stato schermo", "Wake lock lunghi" e "Job", per identificare visivamente le sezioni di wake lock di lunga durata.

Ogni blocco elenca il nome dell'evento, la data di inizio e la data di fine. In Perfetto, questo elemento è chiamato slice.

Per un'analisi scalabile di più tracce, puoi utilizzare l'analisi SQL di Perfetto. Una query SQL può trovare tutti i blocchi di riattivazione ordinati per durata, contribuendo a identificare i principali responsabili dell'utilizzo eccessivo.

Ecco una query di esempio che somma tutti i tag di riattivazione che si sono verificati nella traccia di sistema, ordinati in base alla durata totale:

SELECT slice.name as name, track.name as track_name,SUM(dur / 100000) as total_dur_ms
FROM slice
JOIN track ON slice.track_id = track.id
WHERE track.name = 'WakeLocks'GROUP BY slice.name, track.name
ORDER BY total_dur_ms DESC

Utilizzare ProfilingManager per la raccolta delle tracce sul campo

Per i problemi difficili da riprodurre, ProfilingManager (aggiunto nell'SDK 35) è un'API programmatica che consente agli sviluppatori di raccogliere tracce di sistema sul campo con trigger di inizio e fine. Offre un maggiore controllo sui punti di attivazione iniziale e finale per la raccolta dei profili e applica la limitazione della frequenza a livello di sistema per evitare un impatto sulle prestazioni del dispositivo. 

Consulta la documentazione di ProfilingManager per ulteriori passaggi su come implementare la raccolta delle tracce di sistema sul campo, inclusi i passaggi per acquisire una traccia, analizzare i dati di profilazione e utilizzare i comandi di debug locali.

Le tracce di sistema raccolte utilizzando ProfilingManager avranno un aspetto simile a quelle raccolte manualmente, ma i processi di sistema e altri processi dell'app vengono oscurati dalla traccia.

Conclusione

La metrica wakelock parziali eccessivi in Android vitals è solo una piccola parte del nostro impegno costante a supportare gli sviluppatori nella riduzione del consumo della batteria e nel miglioramento della qualità delle app. 

Comprendendo e implementando correttamente i wake lock, puoi ottimizzare in modo significativo le prestazioni della batteria della tua app. L'utilizzo di API alternative, il rispetto delle best practice per i wake lock e l'utilizzo di potenti strumenti di debug come Background Task Inspector, le tracce di sistema e ProfilingManager sono fondamentali per garantire il successo della tua app su Google Play.