必須提供前景服務類型

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:

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 的特定權限。本頁「預期用途和強制執行各種前景服務類型」一節中的「您必須在資訊清單檔案中宣告的權限」提供此類權限的說明。

所有權限都會定義為一般權限,系統也將依預設授予這些權限。使用者無法撤銷這些權限。

在執行階段加入前景服務類型

如要啟動前景服務的應用程式,最佳做法是使用 startForeground()ServiceCompat 版本 (適用於 androidx-core 1.12 以上版本),您需要傳入前景服務類型的位元整數。您可以選擇傳送一或多個類型值。

一般而言,您只需要宣告特定用途所需的類型。如此可更容易達成系統對每種前景服務類型的預期。如果前景服務透過多種類型啟動,則前景服務必須符合「所有」類型的平台強制執行規定

ServiceCompat.startForeground(0, notification, FOREGROUND_SERVICE_TYPE_LOCATION)

如未在呼叫中指定前景服務類型,則類型會預設為資訊清單中定義的值。如果您沒有在資訊清單中指定服務類型,系統會擲回 MissingForegroundServiceTypeException

如果前景服務在啟動後需要新權限,您應再次呼叫 startForeground() 並新增新的服務類型。舉例來說,假設健身應用程式執行的跑步追蹤服務一律需要 location 資訊,但不一定需要 media 權限。您需要在資訊清單中宣告 locationmediaPlayback。如果使用者開始跑步,且只想追蹤他們的位置資訊,應用程式應該呼叫 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 前景服務,但有以下限制。詳情請參閱「啟動需要使用期間權限的前景服務限制」。

說明

繼續在背景存取相機,例如:支援多工處理的視訊通訊應用程式。

連結的裝置

Foreground service type to declare in manifest under
android:foregroundServiceType
connectedDevice
Permission to declare in your manifest
FOREGROUND_SERVICE_CONNECTED_DEVICE
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
Runtime prerequisites

At least one of the following conditions must be true:

Description

Interactions with external devices that require a Bluetooth, NFC, IR, USB, or network connection.

Alternatives

If your app needs to do continuous data transfer to an external device, consider using the companion device manager instead. Use the companion device presence API to help your app stay running while the companion device is in range.

If your app needs to scan for bluetooth devices, consider using the Bluetooth scan API instead.

同步處理資料

要在資訊清單中宣告的前景服務類型
android:foregroundServiceType
dataSync
在資訊清單中宣告的權限
FOREGROUND_SERVICE_DATA_SYNC
要傳遞至 startForeground() 的常數
FOREGROUND_SERVICE_TYPE_DATA_SYNC
執行階段必要條件
說明

資料移轉作業,例如:

  • 上傳或下載資料
  • 備份與還原作業
  • 匯入或匯出作業
  • 擷取資料
  • 本機檔案處理
  • 透過網路在裝置和雲端之間轉移資料
替代方案

詳情請參閱「資料同步處理前景服務的替代方案」。

健康度

要在資訊清單中宣告的前景服務類型
android:foregroundServiceType
health
在資訊清單中宣告的權限
FOREGROUND_SERVICE_HEALTH
要傳遞至 startForeground() 的常數
FOREGROUND_SERVICE_TYPE_HEALTH
執行階段必要條件

至少必須符合下列其中一項條件:

注意:BODY_SENSORS 執行階段權限必須遵守使用期間的限制。因此,建立 health 前景服務時,無法在應用程式於背景執行時使用人體感應器,但只有少數例外。詳情請參閱「啟動需要使用期間權限的前景服務限制」。

說明

在健身類別中,任何用於支援應用程式的長時間執行用途,例如:運動追蹤器。

位置

要在資訊清單中宣告的前景服務類型
android:foregroundServiceType
location
在資訊清單中宣告的權限
FOREGROUND_SERVICE_LOCATION
要傳遞至 startForeground() 的常數
FOREGROUND_SERVICE_TYPE_LOCATION
執行階段必要條件

要求並至少獲得下列其中一項執行階段權限:

注意:位置執行階段權限必須遵守使用期間的限制。因此,當應用程式在背景執行時,無法建立 location 前景服務,但有以下限制。詳情請參閱「啟動需要使用期間權限的前景服務限制」。

說明

需要位置資訊存取權的長時間執行使用案例,如:導航和位置分享。

替代方案

如果您的應用程式必須在使用者抵達特定位置時觸發,請考慮改用 geofence API

媒體

Foreground service type to declare in manifest under
android:foregroundServiceType
mediaPlayback
Permission to declare in your manifest
FOREGROUND_SERVICE_MEDIA_PLAYBACK
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
Runtime prerequisites
None
Description
Continue audio or video playback from the background. Support Digital Video Recording (DVR) functionality on Android TV.
Alternatives
If you're showing picture-in-picture video, use Picture-in-Picture mode.

媒體投影

Foreground service type to declare in manifest under
android:foregroundServiceType
mediaProjection
Permission to declare in your manifest
FOREGROUND_SERVICE_MEDIA_PROJECTION
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
Runtime prerequisites

Call the createScreenCaptureIntent() method before starting the foreground service. Doing so shows a permission notification to the user; the user must grant the permission before you can create the service.

After you have created the foreground service, you can call MediaProjectionManager.getMediaProjection().

Description

Project content to non-primary display or external device using the MediaProjection APIs. This content doesn't have to be exclusively media content.

Alternatives

To stream media to another device, use the 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
執行階段必要條件

至少必須符合下列其中一項條件:

  • 應用程式透過 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 類型宣告。即便如此,服務仍必須遵守其他宣告類型的必要條件。詳情請參閱前景服務說明文件

特殊用途

Foreground service type to declare in manifest under
android:foregroundServiceType
specialUse
Permission to declare in your manifest
FOREGROUND_SERVICE_SPECIAL_USE
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
Runtime prerequisites
None
Description

Covers any valid foreground service use cases that aren't covered by the other foreground service types.

In addition to declaring the FOREGROUND_SERVICE_TYPE_SPECIAL_USE foreground service type, developers should declare use cases in the manifest. To do so, they specify the <property> element within the <service> element. These values and corresponding use cases are reviewed when you submit your app in the Google Play Console. The use cases you provide are free-form, and you should make sure to provide enough information to let the reviewer see why you need to use the specialUse type.

<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
執行階段必要條件
說明

系統應用程式和特定系統整合的預留項目,以便其繼續使用前景服務。

如要使用此類型,應用程式必須至少符合以下其中一項條件:

Google Play 對於使用前景服務類型的政策違規處置

如果您的應用程式指定 Android 14 以上版本為目標,您必須在 Play 管理中心的應用程式內容頁面 (依序點選「政策」>「應用程式內容」) 聲明應用程式的前景服務類型。如要進一步瞭解如何在 Play 管理中心宣告前景服務類型,請參閱「瞭解前景服務和全螢幕意圖規定」。