フォアグラウンド サービス タイプは必須

为了帮助开发者更有目的地定义面向用户的前台服务，Android 10 在 <service> 元素内引入了 android:foregroundServiceType 属性。

如果您的应用以 Android 14 为目标平台，则必须指定适当的前台服务类型。与以前的 Android 版本一样，可组合使用多个类型。下面列出了可供选择的前台服务类型：

如果应用中的用例与这些类型均不相关，强烈建议您迁移逻辑以使用 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
ランタイムの前提条件

次の条件の少なくとも 1 つを満たす必要があります。

説明

Bluetooth、NFC、IR、USB、またはネットワーク接続を必要とする外部デバイスとの通信。

代替

アプリが外部デバイスへの継続的なデータ転送を行う必要がある場合は、代わりにコンパニオン デバイス マネージャーを使用することを検討してください。companion device presence API を使用すると、コンパニオン デバイスが範囲内にある間はアプリを実行し続けることができます。

アプリで Bluetooth デバイスをスキャンする必要がある場合は、代わりに Bluetooth scan 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
运行时前提条件

必须至少满足以下其中一个条件：

注意：BODY_SENSORS 和基于传感器的读取运行时权限受“在使用时”限制。因此，除非您已获得 BODY_SENSORS_BACKGROUND（API 级别 33 到 35）或 READ_HEALTH_DATA_IN_BACKGROUND（API 级别 36 及更高级别）权限，否则您无法创建在应用处于后台运行时使用身体传感器的 health 前台服务。如需了解详情，请参阅与启动需要使用时权限的前台服务相关的限制。

说明

为健身类别的应用（例如锻炼追踪器）提供支持的所有长时间运行的用例。

位置情報

マニフェストで宣言するフォアグラウンド サービス タイプ
android:foregroundServiceType
location
マニフェストで宣言する権限
FOREGROUND_SERVICE_LOCATION
startForeground() に渡す定数
FOREGROUND_SERVICE_TYPE_LOCATION
ランタイムの前提条件

ユーザーが位置情報サービスを有効にしており、アプリに次のいずれかの実行時の権限が付与されている必要があります。

注: ユーザーが位置情報サービスを有効にして実行時の権限へのアクセスを許可していることを確認するには、PermissionChecker#checkSelfPermission() を使用します。

注: 位置情報のランタイム権限には、使用中の制限が適用されます。そのため、ACCESS_BACKGROUND_LOCATION ランタイム権限が付与されている場合を除き、アプリがバックグラウンドにあるときに 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
运行时前提条件

必须至少满足以下其中一个条件：

  • 应用是通过 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
运行时前提条件
无
说明

为系统应用和特定系统集成预留，使其能继续使用前台服务。

如需使用此类型，应用必须至少满足以下条件之一：

フォアグラウンド サービス タイプの使用に対する Google Play ポリシーの適用

Android 14 以降をターゲットとするアプリの場合は、Google Play Console の [アプリのコンテンツ] ページ（[ポリシー] > [アプリのコンテンツ]）で、アプリのフォアグラウンド サービスのタイプを申告する必要があります。Google Play Console でフォアグラウンド サービスのタイプを申告する方法について詳しくは、フォアグラウンド サービスと全画面インテントの要件についてをご覧ください。