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.

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 do Android vitals. 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

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 a execução.

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 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 reprodução de notificações quando conectado via 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 use 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 quando ela não for mais necessária.

Firebase Cloud Messaging (FCM)

O GCM adquire um bloqueio de despertar ao entregar uma transmissão do Firebase Cloud Message (FCM) ao app. O bloqueio de despertar é liberado quando o método onMessageReceived() da transmissão do FCM termina a execução.

Nomes de wake lock

O GCM adquire um wake lock 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.

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, o bloqueio de despertar seria chamado de:

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

Recomendação

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

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