前景服務類型

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

相機

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

camera

在資訊清單中宣告的權限

FOREGROUND_SERVICE_CAMERA

要傳遞至 startForeground() 的常數

FOREGROUND_SERVICE_TYPE_CAMERA

執行階段必要條件

要求並獲得 CAMERA 執行階段權限

說明

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

已連結的裝置

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

android:foregroundServiceType

connectedDevice

在資訊清單中宣告的權限

FOREGROUND_SERVICE_CONNECTED_DEVICE

要傳遞至 startForeground() 的常數

FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE

執行階段必要條件

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

• 在資訊清單中至少宣告以下其中一項權限：

  • CHANGE_NETWORK_STATE
  • CHANGE_WIFI_STATE
  • CHANGE_WIFI_MULTICAST_STATE
  • NFC
  • TRANSMIT_IR

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

  • BLUETOOTH_CONNECT
  • BLUETOOTH_ADVERTISE
  • BLUETOOTH_SCAN
  • UWB_RANGING

• 呼叫 UsbManager.requestPermission()。

說明

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

替代方案

如果您的應用程式需要持續將資料轉移至外部裝置，請考慮改用隨附裝置管理員。使用隨附裝置狀態 API，協助應用程式在配對裝置位於有效範圍內時保持執行。

如果您的應用程式需要掃描藍牙裝置，請考慮改用藍牙掃描 API。

同步處理資料

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

android:foregroundServiceType

dataSync

在資訊清單中宣告的權限

FOREGROUND_SERVICE_DATA_SYNC

要傳遞至 startForeground() 的常數

FOREGROUND_SERVICE_TYPE_DATA_SYNC

執行階段必要條件

無

說明

資料移轉作業，例如：

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

替代選項

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

健康度

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

android:foregroundServiceType

health

在資訊清單中宣告的權限

FOREGROUND_SERVICE_HEALTH

要傳遞至 startForeground() 的常數

FOREGROUND_SERVICE_TYPE_HEALTH

執行階段必要條件

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

• 在資訊清單中宣告 HIGH_SAMPLING_RATE_SENSORS 權限。

• 至少要求下列其中一項執行階段權限，並獲得授予：

  • BODY_SENSORS
  • ACTIVITY_RECOGNITION

說明

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

位置

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

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) 功能。

替代選項

如果您要顯示子母畫面影片，請使用子母畫面模式。

處理中的媒體項目

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

android:foregroundServiceType

mediaProcessing

在資訊清單中宣告的權限

FOREGROUND_SERVICE_MEDIA_PROCESSING

要傳遞至 startForeground() 的常數

FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING

執行階段必要條件

無

說明

用於執行媒體資產耗時作業的服務，例如將媒體轉換成不同格式。系統允許這項服務有一定的執行時間。在正常情況下，此時間限制為每 24 小時 6 小時。(這項限制由應用程式的所有 mediaProcessing 前景服務共用)。

在下列情況下，應用程式應手動停止媒體處理服務：

• 轉碼作業完成或達到失敗狀態時，讓服務呼叫 Service.stopForeground() 和 Service.stopSelf() 完全停止服務。

如果達到逾時期限，系統會呼叫服務的 Service.onTimeout(int, int) 方法。目前，服務有幾秒鐘可以呼叫 Service.stopSelf()。如果服務未呼叫 Service.stopSelf()，將發生 ANR 情形，並顯示以下錯誤訊息：「<fgs_type> 的前景服務並未在逾時期間停止：<component_name>」。

注意：Service.onTimeout(int, int) 不適用於 Android 14 以下版本。在搭載這些版本的裝置上，如果媒體處理服務達到逾時期限，系統就會立即快取應用程式。因此，應用程式不應等到收到逾時通知。而是應盡快終止前景服務或將其變更為背景服務。

媒體投影

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

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

執行階段必要條件

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

• 應用程式已在資訊清單檔案中宣告 MANAGE_OWN_CALLS 權限。

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

特殊用途

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

android:foregroundServiceType

specialUse

在資訊清單中宣告的權限

FOREGROUND_SERVICE_SPECIAL_USE

要傳遞至 startForeground() 的常數

FOREGROUND_SERVICE_TYPE_SPECIAL_USE

執行階段必要條件

無

說明

包含其他未涵蓋的有效前景服務用途 前景服務類型

除了宣告 FOREGROUND_SERVICE_TYPE_SPECIAL_USE 之外， 前景服務類型，則開發人員應在 資訊清單。方法是指定 <property> <service> 元素。這些值和對應的用途 在 Google Play 管理中心提交應用程式時進行審查使用 這類案例採用形式不拘，請務必提供充分的資訊 相關資訊，以便審查人員瞭解您必須使用 specialUse 的原因 類型。

<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

執行階段必要條件

無

說明

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

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

• 裝置處於展示模式狀態
• 應用程式為裝置擁有者
• 應用程式為分析器擁有者
• 具有 ROLE_EMERGENCY 角色的安全應用程式
• 裝置管理員應用程式
• 具有 SCHEDULE_EXACT_ALARM 或 USE_EXACT_ALARM 權限的應用程式

• VPN 應用程式 (透過「設定」>「網路和網際網路」>「VPN」進行設定)

  否則，若宣告此類型將會導致系統擲回 ForegroundServiceTypeNotAllowedException。

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

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