Identificar e otimizar casos de uso de bloqueio de despertar

Este documento ajuda você a identificar e otimizar casos de uso de bloqueio de despertar no seu app, além de destacar se há bloqueios de despertar 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 bloqueio de despertar mesmo que você não esteja adquirindo bloqueios de despertar explicitamente.

Este documento lista alguns nomes comuns de bloqueio de despertar que você pode encontrar ao usar as ferramentas de depuração de bloqueio de despertar ou em relatórios dos 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 bloqueios de despertar com comportamento inadequado e pesquisar o nome do bloqueio de despertar 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 bloqueios de despertar, detalhando os nomes usados por várias APIs e bibliotecas, além de fornecer recomendações e práticas recomendadas para otimizar e reduzir o uso de bloqueios de despertar.

AlarmManager

AlarmManager adquire wake locks e os atribui ao app de chamada. 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 bloqueio de despertar 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 no agendamento, 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 a longo prazo em 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 bloqueio de despertar manual durante o pareamento.
  • 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 bloqueio de despertar manual for considerado necessário, mantenha o bloqueio de despertar 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 o rastreamento do delta de etapas ou da 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 de passos ou os passos nas últimas 6 horas), a Conexão Saúde também oferece suporte ao rastreamento de passos no dispositivo para dispositivos 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 descarregar a bateria significativamente. Confira algumas recomendações para reduzir o consumo de bateria e o uso de bloqueio de ativação:

  • 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, considere usar 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 bloqueio de despertar que o sistema mantém para atualizações de localização, você evita a necessidade de um bloqueio de despertar para manter a CPU ativa. Use um worker ou um bloqueio de despertar de curta duração para processar o upload e o processamento desses dados combinados.

Firebase Cloud Message (FCM)

Um wake lock é adquirido ao entregar 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 bloqueio de despertar breve é mantido com o nome GOOGLE_C2DM. No Android 16 e versões mais recentes, o nome do bloqueio de despertar é 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 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.1 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.1 ou mais recente, o bloqueio de despertar 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 bloqueios de ativação criados pelo JobScheduler com alto uso de bloqueio de ativação, 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 despertar 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 bloqueio de despertar 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 despertar do 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 bloqueios de ativação do kernel não são atribuídos ao app, não há nomes de bloqueio de ativação 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 agendar 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 bloqueio de despertar para detectar interrupções de eventos. Quando os pacotes de dados chegam ao Wi-Fi ou ao rádio celular, o hardware do rádio aciona uma interrupção na forma de um bloqueio de despertar do kernel. Em seguida, você pode programar um worker ou adquirir um bloqueio de despertar 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 dos bloqueios 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.1 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

  • Faça upgrade para a versão estável mais recente do WorkManager para tornar as tags de bloqueio de despertar mais detalhadas no Android 16.1 ou versões mais recentes.
  • 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 bloqueio de despertar mais detalhadas no Android 16.1 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 bloqueios de despertar 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 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.