Identifica y optimiza los casos de uso de bloqueo de activación

Este documento te ayuda a identificar y optimizar los casos de uso de bloqueos de activación en tu app, así como a destacar si hay bloqueos de activación adquiridos por otras bibliotecas o APIs del sistema asociados con este caso de uso. Dado que estos bloqueos de activación son atribuibles a tu app, puede ser difícil identificar la fuente de un bloqueo de activación problemático. El uso incorrecto de la API puede hacer que se marque tu app por un uso excesivo del bloqueo de activación, incluso si no adquieres bloqueos de activación de forma explícita.

En este documento, se enumeran algunos nombres comunes de bloqueos de activación que puedes encontrar cuando usas las herramientas de depuración de bloqueos de activación o en los informes de Vitals. Estos nombres pueden provenir de una biblioteca o una API del sistema, o bien pueden estar ofuscados. Si usas las herramientas de depuración para identificar los bloqueos de activación que no funcionan correctamente y, luego, buscas el nombre del bloqueo de activación en este documento, puedes determinar qué API puede estar causando el problema y encontrar recomendaciones para optimizar su uso.

En este documento, se describen los casos de uso comunes para adquirir bloqueos de activación, se detallan los nombres de los bloqueos de activación que usan varias APIs y bibliotecas, y se proporcionan recomendaciones y prácticas recomendadas para optimizar y reducir el uso de bloqueos de activación.

AlarmManager

AlarmManager adquiere bloqueos de activación y los atribuye a la app que realiza la llamada. AlarmManager adquiere el bloqueo de activación cuando se activa la alarma y libera el bloqueo cuando finaliza la ejecución del método onReceive() de la transmisión de la alarma.

Nombres de los bloqueos de activación

AlarmManager crea bloqueos de activación con el nombre *alarm*. (Los asteriscos forman parte del nombre del bloqueo de activación y no representan comodines).

Recomendación

Te recomendamos las siguientes prácticas para optimizar el comportamiento de la alarma:

  • Consulta Cómo elegir un tipo de alarma para decidir entre una alarma inexacta o exacta. Si la alarma no necesita ser precisa, usa alarmas inexactas para darle al sistema más flexibilidad en la programación, lo que puede mejorar la duración de la batería.
  • Ten en cuenta las cuotas de alarma impuestas por el sistema y diseña tu app para respetarlas.
  • Evita realizar trabajos prolongados en el onReceive() método y programa trabajadores si se requiere un procesamiento adicional después de la alarma.

Audio y contenido multimedia

Las APIs de Media pueden adquirir bloqueos de activación cuando graban o reproducen audio. Los bloqueos de activación se atribuyen a la app que realiza la llamada.

Nombres de los bloqueos de activación

Las APIs de Media adquieren bloqueos de activación con varios nombres que comienzan con Audio:

  • AudioBitPerfect: Se usa para la reproducción de audio USB sin pérdida.
  • AudioDirectOut: Se usa para la reproducción de audio sin pérdida en una TV o un dispositivo especial.
  • AudioDup: Se usa para la reproducción de notificaciones mientras se está conectado mediante Bluetooth o USB.
  • AudioIn: Se usa para la captura de audio en modo de videocámara mientras el micrófono está activo.
  • AudioMix: Se usa para la reproducción de audio en un dispositivo común.
  • AudioOffload: Se usa para la reproducción de música a largo plazo, solo para apps que admiten este modo.
  • AudioSpatial: Se usa para la reproducción de audio de películas o música multicanal en dispositivos que admiten audio espacial.
  • AudioUnknown: Se usa cuando no se aplican las otras situaciones.
  • MmapCapture: Se usa para la captura de audio de baja latencia.
  • MmapPlayback: Se usa para la reproducción de baja latencia, como para juegos o para aplicaciones de audio profesionales.

Recomendación

Te recomendamos las siguientes prácticas:

  • No declares nombres de bloqueos de activación que comiencen con Audio.
  • Si usas las APIs de Media, no deberías necesitar adquirir bloqueos de activación directamente. Puedes confiar en que las APIs adquieran los bloqueos de activación necesarios por ti.
  • Cuando uses las APIs de Media, finaliza la sesión de medios y el servicio de primer plano asociado cuando ya no lo necesites.

