為了協助開發人員更明確地定義面向使用者的前景服務,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
前景服務,但有以下限制。詳情請參閱「啟動需要使用期間權限的前景服務限制」。- 說明
繼續在背景存取相機,例如:支援多工處理的視訊通訊應用程式。
連結的裝置
- 要在資訊清單中宣告的前景服務類型
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
之外, 前景服務類型,則開發人員應在 資訊清單。方法是指定<property>
<service>
元素。這些值和對應的用途 在 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 管理中心宣告前景服務類型,請參閱「瞭解前景服務和全螢幕意圖規定」。