Tempo limite de serviços em primeiro plano

Se um app for direcionado ao Android 15 ou versões mais recentes, o sistema vai impor restrições sobre por quanto tempo determinados serviços em primeiro plano podem ser executados enquanto o app estiver em segundo plano. No momento, essa restrição se aplica apenas a dataSync e serviços em primeiro plano do tipo mediaProcessing. Há limites mais restritivos no tipo de serviço em primeiro plano shortService, que são discutidos na documentação desse tipo de serviço.

Comportamento de tempo limite

O sistema permite que os serviços em primeiro plano dataSync e mediaProcessing sejam executados por um total de 6 horas em um período de 24 horas. Depois disso, o sistema chama o método Service.onTimeout(int, int) do serviço em execução (introduzido no Android 15). O tipo de serviço em primeiro plano mediaProcessing foi adicionado no Android 15. O limite de tempo de seis horas é rastreado separadamente para serviços dataSync e mediaProcessing. Por exemplo, se um serviço dataSync fosse executado por apenas uma hora, o app teria apenas cinco horas disponíveis para os serviços em primeiro plano mediaProcessing, mas teria seis horas completas disponíveis para os serviços do dataSync.

Observação: os serviços em primeiro plano shortService têm um limite de tempo mais restritivo. Para mais informações, consulte a documentação de serviço curto.

Quando um serviço em primeiro plano atinge o limite de seis horas, ele tem alguns segundos para chamar Service.stopSelf(). Quando o sistema chama Service.onTimeout(), o serviço não é mais considerado um serviço em primeiro plano. Se o serviço não chamar Service.stopSelf(), o sistema gerará uma exceção interna. A exceção é registrada no Logcat com a seguinte mensagem:

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

Observação: o limite de tempo de seis horas é compartilhado por todos os serviços em primeiro plano de um app do tipo especificado. Por exemplo, se um app executar um serviço dataSync por quatro horas e iniciar um serviço dataSync diferente, esse segundo serviço só poderá ser executado por duas horas. No entanto, se o usuário colocar o app em primeiro plano, o timer será redefinido e o app terá 6 horas disponíveis.

Para evitar problemas com essa mudança de comportamento, faça uma ou mais das seguintes ações:

1. Faça com que o serviço implemente o novo método Service.onTimeout(int, int). Quando o app receber o callback, chame stopSelf() em alguns segundos. Se você não interromper o app imediatamente, o sistema vai gerar uma falha.
2. Verifique se os serviços dataSync e mediaProcessing do app não são executados por mais de um total de seis horas em qualquer período de 24 horas, a menos que o usuário interaja com o app, redefinindo o timer.
3. Só inicie serviços em primeiro plano dataSync ou mediaProcessing como resultado da interação direta do usuário. Como o app está em primeiro plano quando o serviço é iniciado, ele tem seis horas completas depois que o app vai para o segundo plano.
4. Em vez de usar esses serviços em primeiro plano, use uma API alternativa, como o WorkManager. Em particular, em vez de usar um serviço em primeiro plano dataSync, considere usar uma API alternativa.

Se os serviços em primeiro plano dataSync do app tiverem sido executados por 6 horas nas últimas 24 horas, não será possível iniciar outro serviço em primeiro plano dataSync a menos que o usuário tenha trazido o app para o primeiro plano (o que redefine o timer). Se você tentar iniciar outro serviço em primeiro plano dataSync, o sistema vai gerar ForegroundServiceStartNotAllowedException com uma mensagem de erro como "O limite de tempo já foi esgotado para o tipo de serviço em primeiro plano dataSync".

Teste

Para testar o comportamento do app, é possível ativar tempos limite de sincronização de dados mesmo que o app não seja destinado ao Android 15, desde que esteja em execução em um dispositivo Android 15. Para ativar os tempos limite, execute o comando adb:

adb shell am compat enable FGS_INTRODUCE_TIME_LIMITS your-package-name

Você também pode ajustar o período de tempo limite para facilitar o teste do comportamento do app quando o limite for atingido. Para definir um novo período de tempo limite para serviços em primeiro plano dataSync, execute o seguinte comando adb:

adb shell device_config put activity_manager data_sync_fgs_timeout_duration duration-in-milliseconds

Para definir um novo período de tempo limite para serviços em primeiro plano mediaProcessing, execute este comando:

adb shell device_config put activity_manager media_processing_fgs_timeout_duration duration-in-milliseconds