Os tipos de serviço em primeiro plano são obrigatórios

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:

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

如果以 Android 14 为目标平台的应用使用前台服务,则必须根据前台服务类型声明 Android 14 中引入的特定权限。这些权限显示在本页每种前台服务类型的预期用例和强制执行部分中标记为“您必须在清单文件中声明的权限”的部分。

所有这些权限都定义为一般权限,并默认授予。用户无法撤消这些权限。

Incluir tipo de serviço em primeiro plano no momento da execução

对于启动前台服务的应用,最佳实践是使用 ServiceCompat 版本的 startForeground()(适用于 androidx-core 1.12 及更高版本),并在其中传入前台服务类型的按位整数。您可以选择传递一个或多个类型值。

通常,您应仅声明特定用例所需的类型。这样可以更轻松地满足系统对每种前台服务类型的预期。如果某项前台服务以多种类型启动,则该前台服务必须遵守所有类型的平台强制执行要求

ServiceCompat.startForeground(0, notification, FOREGROUND_SERVICE_TYPE_LOCATION)

如果调用中未指定前台服务类型,则该类型默认为清单中定义的值。如果您没有在清单中指定服务类型,系统会抛出 MissingForegroundServiceTypeException

如果前台服务在您启动后需要新的权限,您应再次调用 startForeground() 并添加新的服务类型。例如,假设健身应用运行一项跑步跟踪器服务,该服务始终需要 location 信息,但不一定需要 media 权限。您需要在清单中同时声明 locationmediaPlayback。如果用户开始跑步并且只想跟踪其位置,您的应用应调用 startForeground() 并仅传递 location 服务类型。然后,如果用户想要开始播放音频,请再次调用 startForeground() 并传递 location|mediaPlayback

Verificações do momento de execução no sistema

系统会检查前台服务类型的使用是否恰当,并确认应用是否已请求适当的运行时权限或使用所需的 API。例如,系统希望使用前台服务类型 FOREGROUND_SERVICE_TYPE_LOCATION 的应用请求 ACCESS_COARSE_LOCATIONACCESS_FINE_LOCATION

这意味着,在向用户请求权限和启动前台服务时,应用必须遵循非常具体的操作顺序。应用在尝试调用 startForeground() 之前,必须先请求并获得所需的权限。在启动前台服务后请求相应权限的应用必须更改此顺序,并在启动前台服务之前请求该权限。

本页面的每种前台服务类型的预期用例和强制执行部分中标记为“运行时要求”的部分列出了平台强制执行的具体内容。

Casos de uso pretendidos e aplicação de cada tipo de serviço em primeiro plano

Para usar determinado tipo de serviço em primeiro plano, é necessário declarar uma permissão específica no arquivo de manifesto e atender a requisitos de execução específicos. Além disso, seu app precisa atender a um dos conjuntos de casos de uso pretendidos para esse tipo. As seções a seguir explicam a permissão que você precisa declarar, os pré-requisitos de execução e os casos de uso pretendidos para cada tipo.

Câmera

要在清单中的 android:foregroundServiceType 下声明的前台服务类型
camera
在清单中声明的权限
FOREGROUND_SERVICE_CAMERA
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_CAMERA
运行时前提条件

请求并获得 CAMERA 运行时权限

注意CAMERA 运行时权限受使用时限制。因此,当您的应用位于后台时,您无法创建 camera 前台服务,但存在一些例外情况。如需了解详情,请参阅有关启动需要运行时权限的前台服务的限制

说明

继续在后台访问摄像头,例如支持多任务的视频聊天应用。

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:

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:

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 plano health 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ção ACCESS_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

要在其清单中声明的前台服务类型
android:foregroundServiceType
microphone
在清单中声明的权限
FOREGROUND_SERVICE_MICROPHONE
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_MICROPHONE
运行时前提条件

请求并获得 RECORD_AUDIO 运行时权限。

注意RECORD_AUDIO 运行时权限受使用时限制。因此,当您的应用位于后台时,您无法创建 microphone 前台服务,但存在一些例外情况。如需了解详情,请参阅有关启动需要运行时权限的前台服务的限制

说明

在后台继续捕获麦克风内容,例如录音器或通信应用。

Ligação telefônica

要在其清单中声明的前台服务类型
android:foregroundServiceType
phoneCall
在清单中声明的权限
FOREGROUND_SERVICE_PHONE_CALL
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_PHONE_CALL
运行时前提条件

必须至少满足以下其中一个条件:

  • 应用通过 ROLE_DIALER 角色成为默认拨号器应用。
说明

使用 ConnectionService API 继续当前通话。

替代方案

如果您需要拨打电话、视频或 VoIP 通话,请考虑使用 android.telecom 库。

不妨考虑使用 CallScreeningService 过滤来电。

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 chamar Service.stopSelf() ou Service.stopForeground() antes que o tempo limite seja atingido. Caso contrário, o novo Service.onTimeout() será chamado, dando aos apps a oportunidade de chamar stopSelf() ou stopForeground() 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 menciona FOREGROUND_SERVICE_TYPE_SHORT_SERVICE. Por esses motivos, uma prática recomendada é implementar o callback Service.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 callback Service.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âmetro FOREGROUND_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 uma ForegroundServiceStartNotAllowedException.

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 tipo shortService. 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 tipo specialUse.

<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
android:foregroundServiceType
systemExempted
Permissão a ser declarada no manifesto
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
Constante a ser transmitida para startForeground()
FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
Pré-requisitos de tempo de execução
Nenhum
Descrição

Reservado para que aplicativos do sistema e integrações específicas do sistema possam continuar usando serviços em primeiro plano.

Para usar esse tipo, um app precisa atender a pelo menos um destes critérios:

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.