前景服務類型

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

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.

同步處理資料

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

Data transfer operations, such as the following:

  • Data upload or download
  • Backup-and-restore operations
  • Import or export operations
  • Fetch data
  • Local file processing
  • Transfer data between a device and the cloud over a network
Alternatives

See Alternatives to data sync foreground services for detailed information.

健康度

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

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

說明

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

位置

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

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

說明

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

替代選項

如果應用程式需要在使用者抵達特定地點時觸發，建議改用 地理圍欄 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
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:

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.

媒體投影

在資訊清單中宣告的前景服務類型
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 執行階段權限。

說明

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

語音通話

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