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. É necessário 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 da permissão FOREGROUND_SERVICE. 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
- Foreground service type to declare in manifest under
android:foregroundServiceType camera- Permission to declare in your manifest
FOREGROUND_SERVICE_CAMERA- Constant to pass to
startForeground() FOREGROUND_SERVICE_TYPE_CAMERA- Runtime prerequisites
Request and be granted the
CAMERAruntime permission- Description
Continue to access the camera from the background, such as video chat apps that allow for multitasking.
Dispositivo conectado
- Tipo de serviço em primeiro plano a ser declarado no manifesto em
android:foregroundServiceTypeconnectedDevice- 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
- Foreground service type to declare in manifest under
android:foregroundServiceTypedataSync- Permission to declare in your manifest
FOREGROUND_SERVICE_DATA_SYNC- Constant to pass to
startForeground() FOREGROUND_SERVICE_TYPE_DATA_SYNC- Runtime prerequisites
- None
- Description
Data transfer operations, such as the following:
- Data upload or download
- Backup-and-restore operations
- Import or export operations
- Fetch data
- Local file processing
- Transfer data between a device and the cloud over a network
- Alternatives
See Alternatives to data sync foreground services for detailed information.
Saúde
- Foreground service type to declare in manifest under
android:foregroundServiceTypehealth- Permission to declare in your manifest
FOREGROUND_SERVICE_HEALTH- Constant to pass to
startForeground() FOREGROUND_SERVICE_TYPE_HEALTH- Runtime prerequisites
At least one of the following conditions must be true:
Declare the
HIGH_SAMPLING_RATE_SENSORSpermission in your manifest.Request and be granted at least one of the following runtime permissions:
BODY_SENSORSon API 35 and lowerREAD_HEART_RATEREAD_SKIN_TEMPERATUREREAD_OXYGEN_SATURATIONACTIVITY_RECOGNITION
- Description
Any long-running use cases to support apps in the fitness category such as exercise trackers.
Local
- Foreground service type to declare in manifest under
android:foregroundServiceTypelocation- Permission to declare in your manifest
FOREGROUND_SERVICE_LOCATION- Constant to pass to
startForeground() FOREGROUND_SERVICE_TYPE_LOCATION- Runtime prerequisites
The user must have enabled location services and the app must be granted at least one of the following runtime permissions:
- Description
Long-running use cases that require location access, such as navigation and location sharing.
- Alternatives
If your app needs to be triggered when the user reaches specific locations, consider using the geofence API instead.
Mídia
- 在清单中声明的前台服务类型
android:foregroundServiceTypemediaPlayback- 要在清单中声明的权限
FOREGROUND_SERVICE_MEDIA_PLAYBACK- 要传递给
startForeground()的常量 FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK- 运行时前提条件
- 无
- 说明
在后台继续播放音频或视频。在 Android TV 上支持数字视频录制 (DVR) 功能。
- 替代方案
如果您要显示画中画视频,请使用画中画模式。
Mídia em processamento
- 要在清单中的以下位置声明的前台服务类型
android:foregroundServiceTypemediaProcessing- 在清单中声明的权限
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
- Foreground service type to declare in manifest under
android:foregroundServiceTypemediaProjection- Permission to declare in your manifest
FOREGROUND_SERVICE_MEDIA_PROJECTION- Constant to pass to
startForeground() FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION- Runtime prerequisites
Call the
createScreenCaptureIntent()method before starting the foreground service. Doing so shows a permission notification to the user; the user must grant the permission before you can create the service.After you have created the foreground service, you can call
MediaProjectionManager.getMediaProjection().- Description
Project content to non-primary display or external device using the
MediaProjectionAPIs. This content doesn't have to be exclusively media content.- Alternatives
To stream media to another device, use the Google Cast SDK.
Microfone
- 在清单中声明的前台服务类型
android:foregroundServiceTypemicrophone- 要在清单中声明的权限
FOREGROUND_SERVICE_MICROPHONE- 要传递给
startForeground()的常量 FOREGROUND_SERVICE_TYPE_MICROPHONE- 运行时前提条件
请求并获得
RECORD_AUDIO运行时权限。- 说明
在后台继续捕获麦克风内容,例如录音器或通信应用。
Ligação telefônica
- 在清单中声明的前台服务类型
android:foregroundServiceTypephoneCall- 要在清单中声明的权限
FOREGROUND_SERVICE_PHONE_CALL- 要传递给
startForeground()的常量 FOREGROUND_SERVICE_TYPE_PHONE_CALL- 运行时前提条件
必须至少满足以下其中一个条件:
- 应用已在其清单文件中声明
MANAGE_OWN_CALLS权限。
- 应用已在其清单文件中声明
- 应用通过
ROLE_DIALER角色成为默认拨号器应用。
- 应用通过
- 说明
使用
ConnectionServiceAPI 继续当前通话。- 替代方案
如果您需要拨打电话、进行视频通话或 VoIP 通话,请考虑使用
android.telecom库。考虑使用
CallScreeningService过滤来电。
Mensagens remotas
- Foreground service type to declare in manifest under
android:foregroundServiceTyperemoteMessaging- Permission to declare in your manifest
FOREGROUND_SERVICE_REMOTE_MESSAGING- Constant to pass to
startForeground() FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING- Runtime prerequisites
- None
- Description
- Transfer text messages from one device to another. Assists with continuity of a user's messaging tasks when they switch devices.
Serviço curto
- 要在清单中的以下位置声明的前台服务类型
android:foregroundServiceTypeshortService- 在清单中声明的权限
- 无
- 要传递给
startForeground()的常量 FOREGROUND_SERVICE_TYPE_SHORT_SERVICE- 运行时前提条件
- 无
- 说明
快速完成不可中断或推迟的关键工作。
这种类型有一些独特的特征:
- 只能持续运行一小段时间(大约 3 分钟)。
- 不支持粘性前台服务。
- 无法启动其他前台服务。
- 不需要类型专用权限,不过它仍需要
FOREGROUND_SERVICE权限。 - 只有当应用当前符合启动新前台服务的条件时,
shortService才能更改为其他服务类型。 - 前台服务可以随时将其类型更改为
shortService,届时超时期限将开始。
shortService 的超时时间从调用
Service.startForeground()开始算起。应用应在发生超时之前调用Service.stopSelf()或Service.stopForeground()。否则,系统会调用新的Service.onTimeout(),让应用有机会调用stopSelf()或stopForeground()来停止其服务。调用
Service.onTimeout()后的短时间内,应用会进入缓存状态,并且不再被视为处于前台,除非用户正在主动与应用互动。应用缓存一小段时间后,服务还未停止,该应用会收到 ANR 消息。ANR 消息提及FOREGROUND_SERVICE_TYPE_SHORT_SERVICE。出于这些原因,实现Service.onTimeout()回调被视为一种最佳实践。Android 13 及更低版本中不存在
Service.onTimeout()回调。如果同一服务在此类设备上运行,则不会出现超时,也不会发生 ANR。确保您的服务在完成处理任务后立即停止,即使它尚未收到Service.onTimeout()回调也是如此。请务必注意,如果未遵循
shortService的超时设置,即使应用还有其他有效的前台服务或其他应用生命周期进程,应用也会遇到 ANR。如果应用对用户可见,或满足允许从后台启动前台服务的某一豁免条件,则使用
FOREGROUND_SERVICE_TYPE_SHORT_SERVICE参数再次调用Service.StartForeground()会将超时时间再延长 3 分钟。如果应用对用户不可见且不满足其中一个豁免条件,则尝试启动其他前台服务(无论其类型如何)都会导致ForegroundServiceStartNotAllowedException。即使用户为您的应用停用电池优化功能,仍然会受到 shortService FGS 的影响。
如果您启动包含
shortService类型和另一个前台服务类型的前台服务,系统会忽略shortService类型声明。不过,该服务仍必须遵守其他声明类型的先决条件。如需了解详情,请参阅前台服务文档。
Uso especial
- Foreground service type to declare in manifest under
android:foregroundServiceTypespecialUse- Permission to declare in your manifest
FOREGROUND_SERVICE_SPECIAL_USE- Constant to pass to
startForeground() FOREGROUND_SERVICE_TYPE_SPECIAL_USE- Runtime prerequisites
- None
- Description
Covers any valid foreground service use cases that aren't covered by the other foreground service types.
In addition to declaring the
FOREGROUND_SERVICE_TYPE_SPECIAL_USEforeground service type, developers should declare use cases in the manifest. To do so, they specify the<property>element within the<service>element. These values and corresponding use cases are reviewed when you submit your app in the Google Play Console. The use cases you provide are free-form, and you should make sure to provide enough information to let the reviewer see why you need to use thespecialUsetype.<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
- Foreground service type to declare in manifest under
android:foregroundServiceTypesystemExempted- Permission to declare in your manifest
FOREGROUND_SERVICE_SYSTEM_EXEMPTED- Constant to pass to
startForeground() FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED- Runtime prerequisites
- None
- Description
Reserved for system applications and specific system integrations, to continue to use foreground services.
To use this type, an app must meet at least one of the following criteria:
- Device is in demo mode state
- App is a Device Owner
- App is a Profiler Owner
- Safety Apps that have the
ROLE_EMERGENCYrole - Device Admin apps
- Apps holding
SCHEDULE_EXACT_ALARMorUSE_EXACT_ALARMpermission VPN apps (configured using Settings > Network & Internet > VPN)
Otherwise, declaring this type causes the system to throw a
ForegroundServiceTypeNotAllowedException.
Aplicação da política do Google Play para uso de tipos de serviço em primeiro plano
如果您的应用以 Android 14 或更高版本为目标平台,您需要在 Play 管理中心的“应用内容”页面(政策 > 应用内容)中声明应用的前台服务类型。如需详细了解如何在 Play 管理中心内声明前台服务类型,请参阅了解前台服务和全屏 intent 要求。