前景服務類型

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

注意： 在許多情況下，您可以使用專為特定用途設計的 API，而不必建立特定類型的前景服務。如果可以使用專用 API，通常會比建立前景服務更合適。這些 API 會列在適當前景服務類型中的「替代方案」部分。

相機

Foreground service type to declare in manifest under android:foregroundServiceType

camera

Permission to declare in your manifest

FOREGROUND_SERVICE_CAMERA

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_CAMERA

Runtime prerequisites

Request and be granted the CAMERA runtime permission

Note: The CAMERA runtime permission is subject to while-in-use restrictions. For this reason, you cannot create a camera foreground service while your app is in the background and you cannot launch a camera foreground service from a BOOT_COMPLETED receiver, with a few exceptions. For more information, see Restrictions on starting foreground services that need while-in-use permissions.

Description

Continue to access the camera from the background, such as video chat apps that allow for multitasking.

已連結的裝置

Foreground service type to declare in manifest under

android:foregroundServiceType

connectedDevice

Permission to declare in your manifest

FOREGROUND_SERVICE_CONNECTED_DEVICE

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE

Runtime prerequisites

At least one of the following conditions must be true:

• Declare at least one of the following permissions in your manifest:

  • CHANGE_NETWORK_STATE
  • CHANGE_WIFI_STATE
  • CHANGE_WIFI_MULTICAST_STATE
  • NFC
  • TRANSMIT_IR

• Request and be granted at least one of the following runtime permissions:

  • BLUETOOTH_CONNECT
  • BLUETOOTH_ADVERTISE
  • BLUETOOTH_SCAN
  • UWB_RANGING

• Call UsbManager.requestPermission()

Description

Interactions with external devices that require a Bluetooth, NFC, IR, USB, or network connection.

Note: If your app performs a projection or remote messaging operation, use the corresponding media projection or remote messaging type instead.

Alternatives

If your app needs to do continuous data transfer to an external device, consider using the companion device manager instead. Use the companion device presence API to help your app stay running while the companion device is in range.

If your app needs to scan for bluetooth devices, consider using the Bluetooth scan API instead.

同步處理資料

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

android:foregroundServiceType

dataSync

在資訊清單中宣告的權限

FOREGROUND_SERVICE_DATA_SYNC

要傳遞至 startForeground() 的常數

FOREGROUND_SERVICE_TYPE_DATA_SYNC

執行階段必要條件

無

說明

資料移轉作業，例如：

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

注意： 如果應用程式指定 Android 15 以上版本，就無法透過 BOOT_COMPLETED 廣播接收器啟動資料同步前景服務。詳情請參閱「限制 BOOT_COMPLETED 廣播接收器啟動前景服務」

。

替代選項

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

健康度

Foreground service type to declare in manifest under

android:foregroundServiceType

health

Permission to declare in your manifest

FOREGROUND_SERVICE_HEALTH

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_HEALTH

Runtime prerequisites

At least one of the following conditions must be true:

• Declare the HIGH_SAMPLING_RATE_SENSORS permission in your manifest.

• Request and be granted at least one of the following runtime permissions:

  • BODY_SENSORS on API 35 and lower
  • READ_HEART_RATE
  • READ_SKIN_TEMPERATURE
  • READ_OXYGEN_SATURATION
  • ACTIVITY_RECOGNITION

Note: The BODY_SENSORS and sensor-based READ runtime permissions are subject to while-in-use restrictions. For this reason, you cannot create a health foreground service that uses body sensors while your app is in the background, unless you've been granted the BODY_SENSORS_BACKGROUND (between API level 33 and API level 35) or READ_HEALTH_DATA_IN_BACKGROUND (API level 36) permissions. For more information, see Restrictions on starting foreground services that need while-in-use permissions.

Description

Any long-running use cases to support apps in the fitness category such as exercise trackers.

位置

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

Note: In order to check that the user has enabled location services as well as granted access to the runtime permissions, use PermissionChecker#checkSelfPermission()

Note: The location runtime permissions are subject to while-in-use restrictions. For this reason, you cannot create a location foreground service while your app is in the background, unless you've been granted the ACCESS_BACKGROUND_LOCATION runtime permission. For more information, see Restrictions on starting foreground services that need while-in-use permissions.

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 15 或更高版本为目标平台的应用不得从 BOOT_COMPLETED 广播接收器启动媒体播放前台服务。如需了解详情，请参阅与 BOOT_COMPLETED 广播接收器启动前台服务相关的限制。

替代方案

如果您要显示画中画视频，请使用画中画模式。

處理中的媒體項目

要在清单中的以下位置声明的前台服务类型

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 將內容投影到非主要螢幕或外部裝置。此類內容不侷限於媒體內容。

注意： 如果應用程式指定 Android 15 以上版本，就無法透過 BOOT_COMPLETED 廣播接收器啟動媒體投影前景服務。詳情請參閱「限制 BOOT_COMPLETED 廣播接收器啟動前景服務」

。

替代選項

如要將媒體串流至其他裝置，請使用 Google Cast SDK。

麥克風

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

android:foregroundServiceType

microphone

在資訊清單中宣告的權限

FOREGROUND_SERVICE_MICROPHONE

要傳遞至 startForeground() 的常數

FOREGROUND_SERVICE_TYPE_MICROPHONE

執行階段必要條件

要求並取得 RECORD_AUDIO 執行階段權限。

注意： RECORD_AUDIO 執行階段權限須遵守「僅限使用期間」限制。因此，應用程式在背景執行時，您無法建立 microphone 前景服務，也無法從 BOOT_COMPLETED 接收器啟動 microphone 前景服務 (少數例外情況除外)。詳情請參閱「限制啟動需要『僅限使用期間』權限的前景服務」。

說明

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

語音通話

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

android:foregroundServiceType

phoneCall

在資訊清單中宣告的權限

FOREGROUND_SERVICE_PHONE_CALL

要傳遞至 startForeground() 的常數

FOREGROUND_SERVICE_TYPE_PHONE_CALL

執行階段必要條件

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

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

• 應用程式是透過 ROLE_DIALER 角色成為預設撥號應用程式。

注意： 如果應用程式指定 Android 15 以上版本，就無法透過 BOOT_COMPLETED 廣播接收器啟動電話通訊前景服務。詳情請參閱「限制 BOOT_COMPLETED 廣播接收器啟動前景服務」

。

說明

使用 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 管理中心内声明前台服务类型，请参阅了解前台服务和全屏 intent 要求。