La durata della batteria è un aspetto fondamentale dell'esperienza utente e i wakelock svolgono un ruolo importante. Li stai utilizzando in modo eccessivo? In questo post del blog esploreremo cosa sono i wakelock, 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 dei wakelock parziali in Android vitals

Play Console ora monitora il consumo eccessivo della batteria, con un focus sull'utilizzo eccessivo dei wakelock parziali, come indicatore chiave del rendimento.

Questa funzionalità aumenta l'importanza dell'efficienza della batteria insieme agli indicatori di stabilità delle metriche principali esistenti: arresti anomali e ANR eccessivi percepiti dagli utenti. 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 superfici di rilevamento in primo piano, come i consigli. In alcuni casi, potremmo mostrare un avviso nella scheda dello Store per indicare agli utenti che la tua app potrebbe causare un consumo eccessivo della batteria.

L'avviso relativo ai wakelock eccessivi nella panoramica di Android vitals.

Per i dispositivi mobili, la metrica di 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 dei wakelock parziali se:

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

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

Informazioni sui wakelock

Un wakelock è 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 sia la CPU.

Esistono due metodi per acquisire i wakelock parziali:

• L'app acquisisce e rilascia manualmente il wakelock utilizzando le API PowerManager per un caso d'uso specifico, spesso in combinazione con un servizio in primo piano, un'API del ciclo di vita della piattaforma destinata a operazioni percepibili dall'utente.
• In alternativa, il wakelock viene acquisito da un'altra API e attribuito all'app a causa dell'utilizzo dell'API. Per saperne di più, consulta la sezione sulle best practice.

Sebbene i wakelock siano necessari per attività come il completamento del download di un file di grandi dimensioni avviato dall'utente, il loro utilizzo eccessivo o improprio può causare un consumo eccessivo della batteria. Abbiamo riscontrato casi in cui le app mantengono i wakelock per ore o non riescono a rilasciarli correttamente, causando reclami degli utenti per un consumo eccessivo 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 dei wakelock, assicurati di seguire le best practice per i wakelock. 

Considera queste quattro domande fondamentali.

1. Hai preso in considerazione opzioni alternative per i wakelock?

Prima di prendere in considerazione l'acquisizione manuale di un wakelock parziale, segui questo diagramma di flusso per il processo decisionale:

Diagramma di flusso per decidere quando acquisire manualmente un wakelock

1. Lo schermo deve rimanere acceso?
   • Sì: consulta invece la documentazione su come mantenere lo schermo acceso
2. L'applicazione esegue un servizio in primo piano?
   • No: non devi acquisire manualmente un wakelock.
3. L'esperienza utente è compromessa se il dispositivo entra in sospensione?
   • No: ad esempio, l'aggiornamento di una notifica dopo che il dispositivo si riattiva non richiede un wakelock.
   • Sì: se è fondamentale impedire al dispositivo di entrare in sospensione, 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 consultare 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, passa 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 wakelock.

2. Stai assegnando il nome corretto al wakelock?

Quando acquisisci manualmente i wakelock, 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 PII, il wakelock viene registrato come _UNKNOWN, il che ostacola il debug.
• Non assegnare un nome al wakelock in modo programmatico utilizzando nomi di classi o metodi, poiché questi possono essere offuscati da strumenti come Proguard. Utilizza invece una stringa hardcoded.
• Non aggiungere contatori o identificatori univoci ai tag dei wakelock. Ogni volta che il wakelock viene eseguito, deve essere utilizzato lo stesso tag per consentire al sistema di aggregare l'utilizzo per nome, semplificando il rilevamento di comportamenti anomali.

3. Il wakelock acquisito viene sempre rilasciato?

Se acquisisci un wakelock manualmente, assicurati che il rilascio del wakelock venga sempre eseguito. Se non rilasci un wakelock, la batteria potrebbe subire un consumo eccessivo. 

Ad esempio, se viene generata un'eccezione non rilevata durante l'esecuzione di processingWork(), la chiamata release() potrebbe non essere mai eseguita. In alternativa, puoi utilizzare un blocco try-finally per garantire che il wakelock venga rilasciato, anche se si verifica un'eccezione.

Inoltre, puoi aggiungere un timeout al wakelock per assicurarti che venga rilasciato dopo un periodo specifico, impedendo che venga mantenuto indefinitamente.

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. Ecco alcuni esempi di come ridurre la frequenza di riattivazione:

• WorkManager: aumenta l'intervallo periodico in PeriodicWorkRequests.
• 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 memorizzata nella cache più recente.
  • Utilizza setPriority(PRIORITY_PASSIVE) per un metodo di aggiornamento meno intensivo per la batteria.
  • Inoltre, puoi sfruttare il meccanismo di batch delle posizioni impostando un intervallo di aggiornamento minimo con setMinUpdateIntervalMillis.

Puoi visualizzare ulteriori dettagli nella documentazione sulle best practice per i wakelock.

Eseguire il debug dell'utilizzo eccessivo dei wakelock

Anche con le migliori intenzioni, può verificarsi un utilizzo eccessivo dei wakelock. Se la tua app è contrassegnata in Play Console, ecco come eseguire il debug:

Identificazione iniziale con Play Console

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

La dashboard dei wakelock parziali eccessivi di Android vitals è stata scorrevole fino alla sezione delle suddivisioni per visualizzare i tag dei wakelock eccessivi.

Eseguire il debug dei wakelock eccessivi mantenuti da worker/job

Puoi identificare i wakelock mantenuti dai worker con questo nome di wakelock:

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

L'elenco completo delle varianti dei nomi dei wakelock mantenuti dai worker è disponibile nella documentazione. Per eseguire il debug di questi wakelock, puoi utilizzare Background Task Inspector per eseguire il debug in locale oppure sfruttare getStopReason per eseguire il debug dei problemi sul campo. 

Strumento di controllo delle attività in background di Android Studio

Acquisizione schermo dello strumento Background Task Inspector, in cui è stato possibile identificare un worker "WeatherSyncWorker" che ha eseguito spesso tentativi e non è riuscito.

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

Ad esempio, può rivelare se un worker non riesce o esegue spesso tentativi a causa del raggiungimento dei limiti di sistema. 

Per ulteriori dettagli, consulta la documentazione dello strumento di controllo delle attività in background.

WorkManager getStopReason

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

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

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

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

Eseguire il debug di altri tipi di wakelock eccessivi

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

Raccolta di tracce di sistema

Una traccia di sistema  è un potente strumento di debug che acquisisce una registrazione dettagliata dell'attività di sistema in un periodo di tempo, fornendo informazioni sullo stato della CPU, sull'attività dei thread, sull'attività di rete e sulle metriche relative alla batteria, come la durata dei job e l'utilizzo dei wakelock.

Puoi acquisire una traccia di sistema utilizzando diversi metodi: 

• Utilizzando lo strumento a riga di comando per le tracce di sistema
• Utilizzando il Profiler CPU di Android Studio
• Utilizzando l'interfaccia utente di Perfetto
• Registrando una traccia manualmente 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. 

Ispezione dell'interfaccia utente di Perfetto e analisi SQL

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

Aggiungi le tracce in "Stato del dispositivo", ad esempio "App principale", "Stato dello schermo", "Wakelock lunghi" e "Job", per identificare visivamente le sezioni dei wakelock a lunga esecuzione.

Ogni blocco elenca il nome dell'evento, l'ora di inizio e l'ora di fine. In Perfetto, questo si chiama sezione.

Per l'analisi scalabile di più tracce, puoi utilizzare l'analisi SQL di Perfetto. Una query SQL può trovare tutti i wakelock ordinati per durata, aiutando a identificare i principali contributori all'utilizzo eccessivo.

Ecco una query di esempio che somma tutti i tag dei wakelock che si sono verificati nella traccia di sistema, ordinati per 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 di 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 trigger di inizio e fine per la raccolta dei profili e applica la limitazione della frequenza a livello di sistema per evitare un impatto sul rendimento del dispositivo. 

Consulta la documentazione di ProfilingManager per ulteriori passaggi su come implementare la raccolta di tracce di sistema sul campo, tra cui come acquisire una traccia in modo programmatico, 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 gli altri processi delle app vengono oscurati dalla traccia.

Conclusione

La metrica dei wakelock parziali eccessivi in Android vitals è solo una piccola parte del nostro impegno continuo per aiutare gli sviluppatori a ridurre il consumo eccessivo della batteria e migliorare la qualità delle app. 

Comprendendo e implementando correttamente i wakelock, puoi ottimizzare notevolmente il rendimento della batteria della tua app. Sfruttare le API alternative, rispettare le best practice per i wakelock e utilizzare 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.