Bluetooth

Las APIs de Bluetooth de la plataforma mantienen principalmente los bloqueos de activación del kernel mientras se producen acciones de Bluetooth, que no son atribuibles a la aplicación.

Recomendación

  • Usa el vinculación de dispositivos complementarios para vincular dispositivos Bluetooth y evitar adquirir un bloqueo de activación manual durante el vinculación de Bluetooth.
  • Consulta la guía de comunicación en segundo plano para comprender cómo realizar la comunicación de Bluetooth en segundo plano.
  • El uso de WorkManager suele ser suficiente si no hay impacto en el usuario en una comunicación demorada. Si se considera necesario un bloqueo de activación manual, solo mantén el bloqueo de activación durante la actividad de Bluetooth o el procesamiento de los datos de actividad.

Sensores del dispositivo

Existen varios métodos para hacer un seguimiento de los datos de los sensores del dispositivo, como el recuento de pasos, el acelerómetro o los datos del giroscopio.

En Wear OS, usa los Servicios de salud de Wear para obtener datos del dispositivo, como la elevación, la frecuencia cardíaca y la distancia recorrida.

Si otras aplicaciones recopilan los datos, puedes usar Health Connect junto con WorkManager para recuperarlos periódicamente.

Para situaciones como el seguimiento del delta de pasos o la distancia recorrida, puedes usar la API de Recording en dispositivos móviles junto con WorkManager para recuperar los datos periódicamente. Para acceder a los datos históricos de pasos (como el total de pasos diarios o los pasos en las últimas 6 horas), Health Connect también admite el seguimiento de pasos en el dispositivo para dispositivos que ejecutan Android 14 o versiones posteriores.

En ciertas situaciones, es posible que se necesite el seguimiento personalizado de los sensores del dispositivo con SensorManager. SensorManager no adquiere bloqueos de activación en nombre de la app, a menos que el sensor sea un sensor de activación, que se puede identificar con la API de isWakeUpSensor.

Recomendación

El uso de sensores para grabar a altas tasas de muestreo puede agotar la batería de manera significativa, estas son las recomendaciones para reducir el agotamiento de la batería y el uso de bloqueos de activación:

  • Si haces un seguimiento del recuento de pasos o la distancia recorrida, usa la API de Recording para registrar datos de manera eficiente en cuanto a la batería. En dispositivos que ejecutan Android 14 o versiones posteriores, considera Health Connect para acceder al dispositivo histórico y al recuento de pasos agregados.
  • Para el seguimiento pasivo de sensores en Wear OS, usa los Servicios de salud de Wear para optimizar el uso de la batería.
  • Cuando registres un sensor con SensorManager, define un maxReportLatencyUs de más de 30 segundos para usar la lógica de procesamiento por lotes de sensores y reducir la cantidad de interrupciones que recibe la aplicación. Cuando el dispositivo se active posteriormente con otro activador, como una interacción del usuario, la recuperación de la ubicación o una tarea programada, el sistema enviará de inmediato los datos del sensor almacenados en caché.
  • Si tu app requiere datos de ubicación y de sensores, sincroniza su recuperación y procesamiento de eventos. Si unes las lecturas de los sensores en el breve bloqueo de activación que mantiene el sistema para las actualizaciones de ubicación, evitas la necesidad de un bloqueo de activación para mantener la CPU activa. Usa un trabajador o un bloqueo de activación de corta duración para controlar la carga y el procesamiento de estos datos combinados.

Firebase Cloud Message (FCM)

Se adquiere un bloqueo de activación mientras se entrega una transmisión de Firebase Cloud Message (FCM) a la app. El bloqueo de activación se libera una vez que finaliza la ejecución del método onMessageReceived() de la transmisión de FCM.

Nombres de los bloqueos de activación

Cuando se recibe un mensaje de FCM en el dispositivo, se mantiene un breve bloqueo de activación con el nombre GOOGLE_C2DM. En Android 16 y versiones posteriores, el nombre del bloqueo de activación es GCM_MESSAGE.

Recomendación

