Identificar e otimizar casos de uso de bloqueio de despertar

Este documento ajuda você a identificar e otimizar casos de uso de wake lock no seu app, além de destacar se há wake locks adquiridos por outras bibliotecas ou APIs do sistema associadas a esse caso de uso. Como esses wake locks são atribuíveis ao seu app, pode ser difícil identificar a origem de um wake lock problemático. O uso incorreto da API pode fazer com que seu app seja sinalizado por uso excessivo de wake lock, mesmo que você não esteja adquirindo wake locks explicitamente.

Este documento lista alguns nomes comuns de wake lock que você pode encontrar ao usar as ferramentas de depuração de wake lock ou em relatórios de vitals. Esses nomes podem vir de uma biblioteca ou API do sistema, ou podem estar ofuscados. Ao usar as ferramentas de depuração para identificar wake locks com comportamento inadequado e pesquisar o nome do wake lock neste documento, você pode determinar qual API pode estar causando o problema e encontrar recomendações sobre como otimizar o uso dela.

Este documento descreve casos de uso comuns para aquisição de wake locks, detalhando os nomes de wake lock usados por várias APIs e bibliotecas, além de fornecer recomendações e práticas recomendadas para otimizar e reduzir o uso de wake locks.

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 locks

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

Recomendação

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

  • Consulte escolher o tipo de alarme para decidir entre um alarme inexato ou exato. Se o alarme não precisar ser preciso, use alarmes inexatos para dar ao sistema mais flexibilidade na programação, o que pode melhorar a duração da bateria.
  • Conheça as cotas de alarmes impostas pelo sistema e crie seu app para respeitá-las.
  • Evite fazer trabalhos longos no método onReceive() e agende workers se for necessário processamento adicional após o alarme.

Á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 locks

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 declare nomes de wake lock que comecem com Audio.
  • Se você estiver usando as APIs de mídia, não será necessário adquirir bloqueios de despertar diretamente. Você pode confiar nas APIs para adquirir os bloqueios de despertar necessários para você.
  • Ao usar APIs de mídia, encerre a sessão de mídia e o serviço em primeiro plano associado quando não precisar mais deles.

Bluetooth

As APIs Bluetooth da plataforma mantêm principalmente bloqueios de despertar do kernel enquanto ações de Bluetooth ocorrem, que não são atribuíveis ao aplicativo.

Recomendação

  • Use o pareamento de dispositivos complementares para parear dispositivos Bluetooth e evitar a aquisição de um wake lock manual durante o pareamento Bluetooth.
  • Consulte as orientações sobre comunicação em segundo plano para entender como fazer isso com o Bluetooth.
  • Usar WorkManager geralmente é suficiente se não houver impacto para o usuário em uma comunicação atrasada. Se um wake lock manual for considerado necessário, mantenha o wake lock apenas durante a atividade do Bluetooth ou o processamento dos dados de atividade.

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 periodicamente.

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 periodicamente. Para acessar dados históricos de passos (como o total diário ou os passos nas últimas 6 horas), a Conexão Saúde também oferece suporte ao rastreamento de passos no dispositivo para aparelhos com o Android 14 ou mais recente.

Em algumas situações, pode ser necessário usar o rastreamento personalizado de sensores do dispositivo usando SensorManager. O 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 causar consumo elevado da bateria significativamente. Confira algumas recomendações para reduzir o consumo elevado 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 dispositivos com Android 14 ou mais recente, use a Conexão Saúde para acessar o histórico do dispositivo e a contagem de passos agregada.
  • Para o rastreamento passivo de sensores no Wear OS, use os Recursos de saúde do Wear para otimizar o uso da bateria.
  • 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. Quando o dispositivo é ativado por outro gatilho, como uma interação do usuário, recuperação de local ou um job programado, o sistema envia imediatamente os dados do sensor armazenados em cache.
  • Se o app exigir dados de local e de sensor, sincronize a recuperação e o processamento de eventos. Ao unir as leituras do sensor ao breve wake lock que o sistema mantém para atualizações de localização, você evita a necessidade de um wake lock para manter a CPU ativa. Use um worker ou um wake lock de curta duração para processar o upload e o processamento desses dados combinados.

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 locks

Quando uma mensagem do FCM é recebida no dispositivo, um wake lock breve é mantido com o nome GOOGLE_C2DM. No Android 16 e versões mais recentes, o nome do wake lock é GCM_MESSAGE.

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.
  • Faça com que o método onMessageReceived() seja concluído o mais rápido possível ou agende um worker para continuar a tarefa se for necessário mais processamento. 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 locks

