Identificar bloqueios de ativação criados por outras APIs

Várias bibliotecas e APIs do sistema podem adquirir bloqueios de despertar atribuíveis ao seu app. Isso pode dificultar a identificação de um bloqueio de despertar no app que pode estar causando um problema. Se você usar uma API de maneira inadequada, isso poderá fazer com que seu app mantenha um wake lock por muito tempo, mesmo que você não esteja chamando as APIs diretamente.

Em cenários em que um wake lock é adquirido por outras APIs, evite a aquisição manual.

Este documento lista alguns nomes comuns de bloqueio de despertar que podem aparecer ao usar as ferramentas de depuração de bloqueio de despertar. Você também pode encontrar esses nomes em um relatório de métricas vitais. Em alguns casos, o bloqueio de despertar pode ter sido criado por uma biblioteca ou API do sistema. Em outros casos, há um motivo para a ferramenta ofuscar o nome do wake lock usado no app. Use as ferramentas de depuração para identificar wake locks com comportamento inadequado e pesquise o nome do wake lock neste documento para identificar qual API pode estar causando o problema e como resolvê-lo.

Este documento aborda os cenários em que os bloqueios de despertar podem ser criados. Em cada caso, embora o bloqueio de despertar possa ser criado por alguma outra biblioteca ou API, ele é atribuído ao app que chamou essa API.

AlarmManager

O AlarmManager adquire wake locks e os atribui ao app de chamada. O AlarmManager adquire o wake lock quando o alarme é acionado e libera o bloqueio quando o método onReceive() da transmissão do alarme termina de ser executado.

Nomes de wake lock

AlarmManager cria bloqueios de despertar com o nome *alarm*. Os asteriscos fazem parte do nome do bloqueio de despertar e não representam caracteres curinga.

Recomendação

Recomendamos as seguintes práticas para otimizar o comportamento dos alarmes:

  • Use AlarmManager para otimizar a frequência de agendamento de alarmes.
  • Use alarmes do tipo RTC_WAKEUP (que ativam o dispositivo) somente quando necessário.
  • Minimize o uso de alarmes e evite fazer trabalhos longos no método onReceive().

Áudio e mídia

As APIs de mídia podem adquirir bloqueios de despertar ao gravar ou tocar áudio. Os bloqueios de ativação são atribuídos ao app que fez a chamada.

Nomes de wake lock

As APIs Media adquirem wake locks com vários nomes que começam com Audio:

  • AudioBitPerfect: usado para reprodução de áudio USB sem perdas.
  • AudioDirectOut: usado para reprodução de áudio sem perdas em uma TV ou dispositivo especial.
  • AudioDup: usado para reproduzir notificações quando conectado por Bluetooth ou USB.
  • AudioIn: usado para captura de áudio no modo filmadora enquanto o microfone está ativo.
  • AudioMix: usado para reprodução de áudio em um dispositivo comum.
  • AudioOffload: usado para reprodução de música apenas em longo prazo, para apps que oferecem suporte a esse modo.
  • AudioSpatial: usado para reprodução de áudio de filmes ou músicas multicanal em dispositivos compatíveis com áudio espacial.
  • AudioUnknown: usado quando as outras situações não se aplicam.
  • MmapCapture: usado para captura de áudio de baixa latência.
  • MmapPlayback: usado para reprodução de baixa latência, como jogos ou aplicativos de áudio profissionais.

Recomendação

Recomendamos as seguintes práticas:

  • Não use nomes de wake lock que comecem com Audio.
  • Se você estiver usando as APIs de mídia, não precisará adquirir bloqueios de despertar diretamente. Basta confiar nas APIs para adquirir os bloqueios de despertar necessários para você.
  • Ao usar APIs de mídia, encerre a sessão quando ela não for mais necessária.

Bluetooth

As APIs Bluetooth da plataforma não mantêm nenhum bloqueio de despertar atribuível ao aplicativo enquanto as ações do Bluetooth ocorrem. Para ajudar a verificar se o transporte Bluetooth ocorre em segundo plano, agende uma tarefa usando o WorkManager.

Recomendação

  • Use o pareamento de dispositivos complementares para parear dispositivos Bluetooth e evitar a aquisição de um bloqueio de despertar manual durante o pareamento Bluetooth.
  • Consulte as orientações sobre comunicação em segundo plano para entender como fazer isso com o Bluetooth.
  • Se um bloqueio de despertar manual for considerado necessário, mantenha-o apenas durante a ação do Bluetooth.

Sensores do dispositivo

Há vários métodos para rastrear dados de sensores do dispositivo, como contagem de passos, dados de acelerômetro ou giroscópio.

No Wear OS, use os Recursos de saúde do Wear para coletar dados do dispositivo, como elevação, frequência cardíaca e distância percorrida.

Se os dados forem coletados por outros aplicativos, use a Conexão Saúde combinada com o WorkManager para recuperar os dados.

Para cenários como rastreamento do delta de etapas ou distância percorrida, use a API Recording em dispositivos móveis combinada com o WorkManager para recuperar os dados.

Em determinadas situações, pode ser necessário usar o rastreamento personalizado de sensores do dispositivo usando SensorManager. SensorManager não adquire bloqueios de despertar em nome do app, a menos que o sensor seja um sensor de despertar, que pode ser identificado usando a API isWakeUpSensor.

Recomendação

