Tipos de serviços em primeiro plano

A partir do Android 14 (nível 34 da API), é 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 também 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.

Observação: em muitos casos, há APIs criadas para fins específicos que podem ser usadas em vez de criar um tipo específico de serviço em primeiro plano. Quando APIs criadas para fins específicos estão disponíveis, elas geralmente são uma opção melhor do que criar um serviço em primeiro plano. Essas APIs estão listadas nas seções Alternativas nos tipos de serviço em primeiro plano adequados.

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 a startForeground()

FOREGROUND_SERVICE_TYPE_CAMERA

Pré-requisitos de ambiente de execução

Solicitar e receber a permissão de execução CAMERA

Observação: a permissão de tempo de execução CAMERA está sujeita a restrições de uso. Por isso, não é possível criar um serviço em primeiro plano camera enquanto o app está em segundo plano nem iniciar um serviço em primeiro plano camera de um receptor BOOT_COMPLETED, com algumas exceções. Para mais informações, consulte Restrições para iniciar serviços em primeiro plano que precisam de permissões de 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:

  • CHANGE_NETWORK_STATE
  • CHANGE_WIFI_STATE
  • CHANGE_WIFI_MULTICAST_STATE
  • NFC
  • TRANSMIT_IR

• Solicitar e receber pelo menos uma das seguintes permissões de execução:

  • BLUETOOTH_CONNECT
  • BLUETOOTH_ADVERTISE
  • BLUETOOTH_SCAN
  • UWB_RANGING

• Chamar UsbManager.requestPermission()

Descrição

Interações com dispositivos externos que exigem uma conexão Bluetooth, NFC, IR, USB ou de rede.

Observação: se o app realiza uma operação de projeção ou mensagens remotas, use o tipo de projeção de mídia ou mensagens remotas correspondente.

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 a startForeground()

FOREGROUND_SERVICE_TYPE_DATA_SYNC

Pré-requisitos de 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

Observação: os apps destinados ao Android 15 ou versões mais recentes não podem iniciar um serviço em primeiro plano de sincronização de dados de um broadcast receiver BOOT_COMPLETED. Para mais informações, consulte Restrições para receptores de transmissão BOOT_COMPLETED que iniciam serviços em primeiro plano.

Alternativas

Consulte Alternativas aos serviços de sincronização de dados em primeiro plano para informações detalhadas.

Saúde

要在清单中的以下位置声明的前台服务类型

android:foregroundServiceType

health

在清单中声明的权限

FOREGROUND_SERVICE_HEALTH

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_HEALTH

运行时前提条件

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

• 在清单中声明 HIGH_SAMPLING_RATE_SENSORS 权限。

• 至少请求并被授予以下其中一项运行时权限：

  • BODY_SENSORS（API 35 及更低版本中）
  • READ_HEART_RATE
  • READ_SKIN_TEMPERATURE
  • READ_OXYGEN_SATURATION
  • ACTIVITY_RECOGNITION

注意： BODY_SENSORS 和基于传感器的读取运行时权限受“在使用时”限制。因此，除非您已获得 BODY_SENSORS_BACKGROUND（API 级别 33 到 API 级别 35）或 READ_HEALTH_DATA_IN_BACKGROUND（API 级别 36）权限，否则您无法创建在应用处于后台运行时使用身体传感器的 health 前台服务。如需了解详情，请参阅与启动需要“使用时”权限的前台服务相关的限制。

说明

为健身类别的应用（例如锻炼追踪器）提供支持的所有长时间运行的用例。

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:

• ACCESS_COARSE_LOCATION
• ACCESS_FINE_LOCATION

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 localização 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, use a API Geofence.

Mídia

要在清单中声明的前台服务类型，位于

android:foregroundServiceType

mediaPlayback

要在清单中声明的权限

FOREGROUND_SERVICE_MEDIA_PLAYBACK

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK

运行时前提条件

无

说明

在后台继续播放音频或视频。在 Android TV 上支持数字视频录制 (DVR) 功能。

注意： 以 Android 15 或更高版本为目标平台的应用不得从 BOOT_COMPLETED 广播接收器启动媒体播放前台服务。如需了解详情，请参阅与 BOOT_COMPLETED 广播接收器启动前台服务相关的限制。

替代方案

如果您要显示画中画视频，请使用画中画模式。

Mídia em processamento

要在清单中的以下位置声明的前台服务类型

android:foregroundServiceType

mediaProcessing

在清单中声明的权限

FOREGROUND_SERVICE_MEDIA_PROCESSING

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING

