為了協助開發人員更明確地定義面向使用者的前景服務,Android 10 在 <service> 元素中導入了 android:foregroundServiceType 屬性。
如果您的應用程式指定 Android 14 為目標,則必須指定適當的前景服務類型。與先前的 Android 版本相同,開發人員可以將多種類型合併使用。這份清單列出可供選擇的前景服務類型:
cameraconnectedDevicedataSynchealthlocationmediaPlaybackmediaProjectionmicrophonephoneCallremoteMessagingshortServicespecialUsesystemExempted
如果應用程式的用途與上述任一類型無關,強烈建議您遷移邏輯,以便使用 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:foregroundServiceTypeconnectedDevice- 在資訊清單中宣告的權限
FOREGROUND_SERVICE_CONNECTED_DEVICE- 要傳遞至
startForeground()的常數 FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE- 執行階段必要條件
至少必須符合下列其中一項條件:
在資訊清單中至少宣告下列其中一項權限:
至少要求下列其中一項執行階段權限,並獲得授予:
- 說明
與需要藍牙、NFC、IR、USB 或網路連線的外部裝置互動。
- 替代選項
如果您的應用程式需要持續將資料傳輸至外部裝置,建議改用隨附裝置管理工具。使用隨附裝置狀態 API,讓應用程式在隨附裝置在範圍內時持續執行。
如果應用程式需要掃描藍牙裝置,建議改用 Bluetooth 掃描 API。
同步處理資料
- 要在下列資訊清單中宣告的前景服務類型
android:foregroundServiceTypedataSync- 在資訊清單中宣告的權限
FOREGROUND_SERVICE_DATA_SYNC- 要傳遞至
startForeground()的常數 FOREGROUND_SERVICE_TYPE_DATA_SYNC- 執行階段必要條件
- 無
- 說明
資料移轉作業,例如:
- 上傳或下載資料
- 備份與還原作業
- 匯入或匯出作業
- 擷取資料
- 本機檔案處理
- 透過網路在裝置和雲端之間轉移資料
- 替代選項
詳情請參閱「資料同步前景服務的替代方案」。
健康度
- 要在資訊清單中宣告的前景服務類型
android:foregroundServiceTypehealth- 在資訊清單中宣告的權限
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前景服務。詳情請參閱「啟動需要使用中權限的前景服務的限制」。- 說明
在健身類別中,任何用於支援應用程式的長時間執行用途,例如:運動追蹤器。
位置
- 要在下列資訊清單中宣告的前景服務類型
android:foregroundServiceTypelocation- 在資訊清單中宣告的權限
FOREGROUND_SERVICE_LOCATION- 要傳遞至
startForeground()的常數 FOREGROUND_SERVICE_TYPE_LOCATION- 執行階段必要條件
使用者必須已啟用定位服務,且應用程式必須獲得下列至少一項執行階段權限:
注意:如要確認使用者已啟用位置服務,並授予執行階段權限存取權,請使用
PermissionChecker#checkSelfPermission()注意:位置資訊執行階段權限適用於使用期間的限制。因此,除非您已獲得
ACCESS_BACKGROUND_LOCATION執行階段權限,否則無法在應用程式處於背景執行時建立location前景服務。詳情請參閱「啟動需要使用中權限的前景服務的限制」。- 說明
需要位置資訊存取權的長時間執行使用案例,如:導航和位置分享。
- 替代選項
如果應用程式需要在使用者抵達特定地點時觸發,建議改用 地理圍欄 API。
媒體
- 要在下列資訊清單中宣告的前景服務類型
android:foregroundServiceTypemediaPlayback- 在資訊清單中宣告的權限
FOREGROUND_SERVICE_MEDIA_PLAYBACK- 要傳遞至
startForeground()的常數 FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK- 執行階段必要條件
- 無
- 說明
- 在背景中繼續播放音訊或視訊。支援 Android TV 的數位錄影 (DVR) 功能。
- 替代選項
- 如果要顯示子母畫面影片,請使用子母畫面模式。
媒體投影
- 要在清单中的以下位置声明的前台服务类型
android:foregroundServiceTypemediaProjection- 在清单中声明的权限
FOREGROUND_SERVICE_MEDIA_PROJECTION- 要传递给
startForeground()的常量 FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION- 运行时前提条件
在启动前台服务之前调用
createScreenCaptureIntent()方法。这样做会向用户显示权限通知;用户必须先授予权限,您才能创建服务。创建前台服务后,您可以调用
MediaProjectionManager.getMediaProjection()。- 说明
使用
MediaProjectionAPI 将内容投影到非主要显示屏或外部设备。这些内容不必全都为媒体内容。- 替代方案
如需将媒体流式传输到其他设备,请使用 Google Cast SDK。
麥克風
- 要在資訊清單中宣告的前景服務類型
android:foregroundServiceTypemicrophone- 在資訊清單中宣告的權限
FOREGROUND_SERVICE_MICROPHONE- 要傳遞至
startForeground()的常數 FOREGROUND_SERVICE_TYPE_MICROPHONE- 執行階段必要條件
要求並取得
RECORD_AUDIO執行階段權限。注意:
RECORD_AUDIO執行階段權限會受到使用期間限制。因此,您無法在應用程式處於背景執行時建立microphone前景服務,但有少數例外情況。詳情請參閱「啟動需要使用中權限的前景服務的限制」。- 說明
繼續從背景擷取麥克風,例如錄音工具或通訊應用程式。
語音通話
- 要在清单中的以下位置声明的前台服务类型
android:foregroundServiceTypephoneCall- 在清单中声明的权限
FOREGROUND_SERVICE_PHONE_CALL- 要传递给
startForeground()的常量 FOREGROUND_SERVICE_TYPE_PHONE_CALL- 运行时前提条件
必须至少满足以下其中一个条件:
- 应用已在其清单文件中声明
MANAGE_OWN_CALLS权限。
- 应用已在其清单文件中声明
- 应用是通过
ROLE_DIALER角色的默认拨号器应用。
- 应用是通过
- 说明
使用
ConnectionServiceAPI 继续当前通话。- 替代方案
如果您需要拨打电话、视频通话或 VoIP 通话,不妨考虑使用
android.telecom库。考虑使用
CallScreeningService来过滤来电。
遠端通訊
- 要在下列資訊清單中宣告的前景服務類型
android:foregroundServiceTyperemoteMessaging- 在資訊清單中宣告的權限
FOREGROUND_SERVICE_REMOTE_MESSAGING- 要傳遞至
startForeground()的常數 FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING- 執行階段必要條件
- 無
- 說明
- 在裝置之間轉移簡訊。協助使用者在切換裝置時,繼續編輯訊息。
短程服務
- 要在清单中的以下位置声明的前台服务类型
android:foregroundServiceTypeshortService- 在清单中声明的权限
- 无
- 要传递给
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()回调被视为一种最佳实践。Android 13 及更低版本中不存在
Service.onTimeout()回调。如果同一服务在此类设备上运行,则不会出现超时,也不会发生 ANR。确保您的服务在完成处理任务后立即停止,即使它尚未收到Service.onTimeout()回调也是如此。请务必注意,如果未遵循
shortService的超时设置,即使应用还有其他有效的前台服务或其他应用生命周期进程,应用也会遇到 ANR。如果应用对用户可见,或满足允许从后台启动前台服务的某一豁免条件,则使用
FOREGROUND_SERVICE_TYPE_SHORT_SERVICE参数再次调用Service.StartForeground()会将超时时间再延长 3 分钟。如果应用对用户不可见且不满足其中一个豁免条件,则尝试启动其他前台服务(无论其类型如何)都会导致ForegroundServiceStartNotAllowedException。即使用户为您的应用停用电池优化功能,仍然会受到 shortService FGS 的影响。
如果您启动包含
shortService类型和另一个前台服务类型的前台服务,系统会忽略shortService类型声明。不过,该服务仍必须遵守其他声明类型的先决条件。如需了解详情,请参阅前台服务文档。
特殊用途
- 要在資訊清單中宣告的前景服務類型
android:foregroundServiceTypespecialUse- 在資訊清單中宣告的權限
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:foregroundServiceTypesystemExempted- 在資訊清單中宣告的權限
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 管理中心聲明前景服務類型,請參閱「瞭解前景服務和全螢幕意圖規定」。