Usar sensores para gravar com altas taxas de amostragem pode descarregar a bateria significativamente. Confira algumas recomendações para reduzir o consumo da bateria e o uso de wake lock:

  • Se você estiver rastreando contagens de passos ou distância percorrida, use a API Recording para registrar dados de maneira eficiente em termos de bateria.
  • Para o rastreamento passivo de sensores no Wear OS, use os Recursos de saúde do Wear para otimizar o uso da bateria.
  • Reduza a frequência do sensor para menos de 200 Hz.
  • Ao registrar um sensor com SensorManager, defina um maxReportLatencyUs de mais de 30 segundos para usar a lógica de agrupamento de sensores e reduzir o número de interrupções que o aplicativo recebe.
  • Evite manter um bloqueio de despertar longo durante todo o período de rastreamento do sensor. Em vez disso, programe alarmes usando o AlarmManager para consultar os dados do sensor a cada 30 segundos ou mais.

Firebase Cloud Messaging (FCM)

Um wake lock é adquirido durante a entrega de uma transmissão do Firebase Cloud Message (FCM) ao app. O wake lock é liberado quando o método onMessageReceived() da transmissão do FCM termina a execução.

Nomes de wake lock

Um wake lock é adquirido com o nome GOOGLE_C2DM.

Recomendação

Recomendamos as seguintes práticas para otimizar o comportamento do FCM:

  • Otimize a frequência de entrega do FCM.
  • Não use FCM de alta prioridade, a menos que a mensagem precise ser entregue imediatamente.
  • Conclua o método onMessageReceived() o mais rápido possível. Consulte as orientações do Firebase para mais informações.

JobScheduler

Os jobs do JobScheduler adquirem wake locks ao executar tarefas em segundo plano. Os bloqueios de ativação são atribuídos ao app que criou os workers.

Nomes de wake lock

Os nomes dos bloqueios de despertar adquiridos pelo JobScheduler dependem da versão do sistema Android em que estão sendo executados e da finalidade do job.

Os itens entre colchetes angulares são variáveis. Por exemplo, "<package_name>" é o nome do pacote do seu app, não o texto literal <package name>. No entanto, *job* é a sequência de caracteres *job*, com asteriscos, que não estão sendo usados como curingas.

Android 15 e versões anteriores

Os jobs iniciados pelo usuário criam bloqueios de despertar com nomes que seguem este padrão:

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

Outros jobs usam este padrão:

*job*/@<name_space>@/<package_name>/<classname>
Android 16 e versões mais recentes

Os jobs iniciados pelo usuário criam bloqueios de despertar com nomes que seguem este padrão:

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

Os jobs acelerados usam este padrão:

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

Os jobs regulares usam este padrão:

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

Suponha que haja um job acelerado com o namespace backup e a tag de rastreamento started. O nome do pacote é com.example.app, e a classe que criou o job é com.backup.BackupFileService.

Em dispositivos com Android 15 ou versões anteriores, o bloqueio de despertar seria chamado de:

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

Em dispositivos com o Android 16 ou mais recente, o bloqueio de despertar seria chamado de:

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

Recomendação

Audite seu uso de tarefas do JobScheduler. Em especial, siga nossas orientações para otimizar o uso da bateria para APIs de programação de tarefas.

Local

O LocationManager e o FusedLocationProviderClient usam bloqueios de ativação para adquirir e fornecer a localização do dispositivo. Os bloqueios de despertar são atribuídos ao app que chamou essas APIs.

Nomes de wake lock

Os serviços de localização usam os seguintes nomes:

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

Recomendação

  • Otimizar o uso da localização. Por exemplo, defina tempos limite, agrupe solicitações de localização ou use atualizações de localização passivas.
  • Se você estiver usando as APIs de localização, não precisará adquirir bloqueios de despertar diretamente. Basta confiar nas APIs para adquirir os bloqueios de despertar necessários para você.

WorkManager

Os workers do WorkManager adquirem bloqueios de despertar ao executar tarefas em segundo plano. Os bloqueios de ativação são atribuídos ao app que criou os workers.

Nomes de wake lock

Os nomes de bloqueio de despertar adquiridos pelo WorkManager dependem da versão do sistema Android em que estão sendo executados.

Android 15 e versões anteriores

As tarefas do WorkManager criam bloqueios de despertar com nomes que seguem este padrão:

*job*/<package_name>/androidx.work.impl.background.systemjob.SystemJobService
Android 16 e versões mais recentes

As tarefas priorizadas criam bloqueios de despertar com nomes que seguem este padrão:

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

As tarefas regulares seguem este padrão:

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

Por padrão, <trace_tag> é o nome do worker.

Exemplo

Suponha que haja um worker acelerado chamado BackupFileWorker. O nome do pacote é com.example.app.

Em dispositivos com Android 15 ou versões anteriores, o bloqueio de despertar seria chamado de:

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

Em dispositivos com o Android 16 ou mais recente e usando WorkManager 2.10.0+, o bloqueio de despertar seria chamado de:

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

Recomendação

_UNKNOWN

Se as ferramentas de depuração acharem que um nome de wake lock contém informações de identificação pessoal (PII), elas não vão mostrar o nome real do wake lock. Em vez disso, eles rotulam o bloqueio de despertar como _UNKNOWN. Por exemplo, as ferramentas podem fazer isso se o nome do bloqueio de ativação contiver um endereço de e-mail.

Recomendação

Siga as práticas recomendadas de nomenclatura de wake lock e evite usar PII no nome do wake lock. Se você encontrar um bloqueio de despertar chamado _UNKNOWN atribuído ao seu app, tente identificar qual é esse bloqueio e dê a ele um nome diferente.