為了協助開發人員更明確地定義面向使用者的前景服務,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
前台服务类型之外,开发者还应在清单中声明用例。为此,他们会在<service>
元素内指定<property>
元素。这些值和相应的应用场景 。用途 您提供的案例均为自由形式,因此,您应确保提供足够的 提供相关信息,让审核者了解您为何需要使用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 管理中心宣告前景服務類型,請參閱「瞭解前景服務和全螢幕意圖規定」。