前台服务类型

从 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，并显示以下错误消息：“<fgs_type> 的前台服务未在其超时期限内停止：<component_name>”。

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

媒体投影

在清单中声明的前台服务类型
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() 回调。

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> 元素。当您在 Google Play Console 中提交应用程序时，将审核这些值和相应的用例。您提供的用例是自由格式的，您应确保提供足够的信息，让审核人员了解您为何需要使用 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 Console 的应用程序内容页面（**策略 > 应用程序内容**）中声明应用程序的前台服务类型。有关如何在 Play Console 中声明前台服务类型的更多信息，请参阅 了解前台服务和全屏意图要求。