Identifier et optimiser les cas d'utilisation des wake locks

Ce document vous aide à identifier et à optimiser les cas d'utilisation des wakelocks dans votre application, et à déterminer s'il existe des wakelocks acquis par d'autres bibliothèques ou API système associées à ce cas d'utilisation. Comme ces wakelocks sont attribuables à votre application, il peut être difficile d'identifier la source d'un wakelock problématique. Une utilisation incorrecte de l'API peut entraîner le signalement de votre application pour une utilisation excessive des wakelocks, même si vous n'en acquérez pas explicitement.

Ce document liste certains noms de wakelocks courants que vous pouvez rencontrer lorsque vous utilisez les outils de débogage des wakelocks ou dans les rapports de Vitals. Ces noms peuvent provenir d'une bibliothèque ou d'une API système, ou être obscurcis. En utilisant les outils de débogage pour identifier les wakelocks qui ne fonctionnent pas correctement, puis en recherchant le nom du wakelock dans ce document, vous pouvez déterminer quelle API est susceptible de causer le problème et trouver des recommandations pour optimiser son utilisation.

Ce document décrit les cas d'utilisation courants pour l'acquisition de wakelocks, en détaillant les noms de wakelocks utilisés par différentes API et bibliothèques, et fournit des recommandations et des bonnes pratiques pour optimiser et réduire l'utilisation des wakelocks.

AlarmManager

AlarmManager acquiert des wakelocks et les attribue à l'application appelante. AlarmManager acquiert le wakelock lorsque l'alarme se déclenche et le libère lorsque la méthode onReceive() de diffusion de l'alarme a fini de s'exécuter.

Noms des wakelocks

AlarmManager crée des wakelocks nommés *alarm*. (Les astérisques font partie du nom du wakelock, ils ne représentent pas des caractères génériques.)

Recommandation

Nous vous recommandons de suivre les pratiques suivantes pour optimiser le comportement des alarmes :

  • Consultez Choisir un type d'alarme pour choisir entre une alarme inexacte ou exacte. Si votre alarme n'a pas besoin d'être précise, utilisez des alarmes inexactes pour donner au système plus de flexibilité dans la planification, ce qui peut améliorer l'autonomie de la batterie.
  • Tenez compte des quotas d'alarmes imposés par le système et concevez votre application de manière à les respecter.
  • Évitez d'effectuer des tâches de longue durée dans la méthode onReceive() et planifiez des nœuds de calcul si un traitement supplémentaire est nécessaire après l'alarme.

Audio et multimédia

Les API multimédias peuvent acquérir des wakelocks lors de l'enregistrement ou de la lecture de contenus audio. Les wakelocks sont attribués à l'application appelante.

Noms des wakelocks

Les API multimédias acquièrent des wakelocks avec différents noms commençant par Audio :

  • AudioBitPerfect : utilisé pour la lecture audio USB sans perte.
  • AudioDirectOut : utilisé pour la lecture audio sans perte sur un téléviseur ou un appareil spécial.
  • AudioDup : utilisé pour la lecture des notifications lorsque l'appareil est connecté via Bluetooth ou USB.
  • AudioIn : utilisé pour la capture audio en mode caméscope lorsque le micro est actif.
  • AudioMix : utilisé pour la lecture audio sur un appareil standard.
  • AudioOffload : utilisé pour la lecture de musique uniquement sur le long terme, pour les applications compatibles avec ce mode.
  • AudioSpatial : utilisé pour la lecture de films ou de musique multicanaux sur les appareils compatibles avec le son spatial.
  • AudioUnknown : utilisé lorsque les autres situations ne s'appliquent pas.
  • MmapCapture : utilisé pour la capture audio à faible latence.
  • MmapPlayback : utilisé pour la lecture à faible latence, par exemple pour les jeux ou les applications audio professionnelles.

Recommandation

Nous vous recommandons de suivre les pratiques suivantes :

  • Ne déclarez pas de noms de wakelock commençant par Audio.
  • Si vous utilisez les API multimédias, vous ne devriez pas avoir besoin d'acquérir directement des wakelocks. Vous pouvez compter sur les API pour acquérir les wakelocks nécessaires à votre place.
  • Lorsque vous utilisez des API multimédias, mettez fin à la session multimédia et au service de premier plan associé lorsque vous n'en avez plus besoin.

Bluetooth

Les API Bluetooth de la plate-forme contiennent principalement des wakelocks du noyau pendant les actions Bluetooth, qui ne sont pas attribuables à l'application.

