Optimiser la batterie de votre application à l'aide de la métrique de wakelock d'Android Vitals

L'autonomie de la batterie est un aspect crucial de l'expérience utilisateur, et les wakelocks jouent un rôle majeur. Les utilisez-vous de manière excessive ? Dans cet article de blog, nous allons voir ce que sont les wakelocks, quelles sont les bonnes pratiques pour les utiliser et comment mieux comprendre le comportement de votre application grâce à la métrique de la Play Console.

Utilisation excessive de wakelocks partiels dans Android Vitals

La Play Console surveille désormais la décharge de la batterie, en se concentrant sur l'utilisation excessive des wakelocks partiels, qui est un indicateur clé de performance.

Cette fonctionnalité met en avant l'importance de l'efficacité de la batterie, en plus des indicateurs de stabilité des métriques principales existants : les plantages et ANR excessifs perçus par l'utilisateur. Nous avons défini un seuil de comportement insatisfaisant pour les wakelocks excessifs. À partir du 1er mars 2026, si votre titre ne respecte pas ce seuil de qualité, nous pourrons l'exclure des surfaces de découverte proéminentes, comme les recommandations. Dans certains cas, nous pouvons afficher un avertissement sur votre fiche Play Store pour indiquer aux utilisateurs que votre application peut entraîner une décharge excessive de la batterie.

Avertissement concernant les wakelocks excessifs dans la vue d'ensemble d'Android Vitals.

Pour les appareils mobiles, la métrique Android Vitals s'applique aux wakelocks non exemptés acquis lorsque l'écran est éteint et que l'application est en arrière-plan ou exécute un service de premier plan. Android Vitals considère que l'utilisation des wakelocks partiels est excessive si :

• Les wakelocks sont maintenus pendant au moins deux heures sur une période de 24 heures.
• Il affecte plus de 5% des sessions de votre application, en moyenne sur 28 jours.

Les wakelocks créés par les API initiées par l'utilisateur audio, location et JobScheduler sont exclus du calcul des wakelocks.

Comprendre les wakelocks

Un wakelock est un mécanisme qui permet à une application de maintenir le processeur d'un appareil en fonctionnement même lorsque l'utilisateur n'interagit pas activement avec lui. 

Un wakelock partiel maintient le processeur en fonctionnement même si l'écran est éteint, ce qui l'empêche de passer en mode "suspendu" à faible consommation d'énergie. Un wakelock complet maintient l'écran et le processeur en marche.

Il existe deux méthodes pour acquérir des wakelocks partiels :

• L'application acquiert et libère manuellement le wakelock à l'aide des API PowerManager pour un cas d'utilisation spécifique. Souvent, cela est acquis conjointement avec un service de premier plan, une API de cycle de vie de la plate-forme destinée aux opérations perceptibles par l'utilisateur.
• Il est également possible que le wakelock soit acquis par une autre API et attribué à l'application en raison de l'utilisation de l'API. Pour en savoir plus, consultez la section sur les bonnes pratiques.

Bien que les wakelocks soient nécessaires pour des tâches telles que le téléchargement d'un fichier volumineux initié par l'utilisateur, leur utilisation excessive ou inappropriée peut entraîner une décharge importante de la batterie. Nous avons constaté que certaines applications conservaient des wakelocks pendant des heures ou ne les libéraient pas correctement, ce qui entraînait des plaintes d'utilisateurs concernant une décharge importante de la batterie, même lorsqu'ils n'interagissaient pas avec l'application.

Bonnes pratiques d'utilisation des wakelocks

Avant de voir comment déboguer l'utilisation excessive des wakelocks, assurez-vous de suivre les bonnes pratiques les concernant. 

Posez-vous ces quatre questions essentielles.

1. Avez-vous envisagé d'autres options de wakelock ?

Avant d'envisager d'acquérir un wakelock partiel manuel, suivez cet organigramme décisionnel :

Organigramme permettant de décider quand acquérir manuellement un wakelock

1. L'écran doit-il rester allumé ?
   • Oui : consultez plutôt la documentation Garder l'écran allumé.
2. L'application exécute-t-elle un service de premier plan ?
   • Non : vous n'avez pas besoin d'acquérir manuellement un wakelock.
3. La suspension de l'appareil nuit-elle à l'expérience utilisateur ?
   • Non : par exemple, la mise à jour d'une notification après la sortie de veille de l'appareil ne nécessite pas de wakelock.
   • Oui : si vous devez absolument empêcher l'appareil de se mettre en veille (par exemple, s'il communique avec un appareil externe), continuez.
4. Existe-t-il déjà une API qui maintient l'appareil activé en votre nom ?
   • Vous pouvez consulter la documentation Identifier les wakelocks créés par d'autres API pour identifier les scénarios dans lesquels des wakelocks sont créés par d'autres API, telles que LocationManager.
   • Si aucune API n'existe, passez à la dernière question.
