Resolver problemas de serviços em primeiro plano

Esta página discute alguns motivos comuns pelos quais os serviços em primeiro plano podem falhar e ajuda a identificar o que está causando o problema.

Este documento aborda os seguintes problemas:

Antes de resolver problemas

Verificar se há mudanças recentes nos serviços em primeiro plano

Se os serviços em primeiro plano forem usados incorretamente, eles poderão ter efeitos negativos no desempenho do dispositivo e na duração da bateria. Por esse motivo, as versões da plataforma Android muitas vezes fazem mudanças no comportamento do serviço em primeiro plano para limitar esses efeitos negativos.

Se você tiver problemas com os serviços em primeiro plano, verifique a documentação de mudanças nos serviços em primeiro plano e veja se há mudanças recentes que possam explicar seus problemas. É particularmente importante verificar se há mudanças nessas circunstâncias:

  • O código do serviço em primeiro plano que funcionava antes agora está falhando
  • Você acabou de começar a testar em uma nova versão da plataforma ou mudou o nível da API de destino do app.

Além disso, se você estiver testando o dispositivo em uma prévia para desenvolvedores da plataforma, confira a versão mais recente da documentação da prévia para desenvolvedores.

Erros "O app não está respondendo" (ANR)

Em determinadas circunstâncias, espera-se que um app desligue o serviço em primeiro plano. Se o app não interromper o serviço, o sistema vai interromper o serviço e acionará um erro O app não está respondendo (ANR).

O serviço curto é executado por muito tempo, causando um ANR

Os serviços em primeiro plano que usam o tipo serviço curto precisam ser concluídos rapidamente, em cerca de três minutos. Quando o tempo acabar, o sistema vai chamar o método Service.onTimeout(int,int) do serviço. O serviço tem alguns segundos para chamar stopSelf(). Se o serviço não for interrompido, o sistema vai acionar um erro de aplicativo não respondendo.

Diagnóstico:

Se o ANR for causado por um serviço em primeiro plano que não consegue ser interrompido, o sistema gerará uma exceção interna. Para verificar se esse é o problema, consulte o Logcat. Nesse caso, o registro inclui a seguinte mensagem:

Fatal Exception: android.app.RemoteServiceException: "A foreground service of
type FOREGROUND_SERVICE_TYPE_SHORT_SERVICE did not stop within its timeout:
[component name]"

Correção:

Verifique se todos os serviços em primeiro plano com limite de tempo concluem o trabalho e chamam stopForeground(int) dentro do limite de tempo do sistema.

Implemente Service.onTimeout(int,int) nos seus serviços em primeiro plano. Verifique se a implementação desse método chama stopSelf() imediatamente.

Exceções de serviço em primeiro plano

Esta seção descreve vários problemas de serviço em primeiro plano que podem fazer com que o sistema gere uma exceção. Se o app não detectar a exceção, o usuário vai receber uma caixa de diálogo informando que o app foi interrompido.

Em alguns casos, o sistema gera uma exceção interna. Não é possível capturar essas exceções, mas você pode procurar no Logcat para ver qual exceção foi gerada.

Exceção interna: tempo limite excedido

O sistema impõe um limite sobre o tempo que os serviços em primeiro plano de processamento de mídia e sincronização de dados podem ser executados enquanto o app está em segundo plano. Se o serviço exceder esse limite, o sistema vai chamar o método Service.onTimeout(int,int) do serviço. O serviço tem alguns segundos para chamar stopSelf(). Se o serviço não for interrompido, o sistema vai gerar uma exceção interna que vai causar a falha do app.

Diagnóstico:

Se o tempo limite excedido for a causa, o Logcat vai incluir a seguinte mensagem:

Fatal Exception: android.app.RemoteServiceException: "A foreground service of
type [service type] did not stop within its timeout: [component name]"

Correção:

Verifique se todos os serviços em primeiro plano com tempo limitado concluem o trabalho e chamam stopForeground(int) dentro do limite de tempo do sistema.

Implemente Service.onTimeout(int,int) nos seus serviços em primeiro plano. Verifique se a implementação desse método chama stopSelf() imediatamente.

Exceção interna: ForegroundServiceDidNotStartInTimeException

Quando você inicia um serviço chamando context.startForegroundService(), ele tem alguns segundos para se promover a um serviço em primeiro plano chamando ServiceCompat.startForeground(). Se o serviço não fizer isso, o sistema vai acionar um erro de ANR.