Recommandation

  • Utilisez l'association d'appareils associés pour associer des appareils Bluetooth afin d'éviter d'acquérir un wakelock manuel lors de l'association Bluetooth.
  • Consultez les conseils pour communiquer en arrière-plan afin de comprendre comment effectuer une communication Bluetooth en arrière-plan.
  • L'utilisation de WorkManager est souvent suffisante s'il n'y a pas d'impact sur l'utilisateur en cas de communication retardée. Si un wakelock manuel est jugé nécessaire, ne le maintenez que pendant la durée de l'activité Bluetooth ou du traitement des données d'activité.

Capteurs de l'appareil

Il existe plusieurs méthodes pour suivre les données des capteurs de l'appareil, telles que le nombre de pas, les données de l'accéléromètre ou du gyroscope.

Sur Wear OS, utilisez les Services Santé Wear pour récupérer les données de l'appareil, telles que l'altitude, la fréquence cardiaque et la distance parcourue.

Si les données sont collectées par d'autres applications, vous pouvez utiliser Santé Connect avec WorkManager pour récupérer régulièrement les données.

Pour des scénarios tels que le suivi du delta des pas ou de la distance parcourue, vous pouvez utiliser l'API Recording sur mobile combinée à WorkManager pour récupérer régulièrement les données. Pour accéder aux données historiques sur les pas (comme le nombre total de pas par jour ou les pas effectués au cours des six dernières heures), Santé Connect prend également en charge le suivi des pas sur l'appareil pour les appareils équipés d'Android 14 ou version ultérieure.

Dans certains cas, il peut être nécessaire de suivre les capteurs d'un appareil personnalisé à l'aide de SensorManager. SensorManager n'acquiert pas de wakelocks au nom de l'application, sauf si le capteur est un capteur de réveil, qui peut être identifié à l'aide de l'API isWakeUpSensor.

Recommandation

L'utilisation de capteurs pour enregistrer à des taux d'échantillonnage élevés peut décharger considérablement la batterie. Voici quelques recommandations pour réduire la décharge de la batterie et l'utilisation des wakelocks :

  • Si vous suivez le nombre de pas ou la distance parcourue, utilisez l'API Recording pour enregistrer les données de manière à économiser la batterie. Pour les appareils équipés d'Android 14 ou version ultérieure, envisagez d'utiliser Santé Connect pour accéder à l'historique de l'appareil et au nombre de pas agrégé.
  • Pour le suivi passif des capteurs sur Wear OS, utilisez les Services Santé Wear afin d'optimiser l'utilisation de la batterie.
  • Lorsque vous enregistrez un capteur avec SensorManager, définissez un maxReportLatencyUs de plus de 30 secondes pour utiliser la logique de traitement par lot des capteurs et réduire le nombre d'interruptions reçues par l'application. Lorsque l'appareil est ensuite réveillé par un autre déclencheur, tel qu'une interaction de l'utilisateur, une récupération de la position ou une tâche planifiée, le système envoie immédiatement les données des capteurs mises en cache.
  • Si votre application nécessite à la fois des données de localisation et des données des capteurs, synchronisez la récupération et le traitement de leurs événements. En regroupant les relevés des capteurs sur le wakelock bref que le système conserve pour les notifications de position, vous n'avez pas besoin d'un wakelock pour maintenir le processeur actif. Utilisez un nœud de calcul ou un wakelock de courte durée pour gérer l'importation et le traitement de ces données combinées.

Firebase Cloud Messaging (FCM)

Un wakelock est acquis lors de la diffusion d'un message Firebase Cloud Messaging (FCM) vers l'application. Il est libéré une fois que la méthode de diffusion FCM onMessageReceived() a terminé son exécution.

Noms des wakelocks

Lorsqu'un message FCM est reçu sur l'appareil, un wakelock bref est maintenu avec le nom GOOGLE_C2DM. Sur Android 16 ou version ultérieure, le nom du wakelock est GCM_MESSAGE.

Recommandation

Nous vous recommandons de suivre les pratiques suivantes pour optimiser le comportement de FCM :

  • Optimisez la fréquence de diffusion FCM.
  • N'utilisez pas les messages FCM à priorité élevée, sauf si le message doit être distribué immédiatement.
  • Faites en sorte que la méthode onMessageReceived() se termine le plus rapidement possible ou planifiez un nœud de calcul pour poursuivre la tâche si un traitement supplémentaire est nécessaire. Pour en savoir plus, consultez les conseils Firebase.