5. Si vous avez répondu à toutes ces questions et déterminé qu'il n'existait aucune alternative, vous devez acquérir manuellement un wakelock.

2. Nommez-vous correctement le wakelock ?

Lorsque vous acquérez manuellement des wakelocks, il est important de les nommer correctement pour le débogage :

• N'indiquez aucune information permettant d'identifier personnellement l'utilisateur dans le nom, comme une adresse e-mail. Si des informations permettant d'identifier personnellement l'utilisateur sont détectées, le wakelock est consigné en tant que _UNKNOWN, ce qui entrave le débogage.
• Ne nommez pas votre wakelock de manière programmatique à l'aide de noms de classes ou de méthodes, car ils peuvent être obscurcis par des outils comme Proguard. Utilisez plutôt une chaîne codée en dur.
• N'ajoutez pas de compteurs ni d'identifiants uniques aux tags de wakelock. La même balise doit être utilisée chaque fois que le wakelock s'exécute pour permettre au système d'agréger l'utilisation par nom, ce qui facilite la détection des comportements anormaux.

3. Le wakelock acquis est-il toujours libéré ?

Si vous acquérez un wakelock manuellement, assurez-vous que la libération du wakelock s'exécute toujours. Si vous ne libérez pas un wakelock, la batterie peut se décharger rapidement. 

Par exemple, si une exception non interceptée est générée pendant processingWork(), l'appel release() peut ne jamais se produire. Vous pouvez plutôt utiliser un bloc try-finally pour vous assurer que le wakelock est libéré, même si une exception se produit.

Vous pouvez également ajouter un délai avant expiration au wakelock pour vous assurer qu'il est libéré après une période spécifique, ce qui l'empêche d'être maintenu indéfiniment.

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

4. Pouvez-vous réduire la fréquence de réveil ?

Pour les requêtes de données périodiques, réduire la fréquence à laquelle votre application réveille l'appareil est essentiel pour optimiser la batterie. Voici quelques exemples de réduction de la fréquence de réveil :

• WorkManager : augmentez l'intervalle périodique dans les PeriodicWorkRequest.
• SensorManager : exploitez le traitement par lot en spécifiant maxReportLatencyMs lors de l'enregistrement de l'écouteur.
• Fused Location Provider
  :
  • Réduisez la fréquence de récupération de la position en utilisant getLastLocation pour la position mise en cache la plus récente.
  • Utilisez setPriority(PRIORITY_PASSIVE) pour une méthode de mise à jour moins gourmande en batterie.
  • Vous pouvez également exploiter le mécanisme de traitement par lot de la position en définissant un intervalle de mise à jour minimal avec setMinUpdateIntervalMillis.

Pour en savoir plus, consultez la documentation sur les bonnes pratiques concernant les wakelocks.

Déboguer l'utilisation excessive de wakelocks

Même avec les meilleures intentions, une utilisation excessive des wakelocks peut se produire. Si votre application est signalée dans la Play Console, voici comment la déboguer :

Identification initiale avec la Play Console

Le tableau de bord Android Vitals des wakelocks partiels excessifs fournit une répartition des noms de wakelocks non exemptés associés à votre application, en indiquant les sessions et les durées concernées. N'oubliez pas d'utiliser la documentation pour déterminer si le wakelock est détenu par l'application ou par une autre API.

Tableau de bord Android Vitals des wakelocks partiels excessifs, avec défilement vers le bas jusqu'à la section des répartitions pour afficher les tags de wakelocks excessifs.

Déboguer les wakelocks excessifs détenus par les nœuds de calcul/jobs

Vous pouvez identifier les wakelocks détenus par un nœud de calcul à l'aide du nom de wakelock suivant :

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

La liste complète des variantes de noms de wakelocks détenus par des nœuds de calcul est disponible dans la documentation. Pour déboguer ces wakelocks, vous pouvez utiliser Background Task Inspector pour déboguer localement ou exploiter getStopReason pour déboguer les problèmes sur le terrain. 

Background Task Inspector d'Android Studio

Capture d'écran du Background Task Inspector, qui a pu identifier un Worker "WeatherSyncWorker" qui a échoué à plusieurs reprises.

