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 asociadas con este caso de uso. Como estos bloqueos de activación se pueden atribuir a tu app, puede ser difícil identificar el origen de un bloqueo de activación problemático. El uso incorrecto de la API puede hacer que tu app se marque por un uso excesivo de bloqueos de activación, incluso si no los adquieres 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 API de biblioteca o 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 termina de ejecutarse el 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, no representan comodines).

Recomendación

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

  • Consulta Cómo elegir el 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 respetarlas.
  • Evita realizar tareas prolongadas 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 contenido multimedia pueden adquirir bloqueos de activación cuando graban o reproducen audio. Los bloqueos de activación se atribuyen a la app de llamadas.

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érdidas.
  • AudioDirectOut: Se usa para la reproducción de audio sin pérdidas en una TV o un dispositivo especial.
  • AudioDup: Se usa para la reproducción de notificaciones mientras se establece la conexión con Bluetooth o USB.
  • AudioIn: Se usa para la captura de audio en el 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 prolongada de solo música en las apps que admiten este modo.
  • AudioSpatialSe usa para reproducir 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.
  • MmapPlaybackSe 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 bloqueos de activación que comiencen con Audio.
  • Si usas las APIs de contenido multimedia, no deberías necesitar adquirir bloqueos de activación directamente, ya que puedes confiar en que las APIs adquirirán los bloqueos de activación necesarios por ti.
  • Cuando uses las APIs de contenido multimedia, finaliza la sesión de contenido multimedia y el servicio en primer plano asociado cuando ya no lo 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 se pueden atribuir 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 Bluetooth.
  • Consulta la guía para comunicarse en segundo plano y comprender cómo realizar la comunicación Bluetooth en segundo plano.
  • Usar WorkManager suele ser suficiente si no hay un impacto para el usuario en una comunicación retrasada. Si se considera necesario un bloqueo de activación manual, mantenlo solo 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 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 junto con WorkManager para recuperar los datos de forma periódica.

En situaciones como el seguimiento de la diferencia 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 seguimiento 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 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 con tasas 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 recuentos de pasos o de la distancia recorrida, usa la API de Recording para registrar los datos con un uso eficiente de la batería. En el caso de los 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 de sensores y reducir la cantidad de interrupciones que recibe la aplicación. Cuando el dispositivo se activa posteriormente con otro activador, como una interacción del usuario, la recuperación de la ubicación o un trabajo programado, el sistema enviará de inmediato los datos de sensores almacenados en caché.
  • Si tu app requiere datos de ubicación y de sensores, sincroniza la recuperación y el procesamiento de sus eventos. Si fusionas 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 Messaging (FCM)

Se adquiere un bloqueo de activación mientras se entrega una transmisión de Firebase Cloud Messaging (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 realmente se deba entregar de inmediato.
  • Haz que el método onMessageReceived() se complete lo más rápido posible o programa un trabajador para que continúe con 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 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 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; los asteriscos 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 normales 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 dispositivos con 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 los 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 descarga o carga iniciados por el usuario. En su lugar, usa la API de transferencia de datos iniciada por el usuario (UIDT). Esta es la ruta de acceso 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 de forma incorrecta 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 el 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 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 esto es redundante y se debe quitar. Cuando solicitas actualizaciones de ubicación con las APIs de FusedLocationProvider o LocationManager, el sistema activa automáticamente la activación del 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 en el almacenamiento, y procésalos 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 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 en el cliente. Puedes 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 móvil, el hardware de la radio activa una interrupción en forma de bloqueo de activación del kernel. Luego, puedes 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 los 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 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 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 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 con 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 los 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 el uso de los trabajadores de WorkManager. En particular, verifica que siga nuestra guía para optimizar el uso de la batería en 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 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 se deba a que configuraste de forma incorrecta tu trabajador para que no se complete en ciertas situaciones. Considera analizar los motivos de detención de los trabajadores, en especial si observas una gran cantidad de casos 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. 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 consideran 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 pueden 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.