Te recomendamos las siguientes prácticas para optimizar el comportamiento de FCM:

  • Optimiza la frecuencia de entrega de FCM.
  • No uses FCM de alta prioridad, a menos que el mensaje deba entregarse de inmediato.
  • Haz que el método onMessageReceived() se complete lo más rápido posible o programa un trabajador para continuar con la tarea si se requiere un procesamiento adicional. Consulta la guía de Firebase para obtener más información.

JobScheduler

Las tareas de JobScheduler adquieren bloqueos de activación mientras ejecutan tareas en segundo plano. Los bloqueos de activación se atribuyen a la app que creó los trabajadores.

Nombres de los bloqueos de activación

Los nombres de los bloqueos de activación que adquiere JobScheduler dependen de la versión del sistema Android en la que se ejecutan y del propósito de la tarea.

Los elementos entre corchetes angulares son variables. Por ejemplo, "<package_name>" es el nombre del paquete de tu app, no el texto literal <package name>. Sin embargo, *job* es la secuencia de caracteres *job*, con asteriscos. Los asteriscos no se usan como comodines.

Android 15 y versiones anteriores

Las tareas iniciadas por el usuario crean bloqueos de activación con nombres que siguen este patrón:

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

Otras tareas usan este patrón:

*job*/@<name_space>@/<package_name>/<classname>
Android 16.1 y versiones posteriores

Las tareas iniciadas por el usuario crean bloqueos de activación con nombres que siguen este patrón:

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

Las tareas aceleradas usan este patrón:

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

Las tareas normales usan este patrón:

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

Supongamos que hay una tarea acelerada con el espacio de nombres backup y la etiqueta de seguimiento started. El nombre del paquete es com.example.app, y la clase que creó la tarea es com.backup.BackupFileService.

En dispositivos que ejecutan Android 15 o versiones anteriores, el bloqueo de activación se llamaría de la siguiente manera:

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

En dispositivos que ejecutan Android 16.1 o versiones posteriores, el bloqueo de activación se llamaría de la siguiente manera:

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

Recomendación

  • No adquieras un bloqueo de activación manual para los casos de uso de descarga o carga iniciados por el usuario. En su lugar, usa la API de User-Initiated Data Transfer (UIDT). Esta es la ruta designada para las tareas de transferencia de datos de larga duración iniciadas por el usuario.
  • Si identificas bloqueos de activación creados por JobScheduler con un uso elevado de bloqueos de activación, es posible que hayas configurado incorrectamente tu tarea para que no se complete en ciertas situaciones. Considera analizar los motivos de detención de la tarea, en especial si ves muchas instancias de STOP_REASON_TIMEOUT.
  • Audita tu uso de las tareas de JobScheduler. En particular, sigue nuestra guía para optimizar el uso de la batería para las APIs de programación de tareas.

Ubicación

LocationManager y FusedLocationProviderClient usan bloqueos de activación para adquirir y entregar la ubicación del dispositivo. Los bloqueos de activación se atribuyen a la app que llamó a esas APIs.

Nombres de los bloqueos de activación

Los servicios de ubicación usan los siguientes nombres:

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

Recomendación

  • Consulta nuestra guía para optimizar el uso de la ubicación. Considera implementar tiempos de espera, aprovechar el procesamiento por lotes de solicitudes de ubicación, o usar actualizaciones de ubicación pasiva.
  • Evita adquirir un bloqueo de activación continuo y separado para almacenar en caché los datos de ubicación, ya que es redundante y se debe quitar. Cuando solicitas actualizaciones de ubicación con las APIs de FusedLocationProvider o LocationManager, el sistema activa automáticamente un dispositivo durante la devolución de llamada del evento de ubicación. En su lugar, almacena los eventos de ubicación en la memoria o el almacenamiento, y procesa los eventos de ubicación periódicamente con WorkManager.

Mensajería remota

En esta sección, se analizan situaciones que involucran la mensajería remota en las que las apps podrían necesitar mantener conexiones o reaccionar a eventos de otros dispositivos, lo que podría afectar el uso de bloqueos de activación. Los casos de uso comunes incluyen los siguientes:

  • Apps complementarias de supervisión de video o sonido que necesitan supervisar eventos que ocurren en un dispositivo externo conectado a través de una red local
  • Apps de mensajería que mantienen una conexión de socket de red con una variante de escritorio

