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:
camera
connectedDevice
dataSync
health
location
mediaPlayback
mediaProjection
microphone
phoneCall
remoteMessaging
shortService
specialUse
systemExempted
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.
宣告使用前景服務類型的新權限
如果以 Android 14 为目标平台的应用使用前台服务,则必须根据前台服务类型声明 Android 14 中引入的特定权限。这些权限显示在本页每种前台服务类型的预期用例和强制执行部分中标记为“您必须在清单文件中声明的权限”的部分。
所有这些权限都定义为一般权限,并默认授予。用户无法撤消这些权限。
在執行階段加入前景服務類型
对于启动前台服务的应用,最佳实践是使用 ServiceCompat
版本的 startForeground()
(适用于 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.
各種前景服務類型的預期用途與違規處置
您必須在資訊清單檔案中宣告特定權限,並滿足特定執行階段要求,而且應用程式必須滿足該類型預期用途的其中一項,才能使用特定的前景服務類型。以下各節說明您必須宣告的權限、執行階段必要條件,以及各個類型的預期用途。
相機
- 要在
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
- 執行階段必要條件
至少必須符合下列其中一項條件:
在資訊清單中至少宣告以下其中一項權限:
要求並至少獲得下列其中一項執行階段權限:
- 說明
與需要藍牙、NFC、IR、USB 或網路連線的外部裝置互動。
- 替代方案
如果您的應用程式需要持續將資料轉移至外部裝置,請考慮改用隨附裝置管理員。使用隨附裝置狀態 API,協助應用程式在配對裝置位於有效範圍內時保持執行。
如果您的應用程式需要掃描藍牙裝置,請考慮改用藍牙掃描 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
- 运行时前提条件
必须至少满足以下其中一个条件:
在清单中声明
HIGH_SAMPLING_RATE_SENSORS
权限。请求并获得以下至少一项运行时权限:
注意:
BODY_SENSORS
运行时权限受使用时限制。因此,您无法创建在应用在后台运行时使用身体传感器的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
- 執行階段必要條件
至少必須符合下列其中一項條件:
- 應用程式已在資訊清單檔案中宣告
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()
回呼是最佳做法。Service.onTimeout()
回呼不存在於 Android 13 及更早版本中。如果在此類裝置上執行相同的服務,則不會收到逾時或收到 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 管理中心提交應用程式時,系統會審查這些值和對應的用途。您提供的用途可以任意形式,請務必提供充分的資訊,讓審查人員瞭解您需要使用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
- 執行階段必要條件
- 無
- 說明
系統應用程式和特定系統整合的預留項目,以便其繼續使用前景服務。
如要使用此類型,應用程式必須至少符合以下其中一項條件:
- 裝置處於展示模式狀態
- 應用程式為裝置擁有者
- 應用程式為分析器擁有者
- 具有
ROLE_EMERGENCY
角色的安全應用程式 - 裝置管理員應用程式
- 具有
SCHEDULE_EXACT_ALARM
或USE_EXACT_ALARM
權限的應用程式 VPN 應用程式 (透過「設定」>「網路和網際網路」>「VPN」進行設定)
否則,若宣告此類型將會導致系統擲回
ForegroundServiceTypeNotAllowedException
。
Google Play 對於使用前景服務類型的政策違規處置
如果您的應用程式指定 Android 14 以上版本為目標,您必須在 Play 管理中心的應用程式內容頁面 (依序點選「政策」>「應用程式內容」) 聲明應用程式的前景服務類型。如要進一步瞭解如何在 Play 管理中心宣告前景服務類型,請參閱「瞭解前景服務和全螢幕意圖規定」。