JobScheduler

Les jobs JobScheduler acquièrent des wakelocks lors de l'exécution de tâches en arrière-plan. Les wakelocks sont attribués à l'application qui a créé les workers.

Noms des wakelocks

Les noms des wakelocks acquis par JobScheduler dépendent de la version du système Android sur laquelle ils s'exécutent et de l'objectif du job.

Les éléments entre crochets sont des variables. Par exemple, "<package_name>" est le nom du package de votre application, et non le texte littéral <package name>. Toutefois, *job* est la séquence de caractères *job*, avec des astérisques. Les astérisques ne sont pas utilisés comme caractères génériques.

Android 15 ou version antérieure

Les jobs lancés par l'utilisateur créent des wakelocks dont les noms suivent ce modèle :

*job*u/@<name_space>@/<package_name>/<classname>

Les autres jobs utilisent ce modèle :

*job*/@<name_space>@/<package_name>/<classname>
Android 16 QPR2 et versions ultérieures

Les jobs lancés par l'utilisateur créent des wakelocks dont les noms suivent ce modèle :

*job*u/@<name_space>@/#<trace_tag>#/<package_name>/<classname>

Les tâches accélérées utilisent ce modèle :

*job*e/@<name_space>@/#<trace_tag>#/<package_name>/<classname>

Les jobs standards utilisent ce modèle :

*job*r/@<name_space>@/#<trace_tag>#/<package_name>/<classname>
Exemple

Supposons qu'il existe une tâche accélérée avec l'espace de noms backup et le tag de trace started. Le nom du package est com.example.app, et la classe qui a créé le job est com.backup.BackupFileService.

Sur les appareils équipés d'Android 15 ou version antérieure, le wakelock serait nommé :

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

Sur les appareils équipés d'Android 16 QPR2 ou version ultérieure, le wakelock serait nommé :

*job*e/@backup@/#started#/com.example.app/com.backup.BackupFileService

Recommandation

  • N'acquérez pas de wakelock manuel pour les cas d'utilisation de téléchargement/ importation initiés par l'utilisateur. Utilisez plutôt l'API User-Initiated Data Transfer (UIDT). Il s'agit du chemin d'accès désigné pour les tâches de transfert de données de longue durée lancées par l'utilisateur.
  • Si vous identifiez des wakelocks créés par JobScheduler avec une utilisation élevée des wakelocks, cela peut être dû au fait que vous avez mal configuré votre tâche pour qu'elle ne se termine pas dans certains scénarios. Envisagez d'analyser les motifs d'arrêt du job, en particulier si vous constatez un nombre élevé d'occurrences de STOP_REASON_TIMEOUT.
  • Auditez votre utilisation des tâches JobScheduler. En particulier, suivez nos conseils pour optimiser l'utilisation de la batterie pour les API de planification des tâches.

Emplacement

LocationManager et FusedLocationProviderClient utilisent des wakelocks pour acquérir et fournir la position de l'appareil. Les wakelocks sont attribués à l'application qui a appelé ces API.

Noms des wakelocks

Les services de localisation utilisent les noms suivants :

  • CollectionLib-SigCollector
  • NetworkLocationLocator
  • NetworkLocationScanner
  • NlpCollectorWakeLock
  • NlpWakeLock
  • *location*

Recommandation

  • Consultez nos conseils pour optimiser l'utilisation de la localisation. Envisagez d'implémenter des délais avant expiration, d'utiliser le traitement par lot des demandes de localisation ou d'utiliser des notifications de position passives.
  • Évitez d'acquérir un wakelock continu distinct pour mettre en cache les données de localisation, car cela est redondant et doit être supprimé. Lorsque vous demandez des notifications de position à l'aide des API FusedLocationProvider ou LocationManager, le système déclenche automatiquement un réveil de l'appareil pendant le rappel d'événement de localisation. Stockez plutôt les événements de localisation en mémoire ou dans l'espace de stockage, et traitez-les régulièrement à l'aide de WorkManager.

Messagerie à distance

Cette section traite des scénarios impliquant la messagerie à distance, dans lesquels les applications peuvent avoir besoin de maintenir des connexions ou de réagir à des événements provenant d'autres appareils, ce qui peut avoir un impact sur l'utilisation des wakelocks. Vous trouverez ci-dessous des cas d'utilisation courants :

  • Applications associées de surveillance vidéo ou audio qui doivent surveiller les événements se produisant sur un appareil externe connecté via un réseau local.
  • Applications de chat qui maintiennent une connexion de socket réseau avec une variante pour ordinateur.

