必須提供前景服務類型

為開發人員定義面向使用者的前景，讓他們更有意識 服務，Android 10 導入了 android:foregroundServiceType <service> 元素中的屬性。

如果您的應用程式指定 Android 14 為目標，則必須指定適當的前景服務 。與先前的 Android 版本相同，開發人員可以將多種類型合併使用。這份清單列出可供選擇的前景服務類型：

如果您的應用程式用途與上述任一類型無關，強烈建議您 建議您遷移邏輯，改用 WorkManager； User-Initiated Data Transfer Jobs。

《health, remoteMessaging, shortService, specialUse》和《systemExempted》 類型是 Android 14 的新功能

以下程式碼片段提供資訊清單中的前景服務類型宣告範例：

<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 的應用程式並未在 那麼系統就會引發 MissingForegroundServiceTypeException 針對該服務呼叫 startForeground()

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

如果以 Android 14 為目標版本的應用程式使用前景服務，則必須依據前景服務類型宣告 Android 14 的特定權限。本頁「預期用途和強制執行各種前景服務類型」一節中的「您必須在資訊清單檔案中宣告的權限」提供此類權限的說明。

所有權限都會定義為一般權限，系統也將依預設授予這些權限。使用者無法撤銷這些權限。

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

啟動前景服務的應用程式最佳做法是使用 startForeground() 的 ServiceCompat 版本 (適用於 androidx-core 1.12 以上版本)。 前景服務類型的整數值。您可以選擇傳送一或多個類型 輕鬆分配獎金

一般而言，您只需要宣告特定用途所需的類型。 如此更容易達成系統對每個前景的期望 服務類型。 如果前景服務啟動多種類型， 那麼前景服務必須遵守平台強制執行政策 相關規定 「所有」類型。

ServiceCompat.startForeground(0, notification, FOREGROUND_SERVICE_TYPE_LOCATION)

如未在呼叫中指定前景服務類型，則該類型會預設為資訊清單中定義的值。如果沒有指定服務 系統就會擲回 MissingForegroundServiceTypeException。

如果前景服務在啟動後需要新的權限，您應再次呼叫 startForeground()，並新增新的服務類型。適用對象 例如，假設某個健身應用程式執行了始終需要的跑步追蹤服務 location 資訊，但不一定需要 media 權限。個人中心 您需要在資訊清單中宣告 location 和 mediaPlayback。如果 使用者開始跑步，且只希望追蹤他們的位置。您的應用程式應該呼叫 startForeground()，並僅傳遞 location 服務類型。接著，如果使用者 想要開始播放音訊，請再次呼叫 startForeground() 並略過 location|mediaPlayback。

系統執行階段檢查

系統會檢查前景服務類型的使用是否恰當，並確認應用程式已要求合適的執行階段權限，或使用必要的 API。例如，系統會預期使用 FOREGROUND_SERVICE_TYPE_LOCATION 前景服務類型的應用程式要求 ACCESS_COARSE_LOCATION 或 ACCESS_FINE_LOCATION。

這表示當應用程式向使用者要求權限並啟動前景服務時，必須遵循特別明確的作業順序。應用程式必須先要求並取得權限，再嘗試呼叫 startForeground()。如果應用程式在前景服務啟動後才要求適當權限，則必須先變更此作業順序並要求權限，才能啟動前景服務。

關於平台違規處置的具體細節，請參閱本頁各前景服務類型預期用途與違規處置一節的「執行階段規定」部分。

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

您必須在資訊清單檔案中宣告特定權限，並滿足特定執行階段要求，而且應用程式必須滿足該類型預期用途的其中一項，才能使用特定的前景服務類型。以下各節說明您必須宣告的權限、執行階段必要條件，以及各個類型的預期用途。

相機

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

要求並授予 CAMERA 執行階段權限

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

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

注意：BODY_SENSORS 執行階段權限必須遵守使用期間的限制。因此，建立 health 前景服務時，無法在應用程式於背景執行時使用人體感應器，但只有少數例外。詳情請參閱「啟動需要使用期間權限的前景服務限制」。

說明

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

位置

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

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

注意：如要檢查使用者是否已啟用定位服務，並授予執行階段權限的存取權，請使用 PermissionChecker#checkSelfPermission()

注意：位置執行階段存取權在使用期間須遵守相關限制。因此，除非您已取得 ACCESS_BACKGROUND_LOCATION 執行階段權限，否則您無法在應用程式於背景建立 location 前景服務。詳情請參閱「啟動需要在使用期間權限的前景服務限制」。

說明

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

替代方案

如果您的應用程式需要在使用者抵達特定位置時觸發，請考慮改用 geofence API。

媒體

要在資訊清單中宣告的前景服務類型
android:foregroundServiceType
mediaPlayback
在資訊清單中宣告的權限
FOREGROUND_SERVICE_MEDIA_PLAYBACK
要傳遞至 startForeground() 的常數
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
執行階段必要條件
無
說明
在背景中繼續播放音訊或視訊。支援 Android TV 的數位錄影 (DVR) 功能。
替代方案
如果你使用的是子母畫面影片，請使用子母畫面模式。

媒體投影

要在資訊清單中宣告的前景服務類型
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 前景服務，但有以下限制。詳情請參閱「啟動需要使用期間權限的前景服務限制」。

說明

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

語音通話

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

供系統應用程式和特定系統整合使用， 才能繼續使用前景服務。

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

  • 裝置處於展示模式狀態
  • 應用程式為裝置擁有者
  • 應用程式為分析器擁有者
  • 具有 ROLE_EMERGENCY 角色的安全應用程式
  • 裝置管理員應用程式
  • 擁有 SCHEDULE_EXACT_ALARM 或 USE_EXACT_ALARM權限，正在使用 前景服務會繼續在背景響鈴 包括僅有觸覺回饋的鬧鐘

  • VPN 應用程式 (依序前往「設定」>「網路和網際網路」>「VPN」進行設定)

    否則的話，若宣告此型別會導致系統擲回 ForegroundServiceTypeNotAllowedException。

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

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