必須提供前景服務類型

為了協助開發人員更明確地定義面向使用者的前景服務，Android 10 在 <service> 元素中導入了 android:foregroundServiceType 屬性。

如果您的應用程式指定 Android 14 為目標，則必須指定適當的前景服務類型。與先前的 Android 版本相同，開發人員可以將多種類型合併使用。這份清單列出可供選擇的前景服務類型：

如果應用程式的用途與上述任一類型無關，強烈建議您遷移邏輯，以便使用 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。

系統執行階段檢查

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.

各種前景服務類型的預期用途與違規處置

您必須在資訊清單檔案中宣告特定權限，並滿足特定執行階段要求，而且應用程式必須滿足該類型預期用途的其中一項，才能使用特定的前景服務類型。以下各節說明您必須宣告的權限、執行階段先決條件，以及各個類型的預期用途。

相機

Foreground service type to declare in manifest under android:foregroundServiceType
camera
Permission to declare in your manifest
FOREGROUND_SERVICE_CAMERA
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_CAMERA
Runtime prerequisites

Request and be granted the CAMERA runtime permission

Note: The CAMERA runtime permission is subject to while-in-use restrictions. For this reason, you cannot create a camera foreground service while your app is in the background, with a few exceptions. For more information, see Restrictions on starting foreground services that need while-in-use permissions.

Description

Continue to access the camera from the background, such as video chat apps that allow for multitasking.

連結的裝置

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

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

說明

與需要藍牙、NFC、IR、USB 或網路連線的外部裝置互動。

替代選項

如果您的應用程式需要持續將資料傳輸至外部裝置，建議改用隨附裝置管理工具。使用隨附裝置狀態 API，讓應用程式在隨附裝置在範圍內時持續執行。

如果應用程式需要掃描藍牙裝置，建議改用 Bluetooth 掃描 API。

同步處理資料

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

資料移轉作業，例如：

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

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

健康度

Foreground service type to declare in manifest under
android:foregroundServiceType
health
Permission to declare in your manifest
FOREGROUND_SERVICE_HEALTH
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_HEALTH
Runtime prerequisites

At least one of the following conditions must be true:

Note: The BODY_SENSORS runtime permission is subject to while-in-use restrictions. For this reason, you cannot create a health foreground service that uses body sensors while your app is in the background, with a few exceptions. For more information, see Restrictions on starting foreground services that need while-in-use permissions.

Description

Any long-running use cases to support apps in the fitness category such as exercise trackers.

位置

Foreground service type to declare in manifest under
android:foregroundServiceType
location
Permission to declare in your manifest
FOREGROUND_SERVICE_LOCATION
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_LOCATION
Runtime prerequisites

The user must have enabled location services and the app must be granted at least one of the following runtime permissions:

Note: In order to check that the user has enabled location services as well as granted access to the runtime permissions, use PermissionChecker#checkSelfPermission()

Note: The location runtime permissions are subject to while-in-use restrictions. For this reason, you cannot create a location foreground service while your app is in the background, unless you've been granted the ACCESS_BACKGROUND_LOCATION runtime permission. For more information, see Restrictions on starting foreground services that need while-in-use permissions.

Description

Long-running use cases that require location access, such as navigation and location sharing.

Alternatives

If your app needs to be triggered when the user reaches specific locations, consider using the geofence API instead.

媒體

要在下列資訊清單中宣告的前景服務類型
android:foregroundServiceType
mediaPlayback
在資訊清單中宣告的權限
FOREGROUND_SERVICE_MEDIA_PLAYBACK
要傳遞至 startForeground() 的常數
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
執行階段必要條件
無
說明
在背景中繼續播放音訊或視訊。支援 Android TV 的數位錄影 (DVR) 功能。
替代選項
如果要顯示子母畫面影片，請使用子母畫面模式。

媒體投影

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.

麥克風

Foreground service type to declare in manifest under
android:foregroundServiceType
microphone
Permission to declare in your manifest
FOREGROUND_SERVICE_MICROPHONE
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_MICROPHONE
Runtime prerequisites

Request and be granted the RECORD_AUDIO runtime permission.

Note: The RECORD_AUDIO runtime permission is subject to while-in-use restrictions. For this reason, you cannot create a microphone foreground service while your app is in the background, with a few exceptions. For more information, see Restrictions on starting foreground services that need while-in-use permissions.

Description

Continue microphone capture from the background, such as voice recorders or communication apps.

語音通話

Foreground service type to declare in manifest under
android:foregroundServiceType
phoneCall
Permission to declare in your manifest
FOREGROUND_SERVICE_PHONE_CALL
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_PHONE_CALL
Runtime prerequisites

At least one of these conditions must be true:

  • App is the default dialer app through the ROLE_DIALER role.
Description

Continue an ongoing call using the ConnectionService APIs.

Alternatives

If you need to make phone, video, or VoIP calls, consider using the android.telecom library.

Consider using CallScreeningService to screen calls.

遠端通訊

要在下列資訊清單中宣告的前景服務類型
android:foregroundServiceType
remoteMessaging
在資訊清單中宣告的權限
FOREGROUND_SERVICE_REMOTE_MESSAGING
要傳遞至 startForeground() 的常數
FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
執行階段必要條件
無
說明
在裝置之間轉移簡訊。協助使用者在切換裝置時，繼續編輯訊息。

短程服務

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

Quickly finish critical work that cannot be interrupted or postponed.

This type has some unique characteristics:

  • Can only run for a short period of time (about 3 minutes).
  • No support for sticky foreground services.
  • Cannot start other foreground services.
  • Doesn't require a type-specific permission, though it still requires the FOREGROUND_SERVICE permission.
  • A shortService can only change to another service type if the app is currently eligible to start a new foreground service.
  • A foreground service can change its type to shortService at any time, at which point the timeout period begins.

The timeout for shortService begins from the moment that Service.startForeground() is called. The app is expected to call Service.stopSelf() or Service.stopForeground() before the timeout occurs. Otherwise, the new Service.onTimeout() is called, giving apps a brief opportunity to call stopSelf() or stopForeground() to stop their service.

A short time after Service.onTimeout() is called, the app enters a cached state and is no longer considered to be in the foreground, unless the user is actively interacting with the app. A short time after the app is cached and the service has not stopped, the app receives an ANR. The ANR message mentions FOREGROUND_SERVICE_TYPE_SHORT_SERVICE. For these reasons, it's considered best practice to implement the Service.onTimeout() callback.

The Service.onTimeout() callback doesn't exist on Android 13 and lower. If the same service runs on such devices, it doesn't receive a timeout, nor does it ANR. Make sure that your service stops as soon as it finishes the processing task, even if it hasn't received the Service.onTimeout() callback yet.

It's important to note that if the timeout of the shortService is not respected, the app will ANR even if it has other valid foreground services or other app lifecycle processes running.

If an app is visible to the user or satisfies one of the exemptions that allow foreground services to be started from the background, calling Service.StartForeground() again with the FOREGROUND_SERVICE_TYPE_SHORT_SERVICE parameter extends the timeout by another 3 minutes. If the app isn't visible to the user and doesn't satisfy one of the exemptions, any attempt to start another foreground service, regardless of type, causes a ForegroundServiceStartNotAllowedException.

If a user disables battery optimization for your app, it's still affected by the timeout of shortService FGS.

If you start a foreground service that includes the shortService type and another foreground service type, the system ignores the shortService type declaration. However, the service must still adhere to the prerequisites of the other declared types. For more information, see the Foreground services documentation.

特殊用途

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 管理中心聲明前景服務類型，請參閱「瞭解前景服務和全螢幕意圖規定」。