Identificar e otimizar casos de uso de bloqueio de despertar

Este documento ajuda a identificar e otimizar os casos de uso de wake locks 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 o app seja sinalizado por uso excessivo de wake locks, mesmo que você não esteja adquirindo wake locks explicitamente.

Este documento lista alguns nomes comuns de wake locks que você pode encontrar ao usar as ferramentas de depuração de wake locks ou em relatórios de vitals. Esses nomes podem ser originados de uma biblioteca ou API do sistema ou podem ser ofuscados. Ao usar as ferramentas de depuração para identificar wake locks com comportamento inadequado e, em seguida, pesquisar o nome do wake lock neste documento, é possível 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 adquirir wake locks, detalhando os nomes de wake lock usados por várias APIs e bibliotecas, e fornece recomendações e práticas recomendadas para otimizar e reduzir o uso de wake locks.

AlarmManager

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

Nomes de wake lock

O AlarmManager cria wake locks com o nome *alarm*. Os asteriscos fazem parte do nome do wake lock, não representam caracteres curinga.

Recomendação

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

  • Consulte Escolher o tipo de alarme para decidir entre um alarme inexato ou exato. Se o alarme não precisar ser preciso, use alarmes imprecisos para dar ao sistema mais flexibilidade na programação, o que pode melhorar a duração da bateria.
  • Esteja ciente das cotas de alarme impostas pelo sistema e projete seu app para respeitá-las.
  • Evite realizar tarefas longas no método onReceive() e programe workers se for necessário fazer mais processamento após o alarme.

Áudio e mídia

As APIs de mídia podem adquirir wake locks ao gravar ou reproduzir áudio. Os wake locks são atribuídos ao app de ligação.

Nomes de wake lock

As APIs de mídia 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 o dispositivo está conectado por Bluetooth ou USB.
  • AudioIn: usado para captura de áudio no modo de 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 de longo prazo, para apps que oferecem suporte a esse modo.
  • AudioSpatial: usado para reprodução de áudio multicanal de filmes ou músicas 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 em jogos ou em 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 wake locks diretamente. Você pode confiar nas APIs para adquirir os wake locks 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 de Bluetooth da plataforma mantêm principalmente wake locks do kernel enquanto as 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 a comunicação Bluetooth em segundo plano.
  • O uso de 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 apenas durante a atividade do Bluetooth ou o processamento dos dados da atividade.

Sensores do dispositivo

Há vários métodos para monitorar dados de sensores do dispositivo, como contagem de passos, dados do acelerômetro ou do 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, você poderá usar o Conexão Saúde combinado com o WorkManager para recuperar os dados periodicamente.

Para cenários como o acompanhamento de delta de passos 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 dispositivos com o Android 14 ou mais recente.

Em determinadas situações, pode ser necessário usar o rastreamento personalizado de sensores de dispositivos com SensorManager. O SensorManager não adquire wake locks em nome do app, a menos que o sensor seja de ativação, que pode ser identificado usando a API isWakeUpSensor.

Recomendação

O uso de sensores para gravar em altas taxas de amostragem pode consumir muita bateria. Confira algumas recomendações para reduzir o consumo de bateria e o uso de wake locks:

  • Se estiver monitorando a contagem de passos ou a distância percorrida, use a API Recording para registrar dados de maneira eficiente em termos de bateria. Para dispositivos com o Android 14 ou mais recente, use o 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 lote de sensores e reduzir o número de interrupções que o aplicativo recebe. Quando o dispositivo é ativado por outro acionador, como uma interação do usuário, uma 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 localização e dados do sensor, sincronize a recuperação e o processamento de eventos. Ao agrupar as leituras do sensor no breve wake lock que o sistema mantém para atualizações de local, 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 ao entregar uma transmissão do Firebase Cloud Messaging (FCM) ao app. O wake lock é liberado quando o método de transmissão onMessageReceived() do FCM termina de ser executado.

Nomes de wake lock

Quando uma mensagem do FCM é recebida no dispositivo, um breve wake lock é 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 o FCM de alta prioridade, a menos que a mensagem realmente precise ser entregue imediatamente.
  • Conclua o método onMessageReceived() o mais rápido possível ou programe 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 wake locks são atribuídos ao app que criou os workers.

Nomes de wake lock

Os nomes de wake lock 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 app, não o texto literal <package name>. No entanto, *job* é a sequência de caracteres *job*, com asteriscos. Os asteriscos não estão sendo usados como caracteres curinga.

Android 15 e versões anteriores

Os jobs iniciados pelo usuário criam wake locks 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 QPR2 e versões mais recentes

Os jobs iniciados pelo usuário criam wake locks com nomes que seguem este padrão:

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

Os jobs priorizados 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 trace started. O nome do pacote é com.example.app, e a classe que criou o job é com.backup.BackupFileService.

Em dispositivos com o 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 nomeado:

*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 User-Initiated Data Transfer (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, pode ser que você tenha configurado incorretamente o job para não ser concluído em determinados cenários. Analise os motivos de interrupção do job, principalmente se você estiver vendo muitas ocorrências de STOP_REASON_TIMEOUT.
  • Audite o 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

LocationManager e FusedLocationProviderClient usam wake locks para adquirir e fornecer a localização do dispositivo. Os wake locks 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

  • Consulte nossas orientações para otimizar o uso da localização. Considere implementar tempos limite, usar o lote de solicitações de localização ou utilizar atualizações do local passivas.
  • Evite adquirir um wake lock contínuo separado para armazenar dados de local em cache, já que isso é redundante e precisa ser removido. Ao solicitar atualizações do local usando as APIs FusedLocationProvider ou LocationManager, o sistema ativa automaticamente 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

Nesta seção, discutimos cenários que envolvem mensagens remotas em que os apps podem precisar manter conexões ou reagir a eventos de outros dispositivos, o que pode afetar o uso de wake locks. Os casos de uso comuns incluem:

  • Apps complementares de monitoramento de vídeo ou som que precisam monitorar eventos que ocorrem 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 para computador.

A maioria das ativações nesses cenários de mensagens remotas são wake locks 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 servidor, use o FCM para receber informações no cliente. É possível 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, um wake lock não será necessário para detectar interrupções de eventos. Quando os pacotes de dados chegam ao rádio Wi-Fi ou celular, o hardware do 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, adquira um wake lock somente quando os pacotes forem entregues ao cliente.

WorkManager

Os workers do WorkManager adquirem wake locks ao executar tarefas em segundo plano. Os wake locks são atribuídos ao app que criou os workers.

Nomes de wake lock

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 wake locks 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 wake locks 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 o 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 versões mais recentes e que usam 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 para tornar as tags de wake lock mais detalhadas no Android 16 QPR2 ou mais recente.
  • Audite o 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 alto uso de wake lock, 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 de interrupção dos workers, consulte nossa documentação sobre como depurar seus workers. Além disso, considere coletar e analisar rastreamentos do sistema para entender quando os wake locks são adquiridos e liberados.

_UNKNOWN

Se as ferramentas de depuração identificarem 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 wake lock 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ê um nome diferente a ele.