前景服務類型

自 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
執行階段必要條件

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

說明

與需要藍牙、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
執行階段必要條件

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

說明

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

位置

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

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

說明

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

替代選項

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

媒體

要在下方資訊清單中宣告的前景服務類型
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.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
執行階段必要條件

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

  • 應用程式是透過 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
執行階段必要條件
無
說明

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

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

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

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