为了帮助开发者更有目的地定义面向用户的前台服务,Android 10 在 <service> 元素内引入了 android:foregroundServiceType 属性。
如果您的应用以 Android 14 为目标平台,则必须指定适当的前台服务类型。与以前的 Android 版本一样,可组合使用多个类型。下面列出了可供选择的前台服务类型:
cameraconnectedDevicedataSynchealthlocationmediaPlaybackmediaProjectionmicrophonephoneCallremoteMessagingshortServicespecialUsesystemExempted
如果应用中的用例与这些类型均不相关,强烈建议您迁移逻辑以使用 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:foregroundServiceTypeconnectedDevice- 在清单中声明的权限
FOREGROUND_SERVICE_CONNECTED_DEVICE- 要传递给
startForeground()的常量 FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE- 运行时前提条件
必须至少满足以下其中一个条件:
在清单中至少声明以下其中一项权限:
至少请求并被授予以下其中一项运行时权限:
- 说明
与需要蓝牙、NFC、IR、USB 或网络连接的外部设备进行互动。
- 替代方案
如果您的应用需要向外部设备持续传输数据,请考虑改用配套设备管理器。使用配套设备感知 API,可帮助您的应用在配套设备在范围内时保持运行。
如果您的应用需要扫描蓝牙设备,请考虑改用 Bluetooth Scan API。
同步處理資料
- 要在下列資訊清單中宣告的前景服務類型
android:foregroundServiceTypedataSync- 在資訊清單中宣告的權限
FOREGROUND_SERVICE_DATA_SYNC- 要傳遞至
startForeground()的常數 FOREGROUND_SERVICE_TYPE_DATA_SYNC- 執行階段必要條件
- 無
- 說明
資料移轉作業,例如:
- 上傳或下載資料
- 備份與還原作業
- 匯入或匯出作業
- 擷取資料
- 本機檔案處理
- 透過網路在裝置和雲端之間轉移資料
- 替代選項
詳情請參閱「資料同步前景服務的替代方案」。
健康度
- 要在資訊清單中宣告的前景服務類型
android:foregroundServiceTypehealth- 在資訊清單中宣告的權限
FOREGROUND_SERVICE_HEALTH- 要傳遞至
startForeground()的常數 FOREGROUND_SERVICE_TYPE_HEALTH- 執行階段必要條件
至少必須符合下列其中一項條件:
在資訊清單中宣告
HIGH_SAMPLING_RATE_SENSORS權限。至少要求下列其中一項執行階段權限,並獲得授予:
注意:
BODY_SENSORS和感應器的 READ 執行階段權限會受到使用期間限制。因此,除非您已獲得BODY_SENSORS_BACKGROUND(API 級別 33 至 35) 或READ_HEALTH_DATA_IN_BACKGROUND(API 級別 36 以上) 權限,否則無法在應用程式處於背景執行時,建立使用身體感應器的health前景服務。詳情請參閱「啟動需要使用中權限的前景服務的限制」。- 說明
在健身類別中,任何用於支援應用程式的長時間執行用途,例如:運動追蹤器。
位置
- 要在清单中的以下位置声明的前台服务类型
android:foregroundServiceTypelocation- 在清单中声明的权限
FOREGROUND_SERVICE_LOCATION- 要传递给
startForeground()的常量 FOREGROUND_SERVICE_TYPE_LOCATION- 运行时前提条件
用户必须已启用位置信息服务,并且应用必须至少获得以下一项运行时权限:
注意:如需检查用户是否已启用位置信息服务以及是否已授予对运行时权限的访问权限,请使用
PermissionChecker#checkSelfPermission()注意:位置信息运行时权限受“使用期间”限制。因此,除非您已获得
ACCESS_BACKGROUND_LOCATION运行时权限,否则无法在应用在后台运行时创建location前台服务。如需了解详情,请参阅与启动需要“使用时”权限的前台服务相关的限制。- 说明
需要位置信息使用权的长时间运行的用例,例如导航和位置信息分享。
- 替代方案
如果您的应用需要在用户到达特定位置时触发,请考虑改用 Geofence API。
媒體
- Foreground service type to declare in manifest under
android:foregroundServiceTypemediaPlayback- Permission to declare in your manifest
FOREGROUND_SERVICE_MEDIA_PLAYBACK- Constant to pass to
startForeground() FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK- Runtime prerequisites
- None
- Description
- Continue audio or video playback from the background. Support Digital Video Recording (DVR) functionality on Android TV.
- Alternatives
- If you're showing picture-in-picture video, use Picture-in-Picture mode.
媒體投影
- 要在清单中的以下位置声明的前台服务类型
android:foregroundServiceTypemediaProjection- 在清单中声明的权限
FOREGROUND_SERVICE_MEDIA_PROJECTION- 要传递给
startForeground()的常量 FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION- 运行时前提条件
在启动前台服务之前调用
createScreenCaptureIntent()方法。这样做会向用户显示权限通知;用户必须先授予权限,您才能创建服务。创建前台服务后,您可以调用
MediaProjectionManager.getMediaProjection()。- 说明
使用
MediaProjectionAPI 将内容投影到非主要显示屏或外部设备。这些内容不必全都为媒体内容。- 替代方案
如需将媒体流式传输到其他设备,请使用 Google Cast SDK。
麥克風
- Foreground service type to declare in manifest under
android:foregroundServiceTypemicrophone- Permission to declare in your manifest
FOREGROUND_SERVICE_MICROPHONE- Constant to pass to
startForeground() FOREGROUND_SERVICE_TYPE_MICROPHONE- Runtime prerequisites
Request and be granted the
RECORD_AUDIOruntime permission.Note: The
RECORD_AUDIOruntime permission is subject to while-in-use restrictions. For this reason, you cannot create amicrophoneforeground service while your app is in the background, with a few exceptions. For more information, see Restrictions on starting foreground services that need while-in-use permissions.- Description
Continue microphone capture from the background, such as voice recorders or communication apps.
語音通話
- 要在清单中的以下位置声明的前台服务类型
android:foregroundServiceTypephoneCall- 在清单中声明的权限
FOREGROUND_SERVICE_PHONE_CALL- 要传递给
startForeground()的常量 FOREGROUND_SERVICE_TYPE_PHONE_CALL- 运行时前提条件
必须至少满足以下其中一个条件:
- 应用已在其清单文件中声明
MANAGE_OWN_CALLS权限。
- 应用已在其清单文件中声明
- 应用是通过
ROLE_DIALER角色的默认拨号器应用。
- 应用是通过
- 说明
使用
ConnectionServiceAPI 继续当前通话。- 替代方案
如果您需要拨打电话、视频通话或 VoIP 通话,不妨考虑使用
android.telecom库。考虑使用
CallScreeningService来过滤来电。
遠端通訊
- Foreground service type to declare in manifest under
android:foregroundServiceTyperemoteMessaging- Permission to declare in your manifest
FOREGROUND_SERVICE_REMOTE_MESSAGING- Constant to pass to
startForeground() FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING- Runtime prerequisites
- None
- Description
- Transfer text messages from one device to another. Assists with continuity of a user's messaging tasks when they switch devices.
短程服務
- Foreground service type to declare in manifest under
android:foregroundServiceTypeshortService- Permission to declare in your manifest
- None
- Constant to pass to
startForeground() FOREGROUND_SERVICE_TYPE_SHORT_SERVICE- Runtime prerequisites
- None
- Description
Quickly finish critical work that cannot be interrupted or postponed.
This type has some unique characteristics:
- Can only run for a short period of time (about 3 minutes).
- No support for sticky foreground services.
- Cannot start other foreground services.
- Doesn't require a type-specific permission, though it still
requires the
FOREGROUND_SERVICEpermission. - A
shortServicecan only change to another service type if the app is currently eligible to start a new foreground service. - A foreground service can change its type to
shortServiceat any time, at which point the timeout period begins.
The timeout for shortService begins from the moment that
Service.startForeground()is called. The app is expected to callService.stopSelf()orService.stopForeground()before the timeout occurs. Otherwise, the newService.onTimeout()is called, giving apps a brief opportunity to callstopSelf()orstopForeground()to stop their service.A short time after
Service.onTimeout()is called, the app enters a cached state and is no longer considered to be in the foreground, unless the user is actively interacting with the app. A short time after the app is cached and the service has not stopped, the app receives an ANR. The ANR message mentionsFOREGROUND_SERVICE_TYPE_SHORT_SERVICE. For these reasons, it's considered best practice to implement theService.onTimeout()callback.The
Service.onTimeout()callback doesn't exist on Android 13 and lower. If the same service runs on such devices, it doesn't receive a timeout, nor does it ANR. Make sure that your service stops as soon as it finishes the processing task, even if it hasn't received theService.onTimeout()callback yet.It's important to note that if the timeout of the
shortServiceis not respected, the app will ANR even if it has other valid foreground services or other app lifecycle processes running.If an app is visible to the user or satisfies one of the exemptions that allow foreground services to be started from the background, calling
Service.StartForeground()again with theFOREGROUND_SERVICE_TYPE_SHORT_SERVICEparameter extends the timeout by another 3 minutes. If the app isn't visible to the user and doesn't satisfy one of the exemptions, any attempt to start another foreground service, regardless of type, causes aForegroundServiceStartNotAllowedException.If a user disables battery optimization for your app, it's still affected by the timeout of shortService FGS.
If you start a foreground service that includes the
shortServicetype and another foreground service type, the system ignores theshortServicetype declaration. However, the service must still adhere to the prerequisites of the other declared types. For more information, see the Foreground services documentation.
特殊用途
- Foreground service type to declare in manifest under
android:foregroundServiceTypespecialUse- Permission to declare in your manifest
FOREGROUND_SERVICE_SPECIAL_USE- Constant to pass to
startForeground() FOREGROUND_SERVICE_TYPE_SPECIAL_USE- Runtime prerequisites
- None
- Description
Covers any valid foreground service use cases that aren't covered by the other foreground service types.
In addition to declaring the
FOREGROUND_SERVICE_TYPE_SPECIAL_USEforeground service type, developers should declare use cases in the manifest. To do so, they specify the<property>element within the<service>element. These values and corresponding use cases are reviewed when you submit your app in the Google Play Console. The use cases you provide are free-form, and you should make sure to provide enough information to let the reviewer see why you need to use thespecialUsetype.<service android:name="fooService" android:foregroundServiceType="specialUse"> <property android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE" android:value="explanation_for_special_use"/> </service>
不受規範的系統
- Foreground service type to declare in manifest under
android:foregroundServiceTypesystemExempted- Permission to declare in your manifest
FOREGROUND_SERVICE_SYSTEM_EXEMPTED- Constant to pass to
startForeground() FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED- Runtime prerequisites
- None
- Description
Reserved for system applications and specific system integrations, to continue to use foreground services.
To use this type, an app must meet at least one of the following criteria:
- Device is in demo mode state
- App is a Device Owner
- App is a Profiler Owner
- Safety Apps that have the
ROLE_EMERGENCYrole - Device Admin apps
- Apps holding
SCHEDULE_EXACT_ALARMorUSE_EXACT_ALARMpermission and are using Foreground Service to continue alarms in the background, including haptics-only alarms. VPN apps (configured using Settings > Network & Internet > VPN)
Otherwise, declaring this type causes the system to throw a
ForegroundServiceTypeNotAllowedException.
Google Play 對於使用前景服務類型的政策違規處置
如果應用程式指定 Android 14 以上版本為目標,您就需要在 Play 管理中心的「應用程式內容」頁面 (依序點選「政策」>「應用程式內容」) 中,聲明所使用的任何前景服務類型。如要進一步瞭解如何在 Play 管理中心聲明前景服務類型,請參閱「瞭解前景服務和全螢幕意圖規定」。