前台服务类型

从 Android 14（API 级别 34）开始，您必须为每个前台服务声明相应的服务类型。这意味着您必须在应用清单中声明服务类型，并为该类型请求相应的前台服务权限（除了请求 FOREGROUND_SERVICE 权限）。此外，根据前台服务类型，您可能需要在启动服务之前请求运行时权限。

摄像头

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

请求并获得 CAMERA 运行时权限

说明

继续从后台访问摄像头，例如允许多任务处理的视频聊天应用。

已连接设备

在清单中声明的前台服务类型，位于
android:foregroundServiceType
connectedDevice
在清单中声明的权限
FOREGROUND_SERVICE_CONNECTED_DEVICE
传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
运行时先决条件

以下至少一个条件必须为真

说明

与需要蓝牙、NFC、红外、USB 或网络连接的外部设备进行交互。

替代方案

如果您的应用需要向外部设备进行持续数据传输，请考虑使用配套设备管理器。使用配套设备在场 API 帮助您的应用在配套设备处于范围内时保持运行。

如果您的应用需要扫描蓝牙设备，请考虑使用蓝牙扫描 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
运行时先决条件

以下至少一个条件必须为真

说明

支持健身类别应用（例如运动追踪器）的任何长时间运行的用例。

位置

在清单中声明的前台服务类型，位于
android:foregroundServiceType
location
在清单中声明的权限
FOREGROUND_SERVICE_LOCATION
传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_LOCATION
运行时先决条件

用户必须已启用位置服务，并且应用必须获得以下至少一项运行时权限

说明

需要位置访问的长时间运行用例，例如导航和位置共享。

替代方案

如果您的应用需要在用户到达特定位置时触发，请考虑改用地理围栏 API。

媒体

在清单中声明的前台服务类型，位于
android:foregroundServiceType
mediaPlayback
在清单中声明的权限
FOREGROUND_SERVICE_MEDIA_PLAYBACK
传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
运行时先决条件
无
说明

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

替代方案

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

媒体处理

在清单中声明的前台服务类型，位于
android:foregroundServiceType
mediaProcessing
在清单中声明的权限
FOREGROUND_SERVICE_MEDIA_PROCESSING
传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING
运行时先决条件
无
说明

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

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

如果达到超时期限，系统会调用服务的 Service.onTimeout(int, int) 方法。此时，服务有几秒钟的时间调用 Service.stopSelf()。如果服务未调用 Service.stopSelf()，则会发生 ANR，并显示此错误消息：“A foreground service of <fgs_type> did not stop within its timeout: <component_name>”。

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

媒体投影

在清单中声明的前台服务类型，位于
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 运行时权限。

说明

继续从后台捕获麦克风，例如录音机或通信应用。

电话

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

以下至少一个条件必须为真

  • 应用通过 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() 回调被认为是最佳实践。

Service.onTimeout() 回调在 Android 13 及更低版本上不存在。如果同一服务在此类设备上运行，它不会收到超时，也不会出现 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> 元素。这些值和相应的用例会在您在 Google Play 管理中心提交应用时进行审核。您提供的用例是自由形式的，您应确保提供足够的信息，让审核人员了解您为何需要使用 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
运行时先决条件
无
说明

预留给系统应用和特定系统集成，以便继续使用前台服务。

要使用此类型，应用必须满足以下至少一项条件

Google Play 关于使用前台服务类型的政策执行

如果您的应用目标版本为 Android 14 或更高版本，您需要在 Play 管理中心的“应用内容”页面（政策 > 应用内容）中声明应用的前台服务类型。有关如何在 Play 管理中心声明前台服务类型的更多信息，请参阅了解前台服务和全屏意图要求。