为了帮助开发者更有目的地定义面向用户的前台服务,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>
元素。在您透過 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 管理中心宣告前景服務類型,請參閱「瞭解前景服務和全螢幕意圖規定」。