La mayoría de las activaciones en estas situaciones de mensajería remota son bloqueos de activación del kernel. Como los bloqueos de activación del kernel no se atribuyen a la app, no hay nombres de bloqueos de activación asociados para enumerar aquí.

Recomendación

  • Si los eventos de red se pueden procesar en el servidor, usa FCM para recibir información sobre el cliente. Puedes optar por programar un trabajador acelerado si se requiere un procesamiento adicional de los datos de FCM.
  • Si los eventos se deben procesar en el cliente con una conexión de socket, no se necesita un bloqueo de activación para escuchar las interrupciones de eventos. Cuando los paquetes de datos llegan a la radio Wi-Fi o celular, el radio hardware activa una interrupción en forma de bloqueo de activación del kernel. Luego, puedes optar por programar un trabajador o adquirir un bloqueo de activación para procesar los datos.
  • Por ejemplo, si usas ktor-network para escuchar paquetes de datos en un socket de red, solo debes adquirir un bloqueo de activación cuando los paquetes se hayan entregado al cliente.

WorkManager

Los trabajadores deWorkManager adquieren bloqueos de activación mientras ejecutan tareas en segundo plano. Los bloqueos de activación se atribuyen a la app que creó los trabajadores.

Nombres de los bloqueos de activación

Los nombres de los bloqueos de activación que adquiere WorkManager dependen de la versión del sistema Android en la que se ejecutan.

Android 15 y versiones anteriores

Las tareas de WorkManager crean bloqueos de activación con nombres que siguen este patrón:

*job*/<package_name>/androidx.work.impl.background.systemjob.SystemJobService
Android 16.1 y versiones posteriores

Las tareas aceleradas crean bloqueos de activación con nombres que siguen este patrón:

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

Las tareas normales siguen este patrón:

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

De forma predeterminada, <trace_tag> es el nombre del trabajador.

Ejemplo

Supongamos que hay un trabajador acelerado llamado BackupFileWorker. El nombre del paquete es com.example.app.

En dispositivos que ejecutan Android 15 o versiones anteriores, el bloqueo de activación se llamaría de la siguiente manera:

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

En dispositivos que ejecutan Android 16 o versiones posteriores y usan WorkManager 2.10.0+, el bloqueo de activación se llamaría de la siguiente manera:

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

Recomendación

  • Actualiza tu versión de WorkManager a la versión estable más reciente para que las etiquetas de bloqueo de activación sean más detalladas en Android 16.1 o versiones posteriores.
  • Audita tu uso de los trabajadores de WorkManager. En particular, verifica que siga nuestra guía para optimizar el uso de la batería para las APIs de programación de tareas. Para que las etiquetas de bloqueo de activación sean más detalladas en Android 16.1 o versiones posteriores, usa el setTraceTag método en el trabajador para agregar más información de depuración, como qué clase programó el trabajador.
  • Si identificas bloqueos de activación creados por WorkManager con un uso elevado de bloqueos de activación, es posible que hayas configurado incorrectamente tu trabajador para que no se complete en ciertas situaciones. Considera analizar los motivos de detención del trabajador, en especial si ves muchas instancias de STOP_REASON_TIMEOUT.
  • Además de registrar los motivos de detención del trabajador, consulta nuestra documentación sobre cómo depurar tus trabajadores. Además, considera recopilar y analizar seguimientos del sistema para comprender cuándo se adquieren y liberan los bloqueos de activación.

_UNKNOWN

Si las herramientas de depuración creen que un nombre de bloqueo de activación contiene información de identificación personal (PII), no muestran el nombre real del bloqueo de activación. En su lugar, etiquetan el bloqueo de activación como _UNKNOWN. Por ejemplo, las herramientas podrían hacer esto si el nombre del bloqueo de activación contiene una dirección de correo electrónico.

Recomendación

Sigue las prácticas recomendadas de asignación de nombres de bloqueos de activación, y evita usar PII en el nombre del bloqueo de activación. Si encuentras un bloqueo de activación llamado _UNKNOWN atribuido a tu app, intenta identificar qué bloqueo de activación es y asígnale un nombre diferente.