No Android 14 (nível 34 da API) e versões mais recentes, é necessário declarar um tipo de
serviço adequado para cada serviço em primeiro plano. Isso significa que você precisa declarar o
tipo de serviço no manifesto do app e solicitar a permissão de serviço em primeiro plano
adequada para esse tipo, além de solicitar a
permissão
FOREGROUND_SERVICE
. Além disso, dependendo do tipo de serviço em primeiro plano, talvez
seja necessário solicitar permissões de execução antes de iniciar o serviço.
Câmera
- Tipo de serviço em primeiro plano a ser declarado no manifesto em
android:foregroundServiceType
camera
- Permissão a ser declarada no manifesto
FOREGROUND_SERVICE_CAMERA
- Constante a ser transmitida para
startForeground()
FOREGROUND_SERVICE_TYPE_CAMERA
- Pré-requisitos de tempo de execução
Solicitar e receber a permissão de execução
CAMERA
Observação:a permissão de execução
CAMERA
está sujeita a restrições durante o uso. Por esse motivo, não é possível criar um serviço em primeiro planocamera
enquanto o app está em segundo plano, com algumas exceções. Para mais informações, consulte Restrições para iniciar serviços em primeiro plano que precisam de permissões durante o uso.- Descrição
Continue acessando a câmera em segundo plano, como em apps de chat por vídeo que permitem várias tarefas.
Dispositivo conectado
- Tipo de serviço em primeiro plano a ser declarado no manifesto
android:foregroundServiceType
connectedDevice
- Permissão a ser declarada no manifesto
FOREGROUND_SERVICE_CONNECTED_DEVICE
- Constante a ser transmitida para
startForeground()
FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
- Pré-requisitos de tempo de execução
Pelo menos uma das condições a seguir precisa ser verdadeira:
Declare pelo menos uma das permissões a seguir no manifesto:
Solicite e receba pelo menos uma das seguintes permissões de execução:
- Descrição
Interações com dispositivos externos que exigem uma conexão Bluetooth, NFC, IR, USB ou de rede.
- Alternativas
Se o app precisar fazer uma transferência contínua de dados para um dispositivo externo, use o gerenciador de dispositivos complementar. Use a API de presença de dispositivo complementar para ajudar o app a continuar em execução enquanto o dispositivo complementar estiver ao alcance.
Se o app precisar procurar dispositivos Bluetooth, use a API Bluetooth Scan.
Sincronização de dados
- Tipo de serviço em primeiro plano a ser declarado no manifesto
android:foregroundServiceType
dataSync
- Permissão a ser declarada no manifesto
FOREGROUND_SERVICE_DATA_SYNC
- Constante a ser transmitida para
startForeground()
FOREGROUND_SERVICE_TYPE_DATA_SYNC
- Pré-requisitos de tempo de execução
- Nenhum
- Descrição
Operações de transferência de dados, como as seguintes:
- Upload ou download de dados
- Operações de backup e restauração
- Operações de importação ou exportação
- Busca de dados
- Processamento local de arquivos
- Transferência de dados entre um dispositivo e a nuvem por uma rede
- Alternativas
Consulte Alternativas à sincronização de dados para serviços em primeiro plano para informações detalhadas.
Saúde
- Tipo de serviço em primeiro plano a ser declarado no manifesto
android:foregroundServiceType
health
- Permissão a ser declarada no manifesto
FOREGROUND_SERVICE_HEALTH
- Constante a ser transmitida para
startForeground()
FOREGROUND_SERVICE_TYPE_HEALTH
- Pré-requisitos de tempo de execução
Pelo menos uma das condições a seguir precisa ser verdadeira:
Declare a permissão
HIGH_SAMPLING_RATE_SENSORS
no manifesto.Solicite e receba pelo menos uma das seguintes permissões de execução:
Observação:a permissão de execução
BODY_SENSORS
está sujeita a restrições durante o uso. Por esse motivo, não é possível criar um serviço em primeiro planohealth
que use sensores corporais enquanto o app estiver em segundo plano, com algumas exceções. Para mais informações, consulte Restrições para iniciar serviços em primeiro plano que precisam de permissões durante o uso.- Descrição
Todos os casos de uso de longa duração que oferecem suporte a apps na categoria fitness, como apps de monitoramento de atividade física.
Local
- Tipo de serviço em primeiro plano a ser declarado no manifesto em
android:foregroundServiceType
location
- Permissão para declarar no manifesto
FOREGROUND_SERVICE_LOCATION
- Constante a ser transmitida para
startForeground()
FOREGROUND_SERVICE_TYPE_LOCATION
- Pré-requisitos do ambiente de execução
O usuário precisa ter ativado os Serviços de localização, e o app precisa receber pelo menos uma das seguintes permissões de execução:
Observação:para verificar se o usuário ativou os serviços de localização e concedeu acesso às permissões de execução, use
PermissionChecker#checkSelfPermission()
.Observação:as permissões de execução de local estão sujeitas a restrições durante o uso. Por esse motivo, não é possível criar um serviço em primeiro plano
location
enquanto o app está em segundo plano, a menos que você tenha recebido a permissão de execuçãoACCESS_BACKGROUND_LOCATION
. Para mais informações, consulte Restrições para iniciar serviços em primeiro plano que precisam de permissões durante o uso.- Descrição
Casos de uso de longa duração que exigem acesso à localização, como navegação e compartilhamento de local.
- Alternativas
Se o app precisar ser acionado quando o usuário chegar a locais específicos, considere usar a API Geoofence.
Mídia
- Tipo de serviço em primeiro plano a ser declarado no manifesto
android:foregroundServiceType
mediaPlayback
- Permissão a ser declarada no manifesto
FOREGROUND_SERVICE_MEDIA_PLAYBACK
- Constante a ser transmitida para
startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
- Pré-requisitos de tempo de execução
- Nenhum
- Descrição
- Continue reproduzindo áudio ou vídeo em segundo plano. Suporte à funcionalidade de gravação de vídeo digital (DVR) no Android TV.
- Alternativas
- Se você estiver exibindo vídeos picture-in-picture, use o modo picture-in-picture.
Projeção de mídia
- Tipo de serviço em primeiro plano a ser declarado no manifesto
android:foregroundServiceType
mediaProjection
- Permissão a ser declarada no manifesto
FOREGROUND_SERVICE_MEDIA_PROJECTION
- Constante a ser transmitida para
startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
- Pré-requisitos de tempo de execução
Chame o método
createScreenCaptureIntent()
antes de iniciar o serviço em primeiro plano. Isso mostra uma notificação de permissão ao usuário, que precisa concedê-la antes de você criar o serviço.Depois de criar o serviço em primeiro plano, chame
MediaProjectionManager.getMediaProjection()
.- Descrição
Projete o conteúdo em uma tela secundária ou um dispositivo externo usando as APIs
MediaProjection
. Esse conteúdo não precisa ser exclusivamente de mídia.- Alternativas
Para fazer streaming de mídia em outro dispositivo, use o SDK do Google Cast.
Microfone
- Tipo de serviço em primeiro plano a ser declarado no manifesto
android:foregroundServiceType
microphone
- Permissão a ser declarada no manifesto
FOREGROUND_SERVICE_MICROPHONE
- Constante a ser transmitida para
startForeground()
FOREGROUND_SERVICE_TYPE_MICROPHONE
- Pré-requisitos de tempo de execução
Solicite e receba a permissão de execução
RECORD_AUDIO
.Observação:a permissão de execução
RECORD_AUDIO
está sujeita a restrições durante o uso. Por esse motivo, não é possível criar um serviço em primeiro planomicrophone
enquanto o app está em segundo plano, com algumas exceções. Para mais informações, consulte Restrições para iniciar serviços em primeiro plano que precisam de permissões durante o uso.- Descrição
Continue a captura do microfone em segundo plano, como gravadores de voz ou apps de comunicação.
Ligação telefônica
- Tipo de serviço em primeiro plano a ser declarado no manifesto
android:foregroundServiceType
phoneCall
- Permissão a ser declarada no manifesto
FOREGROUND_SERVICE_PHONE_CALL
- Constante a ser transmitida para
startForeground()
FOREGROUND_SERVICE_TYPE_PHONE_CALL
- Pré-requisitos de tempo de execução
Pelo menos uma destas condições precisa ser verdadeira:
- O app declarou a permissão
MANAGE_OWN_CALLS
no arquivo de manifesto.
- O app declarou a permissão
- Esse é o app de discador padrão com o papel
ROLE_DIALER
.
- Esse é o app de discador padrão com o papel
- Descrição
Continue uma chamada usando as APIs
ConnectionService
.- Alternativas
Se você precisar fazer chamadas telefônicas, de vídeo ou VoIP, considere usar a biblioteca
android.telecom
.Use o
CallScreeningService
para filtrar ligações.
Mensagens remotas
- Tipo de serviço em primeiro plano a ser declarado no manifesto
android:foregroundServiceType
remoteMessaging
- Permissão a ser declarada no manifesto
FOREGROUND_SERVICE_REMOTE_MESSAGING
- Constante a ser transmitida para
startForeground()
FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
- Pré-requisitos de tempo de execução
- Nenhum
- Descrição
- Transferir mensagens de texto de um dispositivo para outro. Ajuda na continuidade das tarefas de mensagens de um usuário ao trocar de dispositivo.
Serviço curto
- Tipo de serviço em primeiro plano a ser declarado no manifesto
android:foregroundServiceType
shortService
- Permissão a ser declarada no manifesto
- Nenhum
- Constante a ser transmitida para
startForeground()
FOREGROUND_SERVICE_TYPE_SHORT_SERVICE
- Pré-requisitos de tempo de execução
- Nenhum
- Descrição
Conclua rapidamente trabalhos essenciais que não podem ser interrompidos ou adiados.
Esse tipo tem algumas características únicas:
- Pode ser executado por um curto período de tempo (cerca de três minutos).
- Não oferece suporte a serviços fixos em primeiro plano.
- Não inicia outros serviços em primeiro plano.
- Não requer uma permissão específica do tipo, embora ainda
exija a permissão
FOREGROUND_SERVICE
. - Um
shortService
só poderá mudar para outro tipo de serviço se o app estiver qualificado para iniciar um novo serviço em primeiro plano. - Um serviço em primeiro plano pode mudar o próprio tipo para
shortService
a qualquer momento, quando o tempo limite começa.
O tempo limite de shortService começa no momento em que
Service.startForeground()
é chamado. O app precisa chamarService.stopSelf()
ouService.stopForeground()
antes que o tempo limite seja atingido. Caso contrário, o novoService.onTimeout()
será chamado, dando aos apps a oportunidade de chamarstopSelf()
oustopForeground()
para interromper o serviço.Pouco depois que
Service.onTimeout()
é chamado, o app entra em um estado em cache e não é mais considerado em primeiro plano, a menos que o usuário esteja interagindo ativamente com ele. Se o app entra nesse estado e o serviço não é interrompido, o app recebe um erro ANR. A mensagem ANR mencionaFOREGROUND_SERVICE_TYPE_SHORT_SERVICE
. Por esses motivos, uma prática recomendada é implementar o callbackService.onTimeout()
.O callback
Service.onTimeout()
não existe no Android 13 e nas versões anteriores. Se o mesmo serviço for executado nesses dispositivos, ele não receberá um tempo limite nem um erro ANR. Confira se o serviço é interrompido assim que a tarefa de processamento é terminada, mesmo que ele ainda não tenha recebido o callbackService.onTimeout()
.É importante observar que, se o tempo limite do
shortService
não for respeitado, o app receberá um erro ANR mesmo que tenha outros serviços em primeiro plano válidos ou outros processos de ciclo de vida em execução.Se um app estiver visível para o usuário ou atender a uma das isenções que permitem que serviços em primeiro plano sejam iniciados em segundo plano, chame
Service.StartForeground()
novamente com o parâmetroFOREGROUND_SERVICE_TYPE_SHORT_SERVICE
, que estende o tempo limite em mais três minutos. Se o app não estiver visível para o usuário e não atender a uma das isenções, qualquer tentativa de iniciar outro serviço em primeiro plano, independente do tipo, vai causar umaForegroundServiceStartNotAllowedException
.Se um usuário desativar a otimização da bateria para seu app, ele ainda será afetado pelo tempo limite do shortService FGS.
Se você iniciar um serviço em primeiro plano que inclua o tipo
shortService
e outro tipo de serviço em primeiro plano, o sistema vai ignorar a declaração do tiposhortService
. No entanto, o serviço ainda precisará aderir aos pré-requisitos dos outros tipos declarados. Para mais informações, consulte a documentação de serviços em primeiro plano.
Uso especial
- Tipo de serviço em primeiro plano a ser declarado no manifesto
android:foregroundServiceType
specialUse
- Permissão a ser declarada no manifesto
FOREGROUND_SERVICE_SPECIAL_USE
- Constante a ser transmitida para
startForeground()
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
- Pré-requisitos de tempo de execução
- Nenhum
- Descrição
Abrange todos os casos de uso de serviço em primeiro plano válidos que não são abrangidos por outros tipos de serviço em primeiro plano.
Além de declarar o tipo de serviço em primeiro plano
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
, os desenvolvedores precisam declarar casos de uso no manifesto. Para fazer isso, especifique o elemento<property>
no elemento<service>
. Esses valores e os casos de uso correspondentes são analisados quando você envia o app no Google Play Console. Os casos de uso que você fornece têm formato livre, e é preciso fornecer informações suficientes para que o revisor entenda por que você precisa usar o tipospecialUse
.<service android:name="fooService" android:foregroundServiceType="specialUse"> <property android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE" android:value="explanation_for_special_use"/> </service>
Sistema isento
- Tipo de serviço em primeiro plano a ser declarado no manifesto em
android:foregroundServiceType
systemExempted
- Permissão para declarar no manifesto
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
- Constante a ser transmitida para
startForeground()
FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
- Pré-requisitos do ambiente de execução
- Nenhum
- Descrição
Reservado para aplicativos do sistema e integrações específicas do sistema, para e continuar usando os serviços em primeiro plano.
Para usar esse tipo, um app precisa atender a pelo menos um destes critérios:
- O dispositivo está no modo de demonstração
- O app é proprietário do dispositivo
- O app é proprietário do perfil
- Apps de segurança que têm o papel
ROLE_EMERGENCY
- Apps do administrador do dispositivo
- Apps com
SCHEDULE_EXACT_ALARM
ouUSE_EXACT_ALARM
e estão usando Serviço em primeiro plano para continuar alarmes em segundo plano, incluindo alarmes táteis. Apps de VPN (configurados usando Configurações > Rede e Internet > VPN)
Caso contrário, a declaração desse tipo faz com que o sistema gere uma
ForegroundServiceTypeNotAllowedException
.
Aplicação da política do Google Play para uso de tipos de serviço em primeiro plano
Caso o app seja destinado ao Android 14 ou versões mais recentes, declare os tipos de serviço em primeiro plano na página de conteúdo do app no Play Console (Política > Conteúdo do app). Para mais informações sobre como declarar os tipos de serviço em primeiro plano no Play Console, consulte Noções básicas sobre o serviço em primeiro plano e os requisitos de intent para tela cheia.