Identifier et optimiser les cas d'utilisation des wake locks

Ce document vous aide à identifier et à optimiser les cas d'utilisation des wake locks dans votre application. Il vous indique également si des wake locks acquis par d'autres bibliothèques ou API système sont associés à ce cas d'utilisation. Étant donné que ces verrous de réveil sont attribuables à votre application, il peut être difficile d'identifier la source d'un verrou de réveil problématique. Une utilisation incorrecte de l'API peut entraîner le signalement de votre application pour utilisation excessive de wake locks, 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 de wakelocks ou dans les rapports sur les signaux vitaux. 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 verrous de réveil qui se comportent mal, puis en recherchant le nom du verrou de réveil 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 acquérir des verrous de réveil. Il détaille les noms de verrous de réveil 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 verrous de réveil.

AlarmManager

AlarmManager acquiert des wake locks et les attribue à l'application appelante. AlarmManager acquiert le wake lock 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 verrous de réveil avec le nom *alarm*. (Les astérisques font partie du nom du verrouillage de réveil. 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 :

  • Reportez-vous à 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 plus de flexibilité au système 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 verrous de réveil lors de l'enregistrement ou de la lecture audio. Les wake locks sont attribués à l'application appelante.

Noms des wakelocks

Les API Media 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 lorsqu'un 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 commun.
  • AudioOffload : utilisé pour la lecture de musique uniquement à 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 l'audio spatial.
  • AudioUnknown : à utiliser 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 Media, vous n'avez pas besoin d'acquérir directement des wake locks. Vous pouvez vous appuyer sur les API pour acquérir les wake locks nécessaires.
  • Lorsque vous utilisez des API Media, 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 détiennent principalement des verrous de réveil du noyau lors des 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 verrouillage de réveil manuel lors de l'association Bluetooth.
  • Consultez les conseils sur la communication en arrière-plan pour comprendre comment communiquer en arrière-plan via Bluetooth.
  • L'utilisation de WorkManager est souvent suffisante si la communication différée n'a aucune incidence sur les utilisateurs. Si un verrouillage de réveil 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, ou les données de l'accéléromètre ou du gyroscope.

Sur Wear OS, utilisez les Services Santé Wear pour récupérer des données sur l'appareil, comme 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 combiné à WorkManager pour les récupérer périodiquement.

Pour des scénarios tels que le suivi du delta de 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 quotidiens 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 exécutant Android 14 ou version ultérieure.

Dans certains cas, il peut être nécessaire de suivre les capteurs de l'appareil à l'aide de SensorManager. SensorManager n'acquiert pas de wake locks 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 données à 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 du verrouillage de l'écran :

  • Si vous souhaitez suivre le nombre de pas ou la distance parcourue, utilisez l'API Recording pour enregistrer les données de manière économe en batterie. Pour les appareils fonctionnant sous Android 14 ou version ultérieure, pensez à utiliser Santé Connect pour accéder à l'historique des appareils et au nombre de pas cumulés.
  • 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 réactivé par un autre déclencheur, tel qu'une interaction utilisateur, une récupération de position ou une tâche planifiée, 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 capteurs, synchronisez leur récupération et leur traitement d'événements. En regroupant les lectures de capteurs sur le bref verrouillage de réveil que le système détient pour les mises à jour de localisation, vous évitez d'avoir besoin d'un verrouillage de réveil pour maintenir le processeur éveillé. Utilisez un worker ou un verrouillage de réveil de courte durée pour gérer l'importation et le traitement de ces données combinées.

Firebase Cloud Message (FCM)

Un verrouillage de réveil est acquis lors de la diffusion d'un message Firebase Cloud Messaging (FCM) à l'application. Le verrouillage de réveil est libéré une fois que la méthode onMessageReceived() de diffusion FCM a fini de s'exécuter.

Noms des wakelocks

Lorsqu'un message FCM est reçu sur l'appareil, un bref verrouillage de réveil est maintenu avec le nom GOOGLE_C2DM. Sur Android 16 et versions ultérieures, le nom du verrouillage de réveil est GCM_MESSAGE.

Recommandation

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

  • Optimisez la fréquence d'envoi des messages FCM.
  • N'utilisez pas FCM à priorité élevée, sauf si le message doit réellement être remis 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 verrous de réveil lorsqu'elles exécutent des tâches en arrière-plan. Les wake locks sont attribués à l'application qui a créé les workers.

