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

为了帮助开发者更有目的地定义面向用户的前台服务，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 で導入されたフォアグラウンド サービス タイプに基づいて、特定の権限を宣言する必要があります。これらの権限は、このページの対象ユースケースとフォアグラウンド サービス タイプごとの適用セクションの「マニフェスト ファイルで宣言する必要がある権限」に記載されています。

すべての権限は標準の権限として定義され、デフォルトで付与されます。ユーザーはこれらの権限を取り消すことはできません。

実行時にフォアグラウンド サービス タイプを含める

フォアグラウンド サービスを開始するアプリでは、ServiceCompat バージョンの startForeground()（androidx-core 1.12 以降で利用可能）を使用して、フォアグラウンド サービス タイプをビット単位の整数で渡すことをおすすめします。1 つまたは複数のタイプの値を渡すことができます。

通常、特定のユースケースで必要なタイプのみを宣言する必要があります。これにより、各フォアグラウンド サービス タイプに対するシステムの要件を簡単に満たすことができます。フォアグラウンド サービスが複数のタイプで開始される場合、フォアグラウンド サービスは、すべてのタイプのプラットフォーム適用要件に従う必要があります。

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
ランタイムの前提条件

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

注: BODY_SENSORS とセンサーベースの READ ランタイム権限には、使用中の制限が適用されます。そのため、アプリがバックグラウンドにあるときにボディセンサーを使用する health フォアグラウンド サービスを作成するには、BODY_SENSORS_BACKGROUND（API レベル 33 ～ 35）または READ_HEALTH_DATA_IN_BACKGROUND（API レベル 36 以上）の権限が付与されている必要があります。詳細については、使用中の権限が必要なフォアグラウンド サービスの開始に関する制限をご覧ください。

説明

フィットネス カテゴリのアプリ（エクササイズ トラッカーなど）をサポートする、長時間にわたるユースケース。

位置情報

マニフェストで宣言するフォアグラウンド サービス タイプ
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
ランタイムの前提条件

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

  • アプリがマニフェスト ファイルで 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> 要素を指定します。これらの値とそれに対応するユースケースは 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
ランタイムの前提条件
なし
説明

フォアグラウンド サービスを引き続き使用するために、システムアプリと特定のシステム統合用に予約されています。

このタイプを使用するには、アプリが次の条件の少なくとも 1 つを満たしている必要があります。

  • デバイスがデモモードの状態にある
  • アプリがデバイス所有者である
  • アプリがプロファイラ所有者である
  • ROLE_EMERGENCY のロールを持つ緊急情報アプリである
  • デバイス管理アプリである
  • SCHEDULE_EXACT_ALARM 権限または USE_EXACT_ALARM 権限を保持し、フォアグラウンド サービスを使用してハプティクスのみのアラームなど、バックグラウンドでアラームを継続するアプリ。

  • VPN アプリ（[設定] > [ネットワークとインターネット] > [VPN] を使用して構成）

    そうしないと、このタイプを宣言したときに ForegroundServiceTypeNotAllowedException がスローされます。

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

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