To help developers be more intentional with defining user-facing foreground
services, Android 10 introduced the android:foregroundServiceType
attribute within the <service> element.
If your app targets Android 14, it must specify appropriate foreground service types. As in previous versions of Android, multiple types can be combined. This list shows the foreground service types to choose from:
cameraconnectedDevicedataSynchealthlocationmediaPlaybackmediaProjectionmicrophonephoneCallremoteMessagingshortServicespecialUsesystemExempted
If a use case in your app isn't associated with any of these types, we strongly recommend that you migrate your logic to use WorkManager or user-initiated data transfer jobs.
The health, remoteMessaging, shortService, specialUse, and systemExempted
types are new in Android 14.
The following code snippet provides an example of a foreground service type declaration in the manifest:
<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>
If an app that targets Android 14 doesn't define types for a given service in
the manifest, then the system will raise MissingForegroundServiceTypeException
upon calling startForeground() for that service.
宣告使用前景服務類型的新權限
If apps that target Android 14 use a foreground service, they must declare a specific permission, based on the foreground service type, that Android 14 introduces. These permissions appear in the sections labeled "permission that you must declare in your manifest file" in the intended use cases and enforcement for each foreground service type section on this page.
All of the permissions are defined as normal permissions and are granted by default. Users cannot revoke these permissions.
在執行階段加入前景服務類型
啟動前景服務應用程式的最佳做法是使用 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。
系統執行階段檢查
The system checks for proper use of foreground service types and confirms that
the app has requested the proper runtime permissions or uses the required APIs.
For instance, the system expects apps that use the foreground service type
FOREGROUND_SERVICE_TYPE_LOCATION type to request either
ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION.
This implies that apps must follow a very specific
order of operations when requesting permissions from the user and starting
foreground services. Permissions must be requested and granted before the
app attempts to call startForeground(). Apps that request the appropriate
permissions after the foreground service has been started must change this order
of operations and request the permission before starting the foreground service.
The specifics of platform enforcement appear in the sections labeled "runtime requirements" in the intended use cases and enforcement for each foreground service type section on this page.
各種前景服務類型的預期用途與違規處置
为了使用给定的前台服务类型,您必须在清单文件中声明特定权限,必须满足特定的运行时要求,并且应用必须满足该类型的其中一组预期用例。以下部分介绍了您必须声明的权限、运行时前提条件以及每种类型的预期用例。
相機
- Foreground service type to declare in manifest under
android:foregroundServiceType camera- Permission to declare in your manifest
FOREGROUND_SERVICE_CAMERA- Constant to pass to
startForeground() FOREGROUND_SERVICE_TYPE_CAMERA- Runtime prerequisites
Request and be granted the
CAMERAruntime permissionNote: The
CAMERAruntime permission is subject to while-in-use restrictions. For this reason, you cannot create acameraforeground 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 to access the camera from the background, such as video chat apps that allow for multitasking.
已連結的裝置
- Foreground service type to declare in manifest under
android:foregroundServiceTypeconnectedDevice- Permission to declare in your manifest
FOREGROUND_SERVICE_CONNECTED_DEVICE- Constant to pass to
startForeground() FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE- Runtime prerequisites
At least one of the following conditions must be true:
Declare at least one of the following permissions in your manifest:
Request and be granted at least one of the following runtime permissions:
- Description
Interactions with external devices that require a Bluetooth, NFC, IR, USB, or network connection.
- Alternatives
If your app needs to do continuous data transfer to an external device, consider using the companion device manager instead. Use the companion device presence API to help your app stay running while the companion device is in range.
If your app needs to scan for bluetooth devices, consider using the Bluetooth scan API instead.
同步處理資料
- 要在下列資訊清單中宣告的前景服務類型
android:foregroundServiceTypedataSync- 在資訊清單中宣告的權限
FOREGROUND_SERVICE_DATA_SYNC- 要傳遞至
startForeground()的常數 FOREGROUND_SERVICE_TYPE_DATA_SYNC- 執行階段必要條件
- 無
- 說明
資料移轉作業,例如:
- 上傳或下載資料
- 備份與還原作業
- 匯入或匯出作業
- 擷取資料
- 本機檔案處理
- 透過網路在裝置和雲端之間轉移資料
- 替代選項
詳情請參閱「資料同步前景服務的替代方案」。
健康度
- Foreground service type to declare in manifest under
android:foregroundServiceTypehealth- Permission to declare in your manifest
FOREGROUND_SERVICE_HEALTH- Constant to pass to
startForeground() FOREGROUND_SERVICE_TYPE_HEALTH- Runtime prerequisites
At least one of the following conditions must be true:
Declare the
HIGH_SAMPLING_RATE_SENSORSpermission in your manifest.Request and be granted at least one of the following runtime permissions:
BODY_SENSORSon API level 35 and lowerREAD_HEART_RATEREAD_SKIN_TEMPERATUREREAD_OXYGEN_SATURATIONACTIVITY_RECOGNITION
Note: The
BODY_SENSORSand sensor-based READ runtime permissions are subject to while-in-use restrictions. For this reason, you cannot create ahealthforeground service that uses body sensors while your app is in the background unless you've been granted theBODY_SENSORS_BACKGROUND(API level 33 to 35) orREAD_HEALTH_DATA_IN_BACKGROUND(API level 36 and higher) permissions. For more information, see Restrictions on starting foreground services that need while-in-use permissions.- Description
Any long-running use cases to support apps in the fitness category such as exercise trackers.
位置
- 要在清单中的以下位置声明的前台服务类型
android:foregroundServiceTypelocation- 在清单中声明的权限
FOREGROUND_SERVICE_LOCATION- 要传递给
startForeground()的常量 FOREGROUND_SERVICE_TYPE_LOCATION- 运行时前提条件
用户必须已启用位置信息服务,并且应用必须至少获得以下一项运行时权限:
注意:如需检查用户是否已启用位置信息服务以及是否已授予对运行时权限的访问权限,请使用
PermissionChecker#checkSelfPermission()注意:位置信息运行时权限受“使用期间”限制。因此,除非您已获得
ACCESS_BACKGROUND_LOCATION运行时权限,否则无法在应用在后台运行时创建location前台服务。如需了解详情,请参阅与启动需要“使用时”权限的前台服务相关的限制。- 说明
需要位置信息使用权的长时间运行的用例,例如导航和位置信息分享。
- 替代方案
如果您的应用需要在用户到达特定位置时触发,请考虑改用 Geofence API。
媒體
- 要在清单中的以下位置声明的前台服务类型
android:foregroundServiceTypemediaPlayback- 在清单中声明的权限
FOREGROUND_SERVICE_MEDIA_PLAYBACK- 要传递给
startForeground()的常量 FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK- 运行时前提条件
- 无
- 说明
- 在后台继续播放音频或视频。在 Android TV 上支持数字视频录制 (DVR) 功能。
- 替代方案
- 如果您要显示画中画视频,请使用画中画模式。
媒體投影
- Foreground service type to declare in manifest under
android:foregroundServiceTypemediaProjection- Permission to declare in your manifest
FOREGROUND_SERVICE_MEDIA_PROJECTION- Constant to pass to
startForeground() FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION- Runtime prerequisites
Call the
createScreenCaptureIntent()method before starting the foreground service. Doing so shows a permission notification to the user; the user must grant the permission before you can create the service.After you have created the foreground service, you can call
MediaProjectionManager.getMediaProjection().- Description
Project content to non-primary display or external device using the
MediaProjectionAPIs. This content doesn't have to be exclusively media content.- Alternatives
To stream media to another device, use the 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>
不受規範的系統
- 要在下列資訊清單中宣告的前景服務類型
android:foregroundServiceTypesystemExempted- 在資訊清單中宣告的權限
FOREGROUND_SERVICE_SYSTEM_EXEMPTED- 要傳遞至
startForeground()的常數 FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED- 執行階段必要條件
- 無
- 說明
系統應用程式和特定系統整合的預留項目,以便其繼續使用前景服務。
如要使用此類型,應用程式必須至少符合下列其中一項條件:
- 裝置處於展示模式狀態
- 應用程式為裝置擁有者
- 應用程式為分析器擁有者
- 具有
ROLE_EMERGENCY角色的安全應用程式 - 裝置管理員應用程式
- 擁有
SCHEDULE_EXACT_ALARM或USE_EXACT_ALARM權限,並使用前景服務在背景繼續鬧鐘 (包括僅震動鬧鐘)。 VPN 應用程式 (使用「設定」>「網路和網際網路」>「VPN」進行設定)
否則,宣告此類型會導致系統擲回
ForegroundServiceTypeNotAllowedException。
Google Play 對於使用前景服務類型的政策違規處置
如果應用程式指定 Android 14 以上版本為目標,您就需要在 Play 管理中心的「應用程式內容」頁面 (依序點選「政策」>「應用程式內容」) 中,聲明所使用的任何前景服務類型。如要進一步瞭解如何在 Play 管理中心聲明前景服務類型,請參閱「瞭解前景服務和全螢幕意圖規定」。