Noms des wakelocks

Les noms des wake locks 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 entourés de 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 tâches lancées par l'utilisateur créent des verrous de réveil dont les noms suivent ce modèle :

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

D'autres tâches utilisent ce modèle :

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

Les tâches lancées par l'utilisateur créent des wake locks dont le nom suit 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 réguliers utilisent ce modèle :

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

Supposons qu'il existe un job accéléré 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 verrouillage de l'écran de sortie de veille est nommé :

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

Sur les appareils fonctionnant sous Android 16.1 ou version ultérieure, le verrouillage de réveil est nommé comme suit :

*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 verrous de réveil créés par JobScheduler avec une utilisation élevée des verrous de réveil, cela peut être dû à une mauvaise configuration de votre job qui ne se termine pas dans certains scénarios. Envisagez d'analyser les motifs d'arrêt du job, 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 verrous de réveil pour obtenir et fournir la position de l'appareil. Les wake locks 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 des lieux. Envisagez d'implémenter des délais d'attente, d'utiliser le regroupement des demandes de localisation ou d'utiliser des mises à jour de localisation passives.
  • Évitez d'acquérir un verrouillage de réveil 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 la position à l'aide des API FusedLocationProvider ou LocationManager, le système déclenche automatiquement la sortie de veille de l'appareil lors du rappel d'événement de localisation. Au lieu de cela, stockez 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 du verrouillage de réveil. Voici quelques 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 messagerie qui maintiennent une connexion de socket réseau avec une variante pour ordinateur.

La plupart des réveils dans ces scénarios de messagerie à distance sont des verrous de réveil du noyau. Étant donné que les verrous de réveil du noyau ne sont pas attribués à l'application, aucun nom de verrou de réveil associé ne peut être listé 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 worker 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 socket, un verrouillage de réveil n'est pas nécessaire pour écouter les interruptions d'événements. Lorsque des paquets de données arrivent au niveau de la radio Wi-Fi ou cellulaire, le matériel radio déclenche une interruption sous la forme d'un verrouillage de réveil du noyau. Vous pouvez ensuite choisir de planifier un worker ou d'acquérir un verrouillage de réveil 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 verrouillage de réveil que lorsque les paquets ont été remis au client.

WorkManager

Les workers WorkManager acquièrent des wake locks lorsqu'ils exécutent des tâches en arrière-plan. Les wake locks sont attribués à l'application qui a créé les workers.

Noms des wakelocks

Les noms de verrouillage de réveil 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 verrous de réveil dont les noms suivent ce modèle :

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

Les tâches accélérées créent des verrous de réveil dont les noms suivent 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 worker.

Exemple

Supposons qu'il existe un nœud de calcul de rendu 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 verrouillage de l'écran de sortie de veille est nommé :

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

Sur les appareils équipés d'Android 16 ou version ultérieure et utilisant WorkManager 2.10.0+, le nom du wake lock serait le suivant :

*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 verrouillage de réveil plus détaillés sur Android 16.1 ou version ultérieure.
  • Auditez votre utilisation des Workers WorkManager. En particulier, vérifiez 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 verrouillage de réveil plus détaillés sur Android 16.1 ou version ultérieure, utilisez la méthode setTraceTag sur le Worker pour ajouter des informations de débogage, comme la classe qui a planifié le Worker.
  • Si vous identifiez des wake locks créés par WorkManager avec une utilisation élevée de wake locks, cela peut être dû à une mauvaise configuration de votre worker qui ne se termine pas dans certains scénarios. Envisagez d'analyser les raisons d'arrêt des nœuds de calcul, en particulier si vous constatez une fréquence élevée de STOP_REASON_TIMEOUT.
  • En plus d'enregistrer les raisons de l'arrêt des nœuds de calcul, consultez notre documentation sur le débogage de vos nœuds de calcul. Pensez également à collecter et à analyser les traces système pour comprendre quand les verrous de réveil sont acquis et libérés.

_UNKNOWN

Si les outils de débogage estiment qu'un nom de wakelock contient des informations permettant d'identifier personnellement l'utilisateur, ils n'affichent pas le nom réel du wakelock. Au lieu de cela, ils attribuent au wake lock le libellé _UNKNOWN. Par exemple, les outils peuvent le faire si le nom du verrou de réveil contient une adresse e-mail.

Recommandation

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