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 los bloqueos de activación en tu app, además de destacar si hay bloqueos de activación adquiridos por otras bibliotecas o APIs del sistema asociadas con este caso de uso. Dado que estos bloqueos de activación se atribuyen 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 uso excesivo de bloqueos 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 signos vitales. 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 suena la alarma y lo libera cuando finaliza la ejecución del método onReceive() de la transmisión de la alarma.

Nombres de bloqueo de activación

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

Recomendación

Te recomendamos que sigas estas prácticas para optimizar el comportamiento de las alarmas:

  • Consulta Cómo elegir un tipo de alarma para decidir entre una alarma inexacta o exacta. Si no es necesario que la alarma sea 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 alarmas impuestas por el sistema y diseña tu app para que las respete.
  • Evita realizar trabajos prolongados en el método onReceive() y programa trabajadores si se requiere procesamiento adicional después de la alarma.

Audio y contenido multimedia

Las APIs de medios 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 bloqueo 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 reproducir notificaciones cuando se conecta a través de Bluetooth o USB.
  • AudioIn: Se usa para la captura de audio en el modo de cámara de video 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 a largo plazo solo de música en 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 en juegos o en aplicaciones de audio profesionales.

Recomendación

Te recomendamos que sigas estas prácticas:

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

Bluetooth

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

Recomendación

  • Usa la vinculación de dispositivos complementarios para vincular dispositivos Bluetooth y evitar adquirir un bloqueo de activación manual durante la vinculación por Bluetooth.
  • Consulta la guía sobre comunicación en segundo plano para comprender cómo realizar la comunicación Bluetooth en segundo plano.
  • Usar WorkManager suele ser suficiente si no hay impacto en el usuario por una comunicación retrasada. 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, los datos del acelerómetro o 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 en combinación con WorkManager para recuperar los datos de forma periódica.

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

En ciertas situaciones, es posible que se necesite un seguimiento personalizado del sensor 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

Usar sensores para grabar con frecuencias de muestreo altas puede agotar la batería de forma significativa. A continuación, se incluyen recomendaciones para reducir el agotamiento de la batería y el uso de bloqueos de activación:

  • Si haces un seguimiento de los pasos o la distancia recorrida, usa la API de Recording para registrar los datos de manera eficiente en cuanto al consumo de batería. En dispositivos que ejecutan Android 14 o versiones posteriores, considera usar Health Connect para acceder al historial del dispositivo y al recuento de pasos agregado.
  • 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 del sensor y reducir la cantidad de interrupciones que recibe la aplicación. Cuando otro activador, como una interacción del usuario, una recuperación de ubicación o un trabajo programado, activa el dispositivo, el sistema enviará de inmediato los datos del sensor almacenados en caché.
  • Si tu app requiere datos de ubicación y del sensor, sincroniza su recuperación y procesamiento de eventos. Al unir las lecturas de los sensores en el breve bloqueo de activación que el sistema mantiene 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 bloqueo de activación

Cuando se recibe un mensaje de FCM en el dispositivo, se mantiene un bloqueo de activación breve 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 que sigas estas prácticas para optimizar el comportamiento de FCM:

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

JobScheduler

Los trabajos 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 subprocesos.

Nombres de bloqueo 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 del trabajo.

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, que no se usan como comodines.

Android 15 y versiones anteriores

Los trabajos iniciados por el usuario crean bloqueos de activación con nombres que siguen este patrón:

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

Otros trabajos usan este patrón:

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

Los trabajos iniciados por el usuario crean bloqueos de activación con nombres que siguen este patrón:

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

Los trabajos acelerados usan este patrón:

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

Los trabajos regulares usan este patrón:

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

Supongamos que hay un trabajo acelerado 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ó el trabajo es com.backup.BackupFileService.

En los 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 QPR2 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 carga o descarga 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 que inicia 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 trabajo para que no se complete en ciertas situaciones. Considera analizar los motivos de detención del trabajo, en especial si observas una gran cantidad de casos 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 en 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 bloqueo 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 utilizar actualizaciones de ubicación pasivas.
  • 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 el 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 de forma periódica 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 del bloqueo de activación. Los casos de uso comunes incluyen los siguientes:

  • Apps complementarias de monitoreo de video o sonido que necesitan monitorear 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 para computadoras.

La mayoría de las activaciones en estos casos 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 bloqueo 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 en 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 del lado del 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 hardware de la radio 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 se hayan entregado paquetes al cliente.

WorkManager

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

Nombres de bloqueo 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 QPR2 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 periódicas 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 los 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 QPR2 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 QPR2 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 QPR2 o versiones posteriores, usa el método setTraceTag en el trabajador para agregar más información de depuración, como la clase que programó el trabajador.
  • Si identificas bloqueos de activación creados por WorkManager con un uso alto 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 observas una gran cantidad de STOP_REASON_TIMEOUT.
  • Además de registrar los motivos de detención de los trabajadores, consulta nuestra documentación sobre cómo depurar tus trabajadores. También considera recopilar y analizar registros 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 mostrarán 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 para asignar nombres a los 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 de qué bloqueo de activación se trata y asígnale un nombre diferente.