必須提供前景服務類型

為了協助開發人員更明確地定義面向使用者的前景服務，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。

宣告使用前景服務類型的新權限

If apps that target Android 14 use a foreground service, they must declare a specific permission, based on the foreground service type, that Android 14 introduces. These permissions appear in the sections labeled "permission that you must declare in your manifest file" in the intended use cases and enforcement for each foreground service type section on this page.

All of the permissions are defined as normal permissions and are granted by default. Users cannot revoke these permissions.

Caution: If you call startForeground() without declaring the appropriate foreground service type permission, the system throws a SecurityException.

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

The best practice for applications starting foreground services is to use the ServiceCompat version of startForeground() (available in androidx-core 1.12 and higher) where you pass in a bitwise integer of foreground service types. You can choose to pass one or more type values.

Usually, you should declare only the types required for a particular use case. This makes it easier to meet the system's expectations for each foreground service type. In cases where a foreground service is started with multiple types, then the foreground service must adhere to the platform enforcement requirements of all types.

ServiceCompat.startForeground(0, notification, FOREGROUND_SERVICE_TYPE_LOCATION)

If the foreground service type is not specified in the call, the type defaults to the values defined in the manifest. If you didn't specify the service type in the manifest, the system throws MissingForegroundServiceTypeException.

If the foreground service needs new permissions after you launch it, you should call startForeground() again and add the new service types. For example, suppose a fitness app runs a running-tracker service that always needs location information, but might or might not need media permissions. You would need to declare both location and mediaPlayback in the manifest. If a user starts a run and just wants their location tracked, your app should call startForeground() and pass just the location service type. Then, if the user wants to start playing audio, call startForeground() again and pass 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.

Caution: If your app doesn't fulfill all of the runtime requirements for starting a foreground service, the system throws a SecurityException after you call startForeground() for that service. This prevents the foreground service from starting, might cause a running foreground service to be removed from the foreground process state, and might cause your app to crash.

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.

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

In order to use a given foreground service type, you must declare a particular permission in your manifest file, you must fulfill specific runtime requirements, and your app must fulfill one of the intended sets of use cases for that type. The following sections explain the permission that you must declare, the runtime prerequisites, and the intended use cases for each type.

相機

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.

已連結的裝置

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:

• Declare at least one of the following permissions in your manifest:

  • CHANGE_NETWORK_STATE
  • CHANGE_WIFI_STATE
  • CHANGE_WIFI_MULTICAST_STATE
  • NFC
  • TRANSMIT_IR

• Request and be granted at least one of the following runtime permissions:

  • BLUETOOTH_CONNECT
  • BLUETOOTH_ADVERTISE
  • BLUETOOTH_SCAN
  • UWB_RANGING

• Call UsbManager.requestPermission()

Description

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

Note: If your app performs a projection or remote messaging operation, use the corresponding media projection or remote messaging type instead.

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

執行階段必要條件

無

說明

資料移轉作業，例如：

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

替代選項

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

健康度

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:

• Declare the HIGH_SAMPLING_RATE_SENSORS permission in your manifest.

• Request and be granted at least one of the following runtime permissions:

  • BODY_SENSORS on API level 35 and lower
  • READ_HEART_RATE
  • READ_SKIN_TEMPERATURE
  • READ_OXYGEN_SATURATION
  • ACTIVITY_RECOGNITION

Note: The BODY_SENSORS and sensor-based READ runtime permissions are 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 unless you've been granted the BODY_SENSORS_BACKGROUND (API level 33 to 35) or READ_HEALTH_DATA_IN_BACKGROUND (API level 36 and higher) permissions. 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:

• ACCESS_COARSE_LOCATION
• ACCESS_FINE_LOCATION

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.

媒體

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.

媒體投影

要在下列資訊清單中宣告的前景服務類型

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 前景服務，但有少數例外情況。詳情請參閱「啟動需要使用中權限的前景服務的限制」。

說明

繼續從背景擷取麥克風，例如錄音工具或通訊應用程式。

語音通話

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 has declared the MANAGE_OWN_CALLS permission in its manifest file.

• 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.

遠端通訊

Foreground service type to declare in manifest under

android:foregroundServiceType

remoteMessaging

Permission to declare in your manifest

FOREGROUND_SERVICE_REMOTE_MESSAGING

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING

Runtime prerequisites

None

Description

Transfer text messages from one device to another. Assists with continuity of a user's messaging tasks when they switch devices.

短程服務

要在下列資訊清單中宣告的前景服務類型

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>

不受規範的系統

Foreground service type to declare in manifest under

android:foregroundServiceType

systemExempted

Permission to declare in your manifest

FOREGROUND_SERVICE_SYSTEM_EXEMPTED

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED

Runtime prerequisites

None

Description

Reserved for system applications and specific system integrations, to continue to use foreground services.

To use this type, an app must meet at least one of the following criteria:

• Device is in demo mode state
• App is a Device Owner
• App is a Profiler Owner
• Safety Apps that have the ROLE_EMERGENCY role
• Device Admin apps
• Apps holding SCHEDULE_EXACT_ALARM or USE_EXACT_ALARM permission and are using Foreground Service to continue alarms in the background, including haptics-only alarms.

• VPN apps (configured using Settings > Network & Internet > VPN)

  Otherwise, declaring this type causes the system to throw a ForegroundServiceTypeNotAllowedException.

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

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