Pour déboguer localement les problèmes liés à WorkManager, utilisez cet outil sur un émulateur ou un appareil connecté (niveau d'API 26 ou supérieur). Il affiche la liste des workers et leur état (terminé, en cours d'exécution, en file d'attente), ce qui vous permet d'inspecter les détails et de comprendre les chaînes de workers. 

Par exemple, il peut révéler si un nœud de calcul échoue ou effectue fréquemment de nouvelles tentatives en raison de limites système atteintes. 

Pour en savoir plus, consultez la documentation sur l'outil d'inspection des tâches en arrière-plan.

getStopReason de WorkManager

Pour déboguer sur le terrain les nœuds de calcul présentant un nombre excessif de wakelocks, utilisez WorkInfo.getStopReason() sur WorkManager 2.9.0 ou version ultérieure, ou JobParameters.getStopReason() pour JobScheduler, disponible sur le SDK 31 ou version ultérieure. 

Cette API permet de consigner la raison pour laquelle un nœud de calcul s'est arrêté (par exemple, STOP_REASON_TIMEOUT, STOP_REASON_QUOTA), en identifiant des problèmes tels que des délais d'expiration fréquents dus à l'épuisement de la durée d'exécution.

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

Pour en savoir plus, consultez Optimiser l'utilisation de la batterie pour les API de planification des tâches.

Déboguer d'autres types de wakelocks excessifs

Pour les scénarios plus complexes impliquant des wakelocks détenus manuellement ou des API détenant le wakelock, nous vous recommandons d'utiliser la collecte de traces système pour le débogage.

Collecte d'une trace système

Une trace système  est un outil de débogage puissant qui capture un enregistrement détaillé de l'activité du système sur une période donnée. Elle fournit des insights sur l'état du processeur, l'activité des threads, l'activité réseau et les métriques liées à la batterie, comme la durée des tâches et l'utilisation des wakelocks.

Vous pouvez capturer une trace système de plusieurs manières : 

• Utiliser l'outil de ligne de commande de trace système
• Utiliser le Profileur de processeur d'Android Studio
• Utiliser l'interface utilisateur de Perfetto
• Enregistrer manuellement une trace sur l'appareil directement depuis les options pour les développeurs. 

Activez la catégorie Atrace "power:PowerManagement" dans l'interface utilisateur de Perfetto, sous l'onglet "Android apps & svcs" (Applications et services Android). 

Quelle que soit la méthode choisie, il est essentiel de vous assurer que vous collectez la catégorie Atrace "power:PowerManagement" pour pouvoir afficher les pistes d'état de l'appareil. 

Inspection de l'UI Perfetto et analyse SQL

Les traces système peuvent être ouvertes et inspectées dans l'interface utilisateur de Perfetto. Lorsque vous ouvrez la trace, vous voyez une visualisation de différents processus sur une chronologie. Dans ce guide, nous nous concentrerons sur les pistes de la section "État de l'appareil".

Épinglez les pistes sous "Device State" (État de l'appareil), telles que "Top app" (Application principale), "Screen state" (État de l'écran), "Long Wake locks" (Wakelocks longs) et "Jobs" (Tâches) pour identifier visuellement les segments de wakelocks de longue durée.

Chaque bloc indique le nom de l'événement, ainsi que ses heures de début et de fin. Dans Perfetto, on parle de "segment".

Pour une analyse évolutive de plusieurs traces, vous pouvez utiliser l'analyse SQL de Perfetto. Une requête SQL peut trouver tous les wakelocks triés par durée, ce qui permet d'identifier les principaux contributeurs à une utilisation excessive.

Voici un exemple de requête additionnant tous les tags de wakelock qui se sont produits dans la trace système, classés par durée 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

Utiliser ProfilingManager pour collecter des traces sur le terrain

Pour les problèmes difficiles à reproduire, ProfilingManager (ajouté au SDK 35) est une API programmatique qui permet aux développeurs de collecter des traces système sur le terrain avec des déclencheurs de début et de fin. Il offre un meilleur contrôle sur les points de déclenchement de début et de fin de la collecte de profils, et applique une limitation du débit au niveau du système pour éviter tout impact sur les performances de l'appareil. 

Consultez la documentation ProfilingManager pour découvrir comment implémenter la collecte de traces système sur le terrain, y compris comment capturer une trace, analyser les données de profilage et utiliser des commandes de débogage locales de manière programmatique.

Les traces système collectées à l'aide de ProfilingManager ressemblent à celles collectées manuellement, mais les processus système et les autres processus d'application sont masqués dans la trace.

Conclusion

La métrique sur les wakelocks partiels excessifs dans Android Vitals n'est qu'une petite partie de notre engagement continu à aider les développeurs à réduire la décharge de la batterie et à améliorer la qualité des applications. 

En comprenant et en implémentant correctement les wakelocks, vous pouvez optimiser considérablement les performances de la batterie de votre application. Pour assurer le succès de votre application sur Google Play, il est essentiel d'utiliser des API alternatives, de respecter les bonnes pratiques concernant les wakelocks et d'utiliser des outils de débogage puissants tels que Background Task Inspector, les traces système et ProfilingManager.