Para ajudar os desenvolvedores na definição de serviços em
primeiro plano voltados ao usuário, o Android 10 introduziu o atributo android:foregroundServiceType
no elemento <service>
.
Caso o app seja destinado ao Android 14, é necessário especificar os tipos de serviço em primeiro plano adequados. Como nas versões anteriores do Android, vários tipos podem ser combinados. Esta lista mostra os tipos de serviço em primeiro plano que você pode escolher:
camera
connectedDevice
dataSync
health
location
mediaPlayback
mediaProjection
microphone
phoneCall
remoteMessaging
shortService
specialUse
systemExempted
Se um caso de uso no app não estiver associado a nenhum desses tipos, é recomendável migrar a lógica para usar o WorkManager ou jobs de transferência de dados iniciados pelo usuário.
Os tipos health, remoteMessaging, shortService, specialUse
e systemExempted
são novos no Android 14.
O snippet de código abaixo mostra um exemplo de declaração de tipo de serviço em primeiro plano no manifesto:
<manifest ...>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
<application ...>
<service
android:name=".MyMediaPlaybackService"
android:foregroundServiceType="mediaPlayback"
android:exported="false">
</service>
</application>
</manifest>
Se um app destinado ao Android 14 não definir tipos para um determinado serviço
no manifesto, o sistema vai gerar uma MissingForegroundServiceTypeException
ao chamar startForeground()
para o serviço.
Declarar nova permissão para usar tipos de serviço em primeiro plano
Se os apps direcionados ao Android 14 usarem um serviço em primeiro plano, eles precisarão declarar uma permissão específica, com base no tipo de serviço em primeiro plano, que foi introduzida no Android 14. Essas permissões são exibidas nas seções denominadas "permissão que você precisa declarar no arquivo de manifesto" na seção de casos de uso pretendidos e aplicação de cada tipo de serviço em primeiro plano nesta página.
Todas as permissões são definidas como permissões normais e são concedidas por padrão. Os usuários não podem revogar essas permissões.
Incluir tipo de serviço em primeiro plano no momento da execução
A prática recomendada para aplicativos que iniciam serviços em primeiro plano é usar a
versão ServiceCompat
de startForeground()
(disponível no androidx-core
1.12 e mais recentes), em que você transmite um número inteiro
de bits de tipos de serviços em primeiro plano. É possível transmitir um ou mais valores
de tipo.
Normalmente, você precisa declarar apenas os tipos necessários para um caso de uso específico. Isso facilita o cumprimento das expectativas do sistema para cada tipo de serviço em primeiro plano. Nos casos em que um serviço em primeiro plano é iniciado com vários tipos, ele precisa aderir aos requisitos de aplicação da plataforma de todos os tipos.
ServiceCompat.startForeground(0, notification, FOREGROUND_SERVICE_TYPE_LOCATION)
Se o tipo de serviço em primeiro plano não for especificado na chamada, o padrão será
os valores definidos no manifesto. Se você não especificar o tipo de
serviço no manifesto, o sistema vai gerar uma
MissingForegroundServiceTypeException
.
Se o serviço em primeiro plano precisar de novas permissões depois de iniciá-lo, chame startForeground()
novamente e adicione os novos tipos de serviço. Por
exemplo, suponha que um app de fitness execute um serviço de rastreamento de corrida que sempre precisa
de informações location
, mas pode ou não precisar de permissões media
. Você
precisa declarar location
e mediaPlayback
no manifesto. Se um
usuário iniciar uma corrida e só quiser que a localização seja rastreada, seu app precisará chamar
startForeground()
e transmitir apenas o tipo de serviço location
. Em seguida, se o usuário
quiser começar a reproduzir o áudio, chame startForeground()
novamente e transmita
location|mediaPlayback
.
Verificações do momento de execução no sistema
O sistema confere o uso adequado dos tipos de serviço em primeiro plano e confirma se
o app solicitou as permissões de execução adequadas ou se ele usa as APIs necessárias.
Por exemplo, o sistema espera que apps que usam o tipo de serviço em primeiro plano
FOREGROUND_SERVICE_TYPE_LOCATION
solicitem
ACCESS_COARSE_LOCATION
ou ACCESS_FINE_LOCATION
.
Isso significa que os apps precisam seguir uma ordem muito específica
de operações ao solicitar permissões do usuário e iniciar
serviços em primeiro plano. As permissões precisam ser solicitadas e concedidas antes que
o app tente chamar startForeground()
. Os apps que solicitam as permissões
adequadas após a inicialização do serviço em primeiro plano precisam mudar essa ordem
de operações e solicitar a permissão antes de iniciar o serviço.
As especificidades da aplicação da plataforma aparecem nas seções denominadas "requisitos de tempo de execução" na seção de casos de uso pretendidos e aplicação para cada tipo de serviço em primeiro plano nesta página.
Casos de uso pretendidos e aplicação de cada tipo de serviço em primeiro plano
In order to use a given foreground service type, you must declare a particular permission in your manifest file, you must fulfill specific runtime requirements, and your app must fulfill one of the intended sets of use cases for that type. The following sections explain the permission that you must declare, the runtime prerequisites, and the intended use cases for each type.
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 para transmitir para
startForeground()
FOREGROUND_SERVICE_TYPE_CAMERA
- Pré-requisitos do ambiente 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 em 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 em
android:foregroundServiceType
connectedDevice
- Permissão a ser declarada no manifesto
FOREGROUND_SERVICE_CONNECTED_DEVICE
- Constante para transmitir para
startForeground()
FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
- Pré-requisitos do ambiente 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:
Solicitar e receber 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 transferências de dados contínuas para um dispositivo externo, use o gerenciador de dispositivo complementar. Use a API de presença de dispositivo complementar para ajudar o app a continuar em execução enquanto o dispositivo complementar está no alcance.
Se o app precisar procurar dispositivos Bluetooth, use a API de verificação de Bluetooth.
Sincronização de dados
- Tipo de serviço em primeiro plano a ser declarado no manifesto em
android:foregroundServiceType
dataSync
- Permissão a ser declarada no manifesto
FOREGROUND_SERVICE_DATA_SYNC
- Constante para transmitir para
startForeground()
FOREGROUND_SERVICE_TYPE_DATA_SYNC
- Pré-requisitos do ambiente 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 aos serviços em primeiro plano de sincronização de dados para informações detalhadas.
Saúde
- Tipo de serviço em primeiro plano a ser declarado no manifesto em
android:foregroundServiceType
health
- Permissão a ser declarada no manifesto
FOREGROUND_SERVICE_HEALTH
- Constante para transmitir para
startForeground()
FOREGROUND_SERVICE_TYPE_HEALTH
- Pré-requisitos do ambiente de execução
Pelo menos uma das condições a seguir precisa ser verdadeira:
Declare a permissão
HIGH_SAMPLING_RATE_SENSORS
no manifesto.Solicitar e receber pelo menos uma das seguintes permissões de execução:
BODY_SENSORS
no nível 35 da API e anterioresREAD_HEART_RATE
READ_SKIN_TEMPERATURE
READ_OXYGEN_SATURATION
ACTIVITY_RECOGNITION
Observação:as permissões de leitura de
BODY_SENSORS
e baseadas em sensores estão sujeitas 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 está em segundo plano, a menos que você tenha recebido as permissõesBODY_SENSORS_BACKGROUND
(nível 33 a 35 da API) ouREAD_HEALTH_DATA_IN_BACKGROUND
(nível 36 e mais recente da API). Para mais informações, consulte Restrições para iniciar serviços em primeiro plano que precisam de permissões em 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 a ser declarada no manifesto
FOREGROUND_SERVICE_LOCATION
- Constante para transmitir 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 ter 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 local de execução estão sujeitas a restrições de 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 em 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, use a API Geofence.
Mídia
- Tipo de serviço em primeiro plano a ser declarado no manifesto em
android:foregroundServiceType
mediaPlayback
- Permissão a ser declarada no manifesto
FOREGROUND_SERVICE_MEDIA_PLAYBACK
- Constante para transmitir para
startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
- Pré-requisitos do ambiente 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 mostrando um vídeo 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 em
android:foregroundServiceType
mediaProjection
- Permissão a ser declarada no manifesto
FOREGROUND_SERVICE_MEDIA_PROJECTION
- Constante para transmitir para
startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
- Pré-requisitos do ambiente 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. Ele precisa conceder a permissão antes que você possa criar o serviço.Depois de criar o serviço em primeiro plano, você pode chamar
MediaProjectionManager.getMediaProjection()
.- Descrição
Projete 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 transmitir mídia para outro dispositivo, use o SDK do Google Cast.
Microfone
- Tipo de serviço em primeiro plano a ser declarado no manifesto em
android:foregroundServiceType
microphone
- Permissão a ser declarada no manifesto
FOREGROUND_SERVICE_MICROPHONE
- Constante para transmitir para
startForeground()
FOREGROUND_SERVICE_TYPE_MICROPHONE
- Pré-requisitos do ambiente 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 em uso.- Descrição
Continue a captura do microfone em segundo plano, como gravadores de voz ou apps de comunicação.
Ligação telefônica
- Foreground service type to declare in manifest under
android:foregroundServiceType
phoneCall
- Permission to declare in your manifest
FOREGROUND_SERVICE_PHONE_CALL
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_PHONE_CALL
- Runtime prerequisites
At least one of these conditions must be true:
- App has declared the
MANAGE_OWN_CALLS
permission in its manifest file.
- App has declared the
- App is the default dialer app through the
ROLE_DIALER
role.
- App is the default dialer app through the
- Description
Continue an ongoing call using the
ConnectionService
APIs.- Alternatives
If you need to make phone, video, or VoIP calls, consider using the
android.telecom
library.Consider using
CallScreeningService
to screen calls.
Mensagens remotas
- Tipo de serviço em primeiro plano a ser declarado no manifesto em
android:foregroundServiceType
remoteMessaging
- Permissão a ser declarada no manifesto
FOREGROUND_SERVICE_REMOTE_MESSAGING
- Constante para transmitir para
startForeground()
FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
- Pré-requisitos do ambiente 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
- Foreground service type to declare in manifest under
android:foregroundServiceType
shortService
- Permission to declare in your manifest
- None
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_SHORT_SERVICE
- Runtime prerequisites
- None
- Description
Quickly finish critical work that cannot be interrupted or postponed.
This type has some unique characteristics:
- Can only run for a short period of time (about 3 minutes).
- No support for sticky foreground services.
- Cannot start other foreground services.
- Doesn't require a type-specific permission, though it still
requires the
FOREGROUND_SERVICE
permission. - A
shortService
can only change to another service type if the app is currently eligible to start a new foreground service. - A foreground service can change its type to
shortService
at any time, at which point the timeout period begins.
The timeout for shortService begins from the moment that
Service.startForeground()
is called. The app is expected to callService.stopSelf()
orService.stopForeground()
before the timeout occurs. Otherwise, the newService.onTimeout()
is called, giving apps a brief opportunity to callstopSelf()
orstopForeground()
to stop their service.A short time after
Service.onTimeout()
is called, the app enters a cached state and is no longer considered to be in the foreground, unless the user is actively interacting with the app. A short time after the app is cached and the service has not stopped, the app receives an ANR. The ANR message mentionsFOREGROUND_SERVICE_TYPE_SHORT_SERVICE
. For these reasons, it's considered best practice to implement theService.onTimeout()
callback.The
Service.onTimeout()
callback doesn't exist on Android 13 and lower. If the same service runs on such devices, it doesn't receive a timeout, nor does it ANR. Make sure that your service stops as soon as it finishes the processing task, even if it hasn't received theService.onTimeout()
callback yet.It's important to note that if the timeout of the
shortService
is not respected, the app will ANR even if it has other valid foreground services or other app lifecycle processes running.If an app is visible to the user or satisfies one of the exemptions that allow foreground services to be started from the background, calling
Service.StartForeground()
again with theFOREGROUND_SERVICE_TYPE_SHORT_SERVICE
parameter extends the timeout by another 3 minutes. If the app isn't visible to the user and doesn't satisfy one of the exemptions, any attempt to start another foreground service, regardless of type, causes aForegroundServiceStartNotAllowedException
.If a user disables battery optimization for your app, it's still affected by the timeout of shortService FGS.
If you start a foreground service that includes the
shortService
type and another foreground service type, the system ignores theshortService
type declaration. However, the service must still adhere to the prerequisites of the other declared types. For more information, see the Foreground services documentation.
Uso especial
- Tipo de serviço em primeiro plano a ser declarado no manifesto em
android:foregroundServiceType
specialUse
- Permissão a ser declarada no manifesto
FOREGROUND_SERVICE_SPECIAL_USE
- Constante para transmitir para
startForeground()
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
- Pré-requisitos do ambiente 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 fornecidos são livres, e você precisa 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 a ser declarada no manifesto
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
- Constante para transmitir para
startForeground()
FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
- Pré-requisitos do ambiente de execução
- Nenhum
- Descrição
Reservado para que aplicativos do sistema e integrações específicas do sistema possam continuar a usar 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 a permissão
SCHEDULE_EXACT_ALARM
ouUSE_EXACT_ALARM
e que usam o serviço em primeiro plano para continuar alarmes em segundo plano, incluindo alarmes somente para retorno tátil. 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
Se o app for direcionado ao Android 14 ou versões mais recentes, será necessário declarar os tipos de serviço em primeiro plano na página "Conteúdo do app" do Play Console (Política > Conteúdo do app). Para mais informações sobre como declarar seus tipos de serviço em primeiro plano no Play Console, consulte Saiba mais sobre o serviço em primeiro plano e os requisitos de intent para tela cheia.