Os nomes dos wake locks 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>

Outras profissões usam esse padrão:

*job*/@<name_space>@/<package_name>/<classname>
Android 16 QPR2 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 priorizado 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 wake lock seria chamado de:

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

Em dispositivos com o Android 16 QPR2 ou mais recente, o wake lock seria chamado de:

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

Recomendação

  • Não adquira um wake lock manual para casos de uso de download/ upload iniciados pelo usuário. Em vez disso, use a API Transferência de dados iniciada pelo usuário (UIDT). Esse é o caminho designado para tarefas de transferência de dados de longa duração iniciadas pelo usuário.
  • Se você identificar wake locks criados pelo JobScheduler com alto uso de wake lock, isso pode ser porque você configurou incorretamente seu job para não ser concluído em determinados cenários. Analise os motivos de interrupção do job, principalmente se você estiver observando muitas ocorrências de STOP_REASON_TIMEOUT.
  • 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 locks

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

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

Recomendação

  • Consulte nossas orientações para otimizar o uso de locais. Considere implementar tempos limite, aproveitar o agrupamento de solicitações de localização ou usar atualizações de localização passivas.
  • Evite adquirir um wake lock contínuo separado para armazenar dados de localização em cache, já que isso é redundante e deve ser removido. Ao solicitar atualizações de localização usando as APIs FusedLocationProvider ou LocationManager, o sistema automaticamente ativa o dispositivo durante o callback do evento de localização. Em vez disso, armazene os eventos de localização na memória ou no armazenamento e processe-os periodicamente usando WorkManager.

Mensagens remotas

Esta seção discute cenários envolvendo mensagens remotas em que os apps podem precisar manter conexões ou reagir a eventos de outros dispositivos, afetando potencialmente o uso do wake lock. Os casos de uso comuns incluem:

  • Apps complementares de monitoramento de vídeo ou som que precisam monitorar eventos em um dispositivo externo conectado por uma rede local.
  • Apps de mensagens que mantêm uma conexão de soquete de rede com uma variante de computador.

A maioria das ativações nesses cenários de mensagens remotas são bloqueios de ativação do kernel. Como os wake locks do kernel não são atribuídos ao app, não há nomes de wake lock associados para listar aqui.

Recomendação

  • Se os eventos de rede puderem ser processados no lado do servidor, use o FCM para receber informações no cliente. Você pode programar um worker acelerado se for necessário processar mais dados do FCM.
  • Se os eventos precisarem ser processados no lado do cliente usando uma conexão de soquete, não será necessário um wake lock para detectar interrupções de eventos. Quando os pacotes de dados chegam ao Wi-Fi ou ao rádio celular, o hardware de rádio aciona uma interrupção na forma de um wake lock do kernel. Em seguida, você pode programar um worker ou adquirir um wake lock para processar os dados.
  • Por exemplo, se você estiver usando ktor-network para detectar pacotes de dados em um soquete de rede, só adquira um wake lock quando os pacotes forem entregues ao cliente.

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 locks

Os nomes de wake lock 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 QPR2 e versões mais recentes

As tarefas aceleradas 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 wake lock seria chamado de:

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

Em dispositivos com o Android 16 QPR2 ou mais recente e usando WorkManager 2.10.0+, o wake lock seria chamado de:

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

Recomendação

  • Faça upgrade da versão do WorkManager para a versão estável mais recente e deixe as tags de wake lock mais detalhadas no Android 16 QPR2 ou mais recente.
  • Audite seu uso de workers do WorkManager. Em especial, verifique se ele segue nossas orientações para otimizar o uso da bateria para APIs de programação de tarefas. Para tornar as tags de wake lock mais detalhadas no Android 16 QPR2 ou versões mais recentes, use o método setTraceTag no worker para adicionar mais informações de depuração, como qual classe programou o worker.
  • Se você identificar wake locks criados pelo WorkManager com uso alto, talvez seja porque você configurou incorretamente o worker para não ser concluído em determinados cenários. Analise os motivos de interrupção do worker, principalmente se você estiver vendo muitas ocorrências de STOP_REASON_TIMEOUT.
  • Além de registrar os motivos da interrupção do worker, consulte nossa documentação sobre depuração de workers. Além disso, considere coletar e analisar rastreamentos do sistema para entender quando os bloqueios de despertar são adquiridos e liberados.

_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 wake lock 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 wake lock chamado _UNKNOWN atribuído ao seu app, tente identificar qual é esse wake lock e dê a ele um nome diferente.