為了協助開發人員更明確地定義面向使用者的前景服務,Android 10 在 <service>
元素中導入了 android:foregroundServiceType
屬性。
如果您的應用程式指定 Android 14 為目標,則必須指定適當的前景服務類型。與先前的 Android 版本相同,開發人員可以將多種類型合併使用。這份清單列出可供選擇的前景服務類型:
camera
connectedDevice
dataSync
health
location
mediaPlayback
mediaProjection
microphone
phoneCall
remoteMessaging
shortService
specialUse
systemExempted
如果應用程式的用途與上述任一類型無關,強烈建議您遷移邏輯,以便使用 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
前景服務,但有少數例外情況。詳情請參閱「啟動需要使用中權限的前景服務的限制」。- 說明
繼續在背景存取相機,例如:支援多工處理的視訊通訊應用程式。
已連結的裝置
- Foreground service type to declare in manifest under
android:foregroundServiceType
connectedDevice
- 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.
同步處理資料
- Foreground service type to declare in manifest under
android:foregroundServiceType
dataSync
- Permission to declare in your manifest
FOREGROUND_SERVICE_DATA_SYNC
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_DATA_SYNC
- Runtime prerequisites
- None
- Description
Data transfer operations, such as the following:
- Data upload or download
- Backup-and-restore operations
- Import or export operations
- Fetch data
- Local file processing
- Transfer data between a device and the cloud over a network
- Alternatives
See Alternatives to data sync foreground services for detailed information.
健康度
- 要在資訊清單中宣告的前景服務類型
android:foregroundServiceType
health
- 在資訊清單中宣告的權限
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
前景服務。詳情請參閱「啟動需要使用中權限的前景服務的限制」。- 說明
在健身類別中,任何用於支援應用程式的長時間執行用途,例如:運動追蹤器。
位置
- Foreground service type to declare in manifest under
android:foregroundServiceType
location
- Permission to declare in your manifest
FOREGROUND_SERVICE_LOCATION
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_LOCATION
- Runtime prerequisites
The user must have enabled location services and the app must be granted at least one of the following runtime permissions:
Note: In order to check that the user has enabled location services as well as granted access to the runtime permissions, use
PermissionChecker#checkSelfPermission()
Note: The location runtime permissions are subject to while-in-use restrictions. For this reason, you cannot create a
location
foreground service while your app is in the background, unless you've been granted theACCESS_BACKGROUND_LOCATION
runtime permission. For more information, see Restrictions on starting foreground services that need while-in-use permissions.- Description
Long-running use cases that require location access, such as navigation and location sharing.
- Alternatives
If your app needs to be triggered when the user reaches specific locations, consider using the geofence API instead.
媒體
- 要在下列資訊清單中宣告的前景服務類型
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
- 執行階段必要條件
至少必須符合下列其中一項條件:
- 應用程式已在資訊清單檔案中宣告
MANAGE_OWN_CALLS
權限。
- 應用程式已在資訊清單檔案中宣告
- 應用程式是透過
ROLE_DIALER
角色成為預設撥號應用程式。
- 應用程式是透過
- 說明
使用
ConnectionService
API 繼續目前的通話。- 替代選項
如果您需要撥打電話、視訊或 VoIP 通話,請考慮使用
android.telecom
程式庫。建議您使用
CallScreeningService
來過濾來電。
遠端通訊
- 要在下列資訊清單中宣告的前景服務類型
android:foregroundServiceType
remoteMessaging
- 在資訊清單中宣告的權限
FOREGROUND_SERVICE_REMOTE_MESSAGING
- 要傳遞至
startForeground()
的常數 FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
- 執行階段必要條件
- 無
- 說明
- 在裝置之間轉移簡訊。協助使用者在切換裝置時,繼續編輯訊息。
短程服務
- Foreground service type to declare in manifest under
android:foregroundServiceType
shortService
- 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_SERVICE
permission. - A
shortService
can 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
shortService
at 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
shortService
is 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_SERVICE
parameter 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
shortService
type and another foreground service type, the system ignores theshortService
type 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:foregroundServiceType
specialUse
- 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_USE
foreground 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 thespecialUse
type.<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:foregroundServiceType
systemExempted
- 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_EMERGENCY
role - Device Admin apps
- Apps holding
SCHEDULE_EXACT_ALARM
orUSE_EXACT_ALARM
permission 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 管理中心聲明前景服務類型,請參閱「瞭解前景服務和全螢幕意圖規定」。