Diagnóstico:

Se um serviço em primeiro plano não for iniciado a tempo, o app vai falhar, fazendo com que o usuário veja uma caixa de diálogo App interrompido. Nesse caso, você pode encontrar a seguinte mensagem no Logcat:

android.app.RemoteServiceException$ForegroundServiceDidNotStartInTimeException:
Context.startForegroundService() did not then call Service.startForeground()

Correção:

Verifique se todos os serviços em primeiro plano recém-criados chamam ServiceCompat.startForeground() em alguns segundos.

ForegroundServiceStartNotAllowedException

Erro:

O sistema gera ForegroundServiceStartNotAllowedException.

Causa:

Isso geralmente é causado pelo app que inicia um serviço em primeiro plano em segundo plano quando não há uma isenção válida.

A partir do Android 12 (nível 31 da API), os apps não podem mais iniciar serviços em primeiro plano enquanto estão em execução em segundo plano, com algumas exceções específicas. Se você tentar iniciar um serviço em primeiro plano em segundo plano e não atender aos requisitos de uma das isenções, o sistema gerará ForegroundServiceStartNotAllowedException. O sistema também faz isso se você não atender aos requisitos da isenção.

Por exemplo, um app pode ter um botão que o usuário pode clicar, o que faz com que ele faça algum processamento e inicie um serviço em primeiro plano. Nesse caso, existe o perigo de o usuário clicar no botão e colocar o app em segundo plano imediatamente. Nesse caso, o app tentaria iniciar o serviço em segundo plano. Se o app não atender a uma das exceções especificadas, o sistema vai gerar uma ForegroundServiceStartNotAllowedException.

Além disso, algumas isenções têm um limite de tempo curto. Por exemplo, há uma breve isenção se o app iniciar um serviço em primeiro plano em resposta a uma mensagem do FCM de alta prioridade. Se você não iniciar o serviço rápido o suficiente, uma ForegroundServiceStartNotAllowedException será gerada.

Às vezes, as isenções específicas ficam mais restritivas com novas versões do Android. Se você mudou a versão do Android que seu app visa, confira a documentação de mudanças nos serviços em primeiro plano e confirme se o app ainda atende a uma das exceções permitidas.

Correção:

Mude o fluxo de trabalho do app para que ele não precise iniciar serviços em primeiro plano enquanto estiver em segundo plano ou confirme se ele atende a uma das isenções.

É possível usar componentes de ciclo de vida, como LiveData, para gerenciar o ciclo de vida do app e evitar que você tente iniciar um serviço em primeiro plano em segundo plano.

SecurityException

Erro:

O sistema gera SecurityException.

Causa:

O app tentou iniciar um serviço em primeiro plano sem as permissões necessárias.

  • Se um app for destinado ao Android 9 (nível 28 da API) ou mais recente, ele precisará ter a permissão FOREGROUND_SERVICE para iniciar um serviço em primeiro plano.
  • Se um app for destinado ao Android 14 (nível 34 da API) ou mais recente, ele precisará atender a todos os pré-requisitos do tipo de serviço em primeiro plano. Esses pré-requisitos são detalhados na documentação de tipos de serviço em primeiro plano. Em particular, observe os seguintes requisitos:
    • Vários tipos de serviço em primeiro plano exigem permissões específicas de execução. Por exemplo, um serviço em primeiro plano de mensagens remotas precisa ter a permissão FOREGROUND_SERVICE_REMOTE_MESSAGING.
  • Em vários casos, há outras restrições de uso em andamento nas permissões necessárias por alguns tipos de serviço em primeiro plano. Essas permissões são concedidas apenas ao app enquanto ele está em primeiro plano (com algumas exceções específicas). Isso significa que, mesmo que o app tenha solicitado e recebido uma dessas permissões, se ele tentar iniciar o serviço em primeiro plano enquanto estiver em segundo plano, o sistema vai gerar uma SecurityException, mesmo que o app tenha uma isenção para iniciar um serviço em primeiro plano em segundo plano. Para mais informações, consulte Restrições para iniciar serviços em primeiro plano que precisam de permissões em uso.
    • Você pode receber uma SecurityException se solicitou as permissões necessárias, mas iniciou o serviço em primeiro plano antes de confirmar que as permissões necessárias foram concedidas.

Correção:

Antes de iniciar o serviço em primeiro plano, solicite todas as permissões adequadas e confirme se você atendeu a todos os outros pré-requisitos de execução.