必須提供前景服務類型

為了協助開發人員更明確地定義面向使用者的前景服務，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，讓應用程式在隨附裝置在範圍內時持續執行。

如果應用程式需要掃描藍牙裝置，建議改用 Bluetooth 掃描 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 和感應器的 READ 執行階段權限會受到使用期間限制。因此，除非您已獲得 BODY_SENSORS_BACKGROUND (API 級別 33 至 35) 或 READ_HEALTH_DATA_IN_BACKGROUND (API 級別 36 以上) 權限，否則無法在應用程式處於背景執行時，建立使用身體感應器的 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 前景服務，但有少數例外情況。詳情請參閱「啟動需要使用中權限的前景服務的限制」。

說明

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

語音通話

Foreground service type to declare in manifest under
android:foregroundServiceType
phoneCall
Permission to declare in your manifest
FOREGROUND_SERVICE_PHONE_CALL
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_PHONE_CALL
Runtime prerequisites

At least one of these conditions must be true:

  • App is the default dialer app through the ROLE_DIALER role.
Description

Continue an ongoing call using the ConnectionService APIs.

Alternatives

If you need to make phone, video, or VoIP calls, consider using the android.telecom library.

Consider using CallScreeningService to screen calls.

遠端通訊

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