运行时前提条件

无

说明

用于对媒体资源执行耗时的操作（例如将媒体转换为其他格式）的服务。系统允许此服务运行的时间有限；在正常情况下，此时限为每天 24 小时中的 6 小时。（此限制由应用的所有 mediaProcessing 前台服务共享。）

在以下情况下，您的应用应手动停止媒体处理服务：

• 当转码操作完成或达到失败状态时，让服务调用 Service.stopForeground() 和 Service.stopSelf() 以完全停止服务。

如果超时期限已到，系统会调用服务的 Service.onTimeout(int, int) 方法。此时，该服务有几秒钟的时间来调用 Service.stopSelf()。如果服务未调用 Service.stopSelf()，则会发生 ANR，并显示以下错误消息：“<fgs_type> 的前台服务未在超时时间内停止：<component_name>”。

注意：Service.onTimeout(int, int) 不适用于 Android 14 或更低版本。在搭载这些版本的设备上，如果媒体处理服务达到超时期限，系统会立即缓存应用。因此，您的应用不应等待收到超时通知。相反，它应在适当情况下尽快终止前台服务或将其更改为后台服务。

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 a startForeground()

FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION

Pré-requisitos de 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, que precisa conceder a permissão antes que você possa 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.

Observação: os apps destinados ao Android 15 ou versões mais recentes não podem iniciar um serviço em primeiro plano de projeção de mídia em um broadcast receiver BOOT_COMPLETED. Para mais informações, consulte Restrições para receptores de transmissão BOOT_COMPLETED que iniciam serviços em primeiro plano.

Alternativas

Para fazer streaming de mídia para 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 前台服务，也无法从 BOOT_COMPLETED 接收器启动 microphone 前台服务，但有少数例外情况。如需了解详情，请参阅与启动需要“使用时”权限的前台服务相关的限制。

说明

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

Ligação telefônica

Tipo de serviço em primeiro plano a ser declarado no manifesto em

android:foregroundServiceType

phoneCall

Permissão a ser declarada no manifesto

FOREGROUND_SERVICE_PHONE_CALL

Constante para transmitir a startForeground()

FOREGROUND_SERVICE_TYPE_PHONE_CALL

Pré-requisitos de ambiente 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 é o discador padrão pela função ROLE_DIALER.

Observação: os apps destinados ao Android 15 ou versões mais recentes não podem iniciar um serviço em primeiro plano de ligação telefônica em um broadcast receiver BOOT_COMPLETED. Para mais informações, consulte Restrições para receptores de transmissão BOOT_COMPLETED que iniciam serviços em primeiro plano.

Descrição

Continue uma chamada usando as APIs ConnectionService.

Alternativas

Se você precisar fazer ligações, videochamadas ou chamadas VoIP, use a biblioteca android.telecom.

Considere usar o CallScreeningService para filtrar ligações.

Mensagens remotas

要在清单中的以下位置声明的前台服务类型

android:foregroundServiceType

remoteMessaging

在清单中声明的权限

FOREGROUND_SERVICE_REMOTE_MESSAGING

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING

运行时前提条件

无

说明

将短信从一台设备转移到另一台设备。在用户切换设备时，帮助确保用户消息任务的连续性。

Serviço curto

Tipo de serviço em primeiro plano a ser declarado no manifesto em

android:foregroundServiceType

shortService

Permissão a ser declarada no manifesto

Nenhum

Constante para transmitir para startForeground()

FOREGROUND_SERVICE_TYPE_SHORT_SERVICE

Pré-requisitos do ambiente 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ó pode 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 tipo para shortService a qualquer momento. Nesse ponto, o período de 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 precisa aderir aos pré-requisitos dos outros tipos declarados. Para mais informações, consulte a documentação de serviços em primeiro plano.

Uso especial

要在清单中声明的前台服务类型

android:foregroundServiceType

specialUse

在清单中声明的权限

FOREGROUND_SERVICE_SPECIAL_USE

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_SPECIAL_USE

运行时前提条件

无

说明

涵盖其他前台服务类型未涵盖的所有有效前台服务用例。

除了声明 FOREGROUND_SERVICE_TYPE_SPECIAL_USE 前台服务类型之外，开发者还应在清单中声明用例。为此，他们会在 <service> 元素内指定 <property> 元素。这些值和相应的应用场景 。用途 您提供的案例均为自由形式，因此，您应确保提供足够的 相关信息，让审核人员了解您为何需要使用 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:

• 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 ou USE_EXACT_ALARM

• Apps de VPN (configurados em 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.