为了帮助开发者更有目的地定义面向用户的前台服务,Android 10 在 <service>
元素内引入了 android:foregroundServiceType
属性。
如果您的应用以 Android 14 为目标平台,则必须指定适当的前台服务类型。与以前的 Android 版本一样,可组合使用多个类型。下面列出了可供选择的前台服务类型:
camera
connectedDevice
dataSync
health
location
mediaPlayback
mediaProjection
microphone
phoneCall
remoteMessaging
shortService
specialUse
systemExempted
如果应用中的用例与这些类型均不相关,强烈建议您迁移逻辑以使用 WorkManager 或用户发起的数据传输作业。
Android 14 中新增了 health, remoteMessaging, shortService, specialUse
和 systemExempted
类型。
以下代码段提供了一个清单中的前台服务类型声明示例:
<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>
如果以 Android 14 为目标平台的应用未在清单中定义给定服务的类型,系统会在调用 startForeground()
时引发 MissingForegroundServiceTypeException
。
声明新权限来使用前台服务类型
如果以 Android 14 为目标平台的应用使用前台服务,则必须根据前台服务类型声明 Android 14 中引入的特定权限。这些权限显示在本页每种前台服务类型的预期用例和强制执行部分中标记为“您必须在清单文件中声明的权限”的部分。
所有这些权限都定义为一般权限,并默认授予。用户无法撤消这些权限。
在运行时包含前台服务类型
对于启动前台服务的应用,最佳做法是使用
startForeground()
的 ServiceCompat
版本(在 androidx-core 中提供)
1.12 及更高版本)。
前台服务类型的整数。您可以选择传递一个或多个类型值。
通常,您应仅声明特定用例所需的类型。这样可以更轻松地满足系统对每种前台服务类型的预期。如果某项前台服务以多种类型启动, 那么前台服务必须遵守平台强制执行要求 要求 所有类型。
ServiceCompat.startForeground(0, notification, FOREGROUND_SERVICE_TYPE_LOCATION)
如果调用中未指定前台服务类型,则默认为类型
与清单中定义的值相关联如果您未指定服务
类型,系统就会抛出
MissingForegroundServiceTypeException
。
如果前台服务在启动后需要新的权限,您应再次调用 startForeground()
并添加新的服务类型。对于
例如,假设某个健身应用运行了一项跑步跟踪器服务,而该服务始终需要
location
信息,但不一定需要 media
权限。您
需要在清单中同时声明 location
和 mediaPlayback
。如果
用户开始跑步并只想跟踪其位置,您的应用应调用
startForeground()
并仅传递 location
服务类型。然后,如果用户
想要开始播放音频,请再次调用 startForeground()
并传递
location|mediaPlayback
。
系统运行时检查
系统会检查前台服务类型的使用是否恰当,并确认应用是否已请求适当的运行时权限或使用所需的 API。例如,系统希望使用前台服务类型 FOREGROUND_SERVICE_TYPE_LOCATION
的应用请求 ACCESS_COARSE_LOCATION
或 ACCESS_FINE_LOCATION
。
这意味着,在向用户请求权限和启动前台服务时,应用必须遵循非常具体的操作顺序。应用在尝试调用 startForeground()
之前,必须先请求并获得所需的权限。在启动前台服务后请求相应权限的应用必须更改此顺序,并在启动前台服务之前请求该权限。
本页面的每种前台服务类型的预期用例和强制执行部分中标记为“运行时要求”的部分列出了平台强制执行的具体内容。
每种前台服务类型的预期用例和强制执行
为了使用给定的前台服务类型,您必须在清单文件中声明特定权限,必须满足特定的运行时要求,并且应用必须满足该类型的其中一组预期用例。下面几部分介绍了您必须声明的权限、运行时前提条件以及每种类型的预期用例。
相机
- 要在清单中的
android:foregroundServiceType
下声明的前台服务类型 camera
- 在清单中声明的权限
FOREGROUND_SERVICE_CAMERA
- 要传递给
startForeground()
的常量 FOREGROUND_SERVICE_TYPE_CAMERA
- 运行时前提条件
请求并获得
CAMERA
运行时权限注意:
CAMERA
运行时权限受使用时限制。因此,当您的应用位于后台时,您无法创建camera
前台服务,但存在一些例外情况。如需了解详情,请参阅有关启动需要运行时权限的前台服务的限制。- 说明
继续在后台访问摄像头,例如支持多任务的视频聊天应用。
连接的设备
- 要在其清单中声明的前台服务类型
android:foregroundServiceType
connectedDevice
- 在清单中声明的权限
FOREGROUND_SERVICE_CONNECTED_DEVICE
- 要传递给
startForeground()
的常量 FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
- 运行时前提条件
必须至少满足以下其中一个条件:
在清单中至少声明以下其中一项权限:
请求并获得以下至少一项运行时权限:
- 说明
与需要蓝牙、NFC、IR、USB 或网络连接的外部设备进行互动。
- 替代方案
如果您的应用需要持续将数据传输到外部设备,请考虑改用配套设备管理器。使用配套设备在线状态 API 帮助您的应用在配套设备在范围内时保持运行。
如果您的应用需要扫描蓝牙设备,请考虑改用 Bluetooth Scanner API。
数据同步
- 要在其清单中声明的前台服务类型
android:foregroundServiceType
dataSync
- 在清单中声明的权限
FOREGROUND_SERVICE_DATA_SYNC
- 要传递给
startForeground()
的常量 FOREGROUND_SERVICE_TYPE_DATA_SYNC
- 运行时前提条件
- 无
- 说明
数据传输操作,例如:
- 数据上传或下载
- 备份和恢复操作
- 导入或导出操作
- 获取数据
- 本地文件处理
- 通过网络在设备和云端之间传输数据
- 替代方案
如需了解详情,请参阅数据同步前台服务的替代方案。
健康
- 要在其清单中声明的前台服务类型
android:foregroundServiceType
health
- 在清单中声明的权限
FOREGROUND_SERVICE_HEALTH
- 要传递给
startForeground()
的常量 FOREGROUND_SERVICE_TYPE_HEALTH
- 运行时前提条件
必须至少满足以下其中一个条件:
在清单中声明
HIGH_SAMPLING_RATE_SENSORS
权限。请求并获得以下至少一项运行时权限:
注意:
BODY_SENSORS
运行时权限受使用时限制。因此,您无法创建在应用在后台运行时使用身体传感器的health
前台服务,但存在一些例外情况。如需了解详情,请参阅有关启动需要运行时权限的前台服务的限制。- 说明
为健身类别的应用(例如锻炼追踪器)提供支持的所有长时间运行的用例。
位置
- 要在清单中声明的前台服务类型
android:foregroundServiceType
location
- 在清单中声明的权限
FOREGROUND_SERVICE_LOCATION
- 要传递给
startForeground()
的常量 FOREGROUND_SERVICE_TYPE_LOCATION
- 运行时前提条件
用户必须已启用位置信息服务,并且必须至少向应用授予以下运行时权限之一:
注意:如需检查用户是否已启用位置信息服务以及是否已授予运行时权限的访问权限,请使用
PermissionChecker#checkSelfPermission()
注意:位置信息运行时权限受使用时限制的约束。因此,当应用在后台运行时,您无法创建
location
前台服务,除非您已被授予ACCESS_BACKGROUND_LOCATION
运行时权限。如需了解详情,请参阅对启动需要在使用时授予权限的前台服务的限制。- 说明
需要位置信息使用权的长时间运行的用例,例如导航和位置信息分享。
- 替代方案
如果您的应用需要在用户到达特定位置时触发,请考虑改用 Geofence API。
媒体
- 要在其清单中声明的前台服务类型
android:foregroundServiceType
mediaPlayback
- 在清单中声明的权限
FOREGROUND_SERVICE_MEDIA_PLAYBACK
- 要传递给
startForeground()
的常量 FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
- 运行时前提条件
- 无
- 说明
- 在后台继续播放音频或视频。在 Android TV 上支持数字视频录制 (DVR) 功能。
- 替代方案
- 如果您显示的是画中画视频,请使用画中画模式。
媒体投影
- 要在其清单中声明的前台服务类型
android:foregroundServiceType
mediaProjection
- 在清单中声明的权限
FOREGROUND_SERVICE_MEDIA_PROJECTION
- 要传递给
startForeground()
的常量 FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
- 运行时前提条件
在启动前台服务之前,调用
createScreenCaptureIntent()
方法。执行此操作会向用户显示权限通知;用户必须授予权限,您才能创建服务。创建前台服务后,您可以调用
MediaProjectionManager.getMediaProjection()
。- 说明
使用
MediaProjection
API 将内容投影到非主要显示屏或外部设备。这些内容不一定是完全媒体内容。- 替代方案
如需将媒体内容流式传输到其他设备,请使用 Google Cast SDK。
麦克风
- 要在其清单中声明的前台服务类型
android:foregroundServiceType
microphone
- 在清单中声明的权限
FOREGROUND_SERVICE_MICROPHONE
- 要传递给
startForeground()
的常量 FOREGROUND_SERVICE_TYPE_MICROPHONE
- 运行时前提条件
请求并获得
RECORD_AUDIO
运行时权限。注意:
RECORD_AUDIO
运行时权限受使用时限制。因此,当您的应用位于后台时,您无法创建microphone
前台服务,但存在一些例外情况。如需了解详情,请参阅有关启动需要运行时权限的前台服务的限制。- 说明
在后台继续捕获麦克风内容,例如录音器或通信应用。
致电
- 要在其清单中声明的前台服务类型
android:foregroundServiceType
phoneCall
- 在清单中声明的权限
FOREGROUND_SERVICE_PHONE_CALL
- 要传递给
startForeground()
的常量 FOREGROUND_SERVICE_TYPE_PHONE_CALL
- 运行时前提条件
必须至少满足以下其中一个条件:
- 应用已在其清单文件中声明
MANAGE_OWN_CALLS
权限。
- 应用已在其清单文件中声明
- 应用通过
ROLE_DIALER
角色成为默认拨号器应用。
- 应用通过
- 说明
使用
ConnectionService
API 继续当前通话。- 替代方案
如果您需要拨打电话、视频或 VoIP 通话,请考虑使用
android.telecom
库。不妨考虑使用
CallScreeningService
过滤来电。
远程消息传递
- 要在其清单中声明的前台服务类型
android:foregroundServiceType
remoteMessaging
- 在清单中声明的权限
FOREGROUND_SERVICE_REMOTE_MESSAGING
- 要传递给
startForeground()
的常量 FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
- 运行时前提条件
- 无
- 说明
- 将短信从一台设备转移到另一台设备。在用户切换设备时,帮助确保用户消息任务的连续性。
短期服务
- 要在其清单中声明的前台服务类型
android:foregroundServiceType
shortService
- 在清单中声明的权限
- 无
- 要传递给
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
类型声明。不过,该服务仍必须遵守其他声明类型的前提条件。如需了解详情,请参阅前台服务文档。
特殊用途
- 要在清单中声明的前台服务类型
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>
系统豁免
- 要在清单中声明的前台服务类型
android:foregroundServiceType
systemExempted
- 在清单中声明的权限
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
- 要传递给
startForeground()
的常量 FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
- 运行时前提条件
- 无
- 说明
为系统应用和特定系统集成预留, 继续使用前台服务。
如需使用此类型,应用必须至少满足以下条件之一:
- 设备处于演示模式状态
- 应用是设备所有者
- 应用是性能分析器所有者
- 属于具有
ROLE_EMERGENCY
角色的安全应用 - 属于设备管理应用
- 持有
SCHEDULE_EXACT_ALARM
或USE_EXACT_ALARM
权限,并且正在使用 前台服务用于在后台继续闹钟, 包括仅触感反馈闹钟。 VPN 应用(通过设置 > 网络和互联网 > VPN 配置)
否则,声明此类型会导致系统抛出
ForegroundServiceTypeNotAllowedException
。
使用前台服务类型时强制执行的 Google Play 政策
如果您的应用以 Android 14 或更高版本为目标平台,您需要在 Play 管理中心的应用内容页面(政策 > 应用内容)中声明应用的前台服务类型。如需详细了解如何在 Play 管理中心内声明前台服务类型,请参阅了解前台服务和全屏 intent 要求。