必須提供前景服務類型

為了協助開發人員更明確地定義面向使用者的前景服務，Android 10 在 <service> 元素中導入了 android:foregroundServiceType 屬性。

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

如果應用程式的用途與上述任一類型無關，強烈建議您遷移邏輯，以便使用 WorkManager 或使用者啟動的資料移轉作業。

Android 14 新增 health, remoteMessaging, shortService, specialUse 和 systemExempted 類型。

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

<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 為目標的應用程式未在資訊清單中定義特定服務類型，則系統將會在呼叫該服務的 startForeground() 時提高 MissingForegroundServiceTypeException。

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

如果以 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
執行階段必要條件
無
說明

資料移轉作業，例如：

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

建立使用者啟動的資料移轉作業，讓使用者開始長時間執行的資料上傳或下載工作。

使用 Download Manager API 從 URI 下載資料。

使用 BackupManager 備份或還原資料。

如需其他用途，請考慮使用 WorkManager。

健康

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

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

注意：位置執行階段權限會受到使用時的限制。因此，在應用程式於背景執行時，您無法建立 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 繼續目前的通話。

替代選項

如需撥打電話、視訊或 IP 網路語音傳遞技術通話，請考慮使用 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 前景服務類型之外，開發人員也應在資訊清單中宣告用途。為此，開發人員可在 <service> 元素中指定 <property> 元素。在您透過 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 管理中心宣告前景服務類型，請參閱「瞭解前景服務和全螢幕意圖規定」。