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 à mettre en évidence s'il existe des pour les wakelocks acquis par d'autres bibliothèques ou API système associés à ce cas d'utilisation. Étant donné que 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 répertorie 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 à l'origine du problème et trouver des recommandations sur la façon d'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.

Gestionnaire d'alarmes (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 la diffusion de l'alarme a terminé son exécution.

Noms des wakelocks

AlarmManager crée des wakelocks avec le nom *alarm*. (Les astérisques font partie du nom du wakelock, ils ne représentent pas de 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 offrir 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 longues dans la onReceive() méthode 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 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 de notifications lors d'une connexion 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 commun.
  • AudioOffload: utilisé pour la lecture de musique à long terme uniquement, pour les applications compatibles avec ce mode.
  • AudioSpatial: utilisé pour la lecture de films ou de musique multicanaux sur des 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 wakelocks commençant par Audio.
  • Si vous utilisez les API multimédias, vous n'avez pas besoin d'acquérir directement des wakelocks. Vous pouvez compter sur les API pour acquérir les wakelocks nécessaires.
  • 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 conservent principalement les wakelocks du noyau lors des actions Bluetooth, qui ne sont pas attribuables à l'application.

Recommandation

  • Utilisez l'association d'appareils compagnons pour associer des appareils Bluetooth afin d' éviter d'acquérir un wakelock manuel lors de l'association Bluetooth.
  • Consultez les conseils sur la communication en arrière-plan pour comprendre comment effectuer une communication Bluetooth en arrière-plan.
  • L'utilisation de WorkManager est souvent suffisante si une communication retardée n'a pas d'incidence sur l'utilisateur. Si un wakelock manuel est jugé nécessaire, ne le conservez 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, l'accéléromètre ou le gyroscope.

Sur Wear OS, utilisez 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 en combinaison avec WorkManager pour les récupérer périodiquement.

Pour les scénarios tels que le suivi du delta de pas ou de la distance parcourue, vous pouvez utiliser l'API Recording sur mobile en combinaison avec WorkManager pour récupérer périodiquement les données. Pour accéder aux données historiques sur les pas (par exemple, le nombre total de pas par jour ou le nombre de pas au cours des six dernières heures), Santé Connect est également compatible avec 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 d'effectuer un suivi personnalisé des capteurs de l'appareil à l'aide de SensorManager. SensorManager n'acquiert pas de wakelocks pour le compte 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 entraîner une décharge importante de 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 économe en énergie. Pour les appareils équipés d'Android 14 ou version ultérieure, envisagez d'utiliser Santé Connect pour accéder à l'historique des appareils et au nombre de pas agrégé.
  • Pour le suivi passif des capteurs sur Wear OS, utilisez Wear Health Services afin d'optimiser l'utilisation de la batterie.
  • Lorsque vous enregistrez un capteur avec SensorManager, définissez une maxReportLatencyUs supérieure à 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éactivé par un autre déclencheur, tel qu'une interaction de l'utilisateur, une récupération de position ou un job planifié, le système envoie immédiatement les données de capteur mises en cache.
  • Si votre application nécessite à la fois des données de localisation et des données de capteur, synchronisez leur récupération et leur traitement. En regroupant les lectures de capteur sur le bref wakelock que le système conserve pour les mises à jour de position, vous évitez d'avoir 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) à l'application. Le wakelock est libéré une fois que la diffusion FCM onMessageReceived() a terminé son exécution.

Noms des wakelocks

Lorsqu'un message FCM est reçu sur l'appareil, un bref wakelock est conservé 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 de FCM.
  • N'utilisez pas FCM à priorité élevée, sauf si le message doit être diffusé 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 tâches 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 nœuds de calcul.

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 de la tâche.

Les éléments entourés de chevrons 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 tâches lancées par l'utilisateur créent des wakelocks avec des noms suivant ce modèle :

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

Les autres tâches utilisent ce modèle :

*job*/@<name_space>@/<package_name>/<classname>
Android 16 QPR2 ou version ultérieure

Les tâches lancées par l'utilisateur créent des wakelocks avec des noms suivant ce modèle :

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

Les tâches prioritaires utilisent ce modèle :

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

Les tâches régulières 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éé la tâche 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 lancés par l'utilisateur. Utilisez plutôt l'API User-Initiated Data Transfer (UIDT). Il s'agit du chemin 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 raisons d'arrêt de la tâche , en particulier si vous constatez une fréquence élevée 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 d'inactivité, d'exploiter le traitement par lot des requêtes de localisation ou d'utiliser des mises à jour de position passives.
  • Évitez d'acquérir un wakelock continu distinct pour la mise en cache des données de localisation, car cela est redondant et doit être supprimé. Lorsque vous demandez des mises à jour de position à l'aide des FusedLocationProvider ou LocationManager API, le système déclenche automatiquement une réactivation de l'appareil lors du rappel d'événement de localisation. Stockez plutôt les événements de localisation en mémoire ou dans un espace de stockage, et traitez-les périodiquement à l'aide de WorkManager.

Messagerie à distance

Cette section aborde les 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 compagnons 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 messagerie qui maintiennent une connexion de socket réseau avec une variante de bureau.

La plupart des réveils dans ces scénarios de messagerie à distance sont des wakelocks du noyau. Étant donné que les wakelocks du noyau ne sont pas attribués à l'application, aucun nom de wakelock associé n'est à répertorier 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 nœud de calcul prioritaire 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 cellulaire, 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é remis au client.

WorkManager

Les nœuds de calculWorkManager 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 nœuds de calcul.

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 avec des noms suivant ce modèle :

*job*/<package_name>/androidx.work.impl.background.systemjob.SystemJobService
Android 16 QPR2 ou version ultérieure

Les tâches prioritaires créent des wakelocks avec des noms suivant ce modèle :

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

Les tâches régulières 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 prioritaire 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

  • Mettez à niveau votre version de WorkManager vers la dernière version stable pour rendre les tags de wakelocks plus détaillés sur Android 16 QPR2 ou version ultérieure.
  • Auditez votre utilisation des nœuds de calcul WorkManager. Vérifiez en particulier qu'elle suit nos conseils pour optimiser l'utilisation de la batterie pour les API de planification des tâches. Pour rendre les tags de wakelocks plus détaillés sur Android 16 QPR2 ou version ultérieure, utilisez la setTraceTag méthode sur le nœud de calcul pour ajouter plus d'informations de débogage, par exemple la classe qui a planifié le nœud de calcul.
  • 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 d'arrêt du nœud de calcul, en particulier si vous constatez une fréquence élevée de STOP_REASON_TIMEOUT.
  • En plus d'enregistrer les raisons d'arrêt du nœud 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 personnelles, ils n'affichent pas le nom réel du wakelock. Au lieu de cela, ils étiquettent le wakelock comme _UNKNOWN. Par exemple, les outils peuvent le faire si le nom du wakelock contient une adresse e-mail.

Recommandation

Suivez les bonnes pratiques de dénomination des wakelocks et évitez d'utiliser des informations personnelles dans le nom du wake lock. Si vous trouvez un wakelock nommé _UNKNOWN attribué à votre application, essayez d'identifier le wakelock et donnez-lui un autre nom.