前景服務類型

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

自 Android 14 (API 級別 34) 起，您必須為每項前景服務聲明適當的服務類型。也就是說，您必須在應用程式資訊清單中宣告服務類型，並為該類型要求適當的前景服務權限 (除了要求 FOREGROUND_SERVICE 權限)。此外，視前景服務類型而定，您可能需要在啟動服務前要求執行階段權限。

相機

要在 android:foregroundServiceType 下於資訊清單中宣告的前景服務類型

camera

在資訊清單中宣告的權限

FOREGROUND_SERVICE_CAMERA

要傳遞至 startForeground() 的常數

FOREGROUND_SERVICE_TYPE_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:

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

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 35 and lower
  • READ_HEART_RATE
  • READ_SKIN_TEMPERATURE
  • READ_OXYGEN_SATURATION
  • ACTIVITY_RECOGNITION

Description

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

位置

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

android:foregroundServiceType

location

在資訊清單中宣告的權限

FOREGROUND_SERVICE_LOCATION

要傳遞至 startForeground() 的常數

FOREGROUND_SERVICE_TYPE_LOCATION

執行階段必要條件

使用者必須已啟用定位服務，且應用程式必須獲得下列至少一項執行階段權限：

• ACCESS_COARSE_LOCATION
• ACCESS_FINE_LOCATION

說明

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

替代選項

如果應用程式需要在使用者抵達特定地點時觸發，建議改用 地理圍欄 API。

媒體

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

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

mediaProcessing

Permission to declare in your manifest

FOREGROUND_SERVICE_MEDIA_PROCESSING

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING

Runtime prerequisites

None

Description

Service for performing time-consuming operations on media assets, like converting media to different formats. The system allows this service a limited time to run; under normal circumstances, this time limit would be 6 hours out of every 24. (This limit is shared by all of an app's mediaProcessing foreground services.)

Your app should manually stop the media processing service in the following scenario:

• When the transcoding operation finishes or reaches a failure state, have the service call Service.stopForeground() and Service.stopSelf() to stop the service completely.

If the timeout period is reached, the system calls the service's Service.onTimeout(int, int) method. At this time, the service has a few seconds to call Service.stopSelf(). If the service does not call Service.stopSelf(), an ANR will occur with this error message: "A foreground service of <fgs_type> did not stop within its timeout: <component_name>".

Note: Service.onTimeout(int, int) is not available on Android 14 or lower. On devices running those versions, if a media processing service reaches the timeout period, the system immediately caches the app. For this reason, your app shouldn't wait to get a timeout notification. Instead, it should terminate the foreground service or change it to a background service as soon as appropriate.

媒體投影

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.

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

遠端通訊

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

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>

不受規範的系統

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

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

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

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

If your app targets Android 14 or higher, you'll need to declare your app's foreground service types in the Play Console's app content page (Policy > App content). For more information on how to declare your foreground service types in Play Console, see Understanding foreground service and full-screen intent requirements.