La plupart des activations dans ces scénarios de messagerie à distance sont des wakelocks du kernel. Comme les wakelocks du kernel ne sont pas attribués à l'application, il n'y a pas de noms de wakelocks associés à lister ici.

Recommandation

  • Si les événements réseau peuvent être traités côté serveur, utilisez FCM pour recevoir des informations sur le client. Vous pouvez choisir de planifier un job accéléré si un traitement supplémentaire des données FCM est nécessaire.
  • Si les événements doivent être traités côté client à l'aide d'une connexion de socket, un wakelock n'est pas nécessaire pour écouter les interruptions d'événements. Lorsque des paquets de données arrivent sur la radio Wi-Fi ou la cellule GSM, le matériel radio déclenche une interruption sous la forme d'un wakelock du noyau. Vous pouvez ensuite choisir de planifier un nœud de calcul ou d'acquérir un wakelock pour traiter les données.
  • Par exemple, si vous utilisez ktor-network pour écouter les paquets de données sur un socket réseau, vous ne devez acquérir un wakelock que lorsque les paquets ont été envoyés au client.

WorkManager

Les workers WorkManager acquièrent des wakelocks lors de l'exécution de tâches en arrière-plan. Les wakelocks sont attribués à l'application qui a créé les workers.

Noms des wakelocks

Les noms des wakelocks acquis par WorkManager dépendent de la version du système Android sur laquelle ils s'exécutent.

Android 15 ou version antérieure

Les tâches WorkManager créent des wakelocks dont les noms suivent ce modèle :

*job*/<package_name>/androidx.work.impl.background.systemjob.SystemJobService
Android 16 QPR2 et versions ultérieures

Les tâches prioritaires créent des wakelocks dont les noms suivent ce modèle :

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

Les tâches standards suivent ce modèle :

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

Par défaut, <trace_tag> est le nom du nœud de calcul.

Exemple

Supposons qu'il existe un nœud de calcul accéléré nommé BackupFileWorker. Le nom du package est com.example.app.

Sur les appareils équipés d'Android 15 ou version antérieure, le wakelock serait nommé :

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

Sur les appareils équipés d'Android 16 QPR2 ou version ultérieure et utilisant WorkManager 2.10.0+, le wakelock serait nommé :

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

Recommandation

  • Passez à la dernière version stable de WorkManager pour rendre les tags de wakelock plus détaillés sur Android 16 QPR2 ou version ultérieure.
  • Auditez votre utilisation des workers WorkManager. En particulier, vérifiez qu'elle respecte nos conseils pour optimiser l'utilisation de la batterie pour les API de planification des tâches. Pour rendre les tags de wakelock plus détaillés sur Android 16 QPR2 ou version ultérieure, utilisez la méthode setTraceTag sur le worker pour ajouter des informations de débogage supplémentaires, comme la classe qui a planifié le worker.
  • Si vous identifiez des wakelocks créés par WorkManager avec une utilisation élevée des wakelocks, cela peut être dû au fait que vous avez mal configuré votre nœud de calcul pour qu'il ne se termine pas dans certains scénarios. Envisagez d'analyser les raisons de l'arrêt des nœuds de calcul, en particulier si vous constatez un nombre élevé d'occurrences de STOP_REASON_TIMEOUT.
  • En plus de consigner les raisons de l'arrêt des nœuds de calcul, consultez notre documentation sur le débogage de vos nœuds de calcul. Envisagez également de collecter et d'analyser les traces système pour comprendre quand les wakelocks sont acquis et libérés.

_UNKNOWN

Si les outils de débogage pensent qu'un nom de wakelock contient des informations permettant d'identifier personnellement l'utilisateur, ils n'affichent pas le nom réel du wakelock. À la place, ils étiquettent le wakelock comme _UNKNOWN. Par exemple, les outils peuvent procéder ainsi si le nom du wakelock contient une adresse e-mail.

Recommandation

Suivez les bonnes pratiques concernant l'attribution de noms aux wakelocks et évitez d'utiliser des informations permettant d'identifier personnellement l'utilisateur dans le nom du wakelock. Si vous trouvez un wakelock nommé _UNKNOWN attribué à votre application, essayez d'identifier de quel wakelock il s'agit et donnez-lui un autre nom.