前台服务类型

从 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 中声明前台服务类型的更多信息，请参阅了解前台服务和全屏意图要求。