Diensttypen im Vordergrund

Ab Android 14 (API-Ebene 34) müssen Sie für jeden Dienst im Vordergrund einen geeigneten Diensttyp deklarieren. Das bedeutet, dass Sie den Diensttyp in Ihrem App-Manifest deklarieren und die entsprechende Berechtigung für Dienste im Vordergrund für diesen Typ anfordern müssen (zusätzlich zur Anforderung der Berechtigung FOREGROUND_SERVICE). Außerdem müssen Sie je nach Diensttyp möglicherweise Laufzeitberechtigungen anfordern, bevor Sie den Dienst starten.

Hinweis :In vielen Fällen gibt es spezielle APIs, die Sie verwenden können, anstatt einen bestimmten Typ von Vordergrunddienst zu erstellen. Wenn zweckorientierte APIs verfügbar sind, sind sie in der Regel die bessere Wahl als das Erstellen eines Dienstes im Vordergrund. Diese APIs sind in den Abschnitten Alternativen der entsprechenden Arten von Vordergrunddiensten aufgeführt.

Kamera

要在清单中 android:foregroundServiceType 下声明的前台服务类型

camera

要在清单中声明的权限

FOREGROUND_SERVICE_CAMERA

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_CAMERA

运行时前提条件

请求并被授予 CAMERA 运行时权限

注意： CAMERA 运行时权限受“使用时”限制。因此，当应用在后台运行时，您无法创建 camera 前台服务，也无法从 BOOT_COMPLETED 接收器启动 camera 前台服务，但有少数例外情况。如需了解详情，请参阅与启动需要“使用时”权限的前台服务相关的限制。

说明

继续在后台访问相机，例如支持多任务的视频聊天应用。

Verbundenes Gerät

Typ des Dienstes im Vordergrund, der im Manifest unter

android:foregroundServiceType

connectedDevice

Berechtigung, die in Ihrem Manifest deklariert werden muss

FOREGROUND_SERVICE_CONNECTED_DEVICE

Konstante, die an startForeground() übergeben werden soll

FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE

Laufzeitvoraussetzungen

Mindestens eine der folgenden Bedingungen muss erfüllt sein:

• Deklarieren Sie mindestens eine der folgenden Berechtigungen in Ihrem Manifest:

  • CHANGE_NETWORK_STATE
  • CHANGE_WIFI_STATE
  • CHANGE_WIFI_MULTICAST_STATE
  • NFC
  • TRANSMIT_IR

• Sie müssen mindestens eine der folgenden Laufzeitberechtigungen anfordern und erhalten:

  • BLUETOOTH_CONNECT
  • BLUETOOTH_ADVERTISE
  • BLUETOOTH_SCAN
  • UWB_RANGING

• UsbManager.requestPermission() anrufen

Beschreibung

Interaktionen mit externen Geräten, die eine Bluetooth‑, NFC‑, IR‑, USB‑ oder Netzwerkverbindung erfordern.

Hinweis: Wenn Ihre App eine Projektion oder Remote-Messaging-Funktion ausführt, verwenden Sie stattdessen den entsprechenden Typ Medienprojektion oder Remote-Messaging.

Alternativen

Wenn Ihre App eine kontinuierliche Datenübertragung an ein externes Gerät ausführen muss, sollten Sie stattdessen den Companion Device Manager verwenden. Mit der API zur Anwesenheit von Companion-Geräten können Sie dafür sorgen, dass Ihre App weiter ausgeführt wird, solange sich das Companion-Gerät in Reichweite befindet.

Wenn Ihre App nach Bluetooth-Geräten suchen muss, können Sie stattdessen die Bluetooth Scan API verwenden.

Datensynchronisierung

要在清单中声明的前台服务类型，位于

android:foregroundServiceType

dataSync

要在清单中声明的权限

FOREGROUND_SERVICE_DATA_SYNC

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_DATA_SYNC

运行时前提条件

无

说明

数据传输操作，例如：

• 数据上传或下载
• 备份和恢复操作
• 导入或导出操作
• 获取数据
• 本地文件处理
• 通过网络在设备和云端之间传输数据

注意： 以 Android 15 或更高版本为目标平台的应用不允许从 BOOT_COMPLETED 广播接收器启动数据同步前台服务。如需了解详情，请参阅与 BOOT_COMPLETED 广播接收器启动前台服务相关的限制。

替代方案

如需了解详情，请参阅数据同步前台服务的替代方案。

Zustand

Typ des Diensts im Vordergrund, der im Manifest unter

android:foregroundServiceType

health

Berechtigung, die in Ihrem Manifest deklariert werden muss

FOREGROUND_SERVICE_HEALTH

Konstante, die an startForeground() übergeben werden soll

FOREGROUND_SERVICE_TYPE_HEALTH

Laufzeitvoraussetzungen

Mindestens eine der folgenden Bedingungen muss erfüllt sein:

• Deklarieren Sie die Berechtigung HIGH_SAMPLING_RATE_SENSORS in Ihrem Manifest.

• Sie müssen mindestens eine der folgenden Laufzeitberechtigungen anfordern und erhalten:

  • BODY_SENSORS bei API 35 und niedriger
  • READ_HEART_RATE
  • READ_SKIN_TEMPERATURE
  • READ_OXYGEN_SATURATION
  • ACTIVITY_RECOGNITION

Hinweis :Die Laufzeitberechtigungen BODY_SENSORS und die sensorbasierten Leseberechtigungen unterliegen Einschränkungen bei der Nutzung. Aus diesem Grund können Sie keinen health-Dienst im Vordergrund erstellen, der Körpersensoren verwendet, während sich Ihre App im Hintergrund befindet, es sei denn, Sie haben die Berechtigungen BODY_SENSORS_BACKGROUND (zwischen API-Level 33 und API-Level 35) oder READ_HEALTH_DATA_IN_BACKGROUND (API-Level 36) erhalten. Weitere Informationen finden Sie unter Einschränkungen beim Starten von Diensten im Vordergrund, für die Berechtigungen für die Nutzung erforderlich sind.

Beschreibung

Alle lang laufenden Anwendungsfälle zur Unterstützung von Apps in der Kategorie „Fitness“, z. B. Trainings-Tracker.

Standort

Typ des Dienstes im Vordergrund, der im Manifest unter

android:foregroundServiceType

location

Berechtigung, die in Ihrem Manifest deklariert werden muss

FOREGROUND_SERVICE_LOCATION

Konstante, die an startForeground() übergeben werden soll

FOREGROUND_SERVICE_TYPE_LOCATION

Laufzeitvoraussetzungen

Der Nutzer muss die Standortdienste aktiviert haben und der App muss mindestens eine der folgenden Laufzeitberechtigungen gewährt werden:

• ACCESS_COARSE_LOCATION
• ACCESS_FINE_LOCATION

Hinweis:Um zu prüfen, ob der Nutzer die Standortdienste aktiviert und Zugriff auf die Laufzeitberechtigungen gewährt hat, verwenden Sie PermissionChecker#checkSelfPermission()

.

Hinweis:Die Laufzeitberechtigungen für die Standortermittlung unterliegen Einschränkungen bei der Verwendung. Aus diesem Grund können Sie keinen location-Dienst im Vordergrund erstellen, während sich Ihre App im Hintergrund befindet, es sei denn, Sie haben die Laufzeitberechtigung ACCESS_BACKGROUND_LOCATION erhalten. Weitere Informationen finden Sie unter Einschränkungen beim Starten von Diensten im Vordergrund, für die Berechtigungen für die Nutzung erforderlich sind.

Beschreibung

Langlaufende Anwendungsfälle, für die der Standortzugriff erforderlich ist, z. B. Navigation und Standortfreigabe.

Alternativen

Wenn Ihre App ausgelöst werden soll, wenn der Nutzer bestimmte Orte erreicht, sollten Sie stattdessen die Geofence API verwenden.

Medien

要在清单中声明的前台服务类型，位于

android:foregroundServiceType

mediaPlayback

要在清单中声明的权限

FOREGROUND_SERVICE_MEDIA_PLAYBACK

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK

运行时前提条件

无

说明

在后台继续播放音频或视频。在 Android TV 上支持数字视频录制 (DVR) 功能。

注意： 以 Android 15 或更高版本为目标平台的应用不得从 BOOT_COMPLETED 广播接收器启动媒体播放前台服务。如需了解详情，请参阅与 BOOT_COMPLETED 广播接收器启动前台服务相关的限制。

替代方案

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

Medien werden verarbeitet.

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

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 或更低版本。在搭载这些版本的设备上，如果媒体处理服务达到超时期限，系统会立即缓存应用。因此，您的应用不应等待收到超时通知。相反，它应在适当情况下尽快终止前台服务或将其更改为后台服务。

Medienprojektion

Typ des Diensts im Vordergrund, der im Manifest unter

android:foregroundServiceType

mediaProjection

Berechtigung, die im Manifest deklariert werden muss

FOREGROUND_SERVICE_MEDIA_PROJECTION

Konstante, die an startForeground() übergeben werden soll

FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION

Voraussetzungen für die Laufzeit

Rufen Sie die Methode createScreenCaptureIntent() auf, bevor Sie den Dienst im Vordergrund starten. Dadurch wird dem Nutzer eine Berechtigungsbenachrichtigung angezeigt. Der Nutzer muss die Berechtigung erteilen, bevor Sie den Dienst erstellen können.

Nachdem Sie den Vordergrunddienst erstellt haben, können Sie MediaProjectionManager.getMediaProjection() aufrufen.

Beschreibung

Übertragung von Inhalten mit den MediaProjection APIs auf nicht primäre Displays oder externe Geräte. Diese Inhalte müssen nicht ausschließlich Medieninhalte sein.

Hinweis :Apps, die auf Android 15 oder höher ausgerichtet sind, dürfen keinen Dienst im Vordergrund für die Medienprojektion über einen BOOT_COMPLETED-Übertragungsempfänger starten. Weitere Informationen finden Sie unter Einschränkungen für BOOT_COMPLETED-Broadcast-Receiver, die Vordergrunddienste starten.

Alternativen

Wenn Sie Medien auf ein anderes Gerät streamen möchten, verwenden Sie das Google Cast SDK.

Mikrofon

要在清单中声明的前台服务类型，位于

android:foregroundServiceType

microphone

要在清单中声明的权限

FOREGROUND_SERVICE_MICROPHONE

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_MICROPHONE

运行时前提条件

请求并被授予 RECORD_AUDIO 运行时权限。

注意： RECORD_AUDIO 运行时权限受“使用时”限制。因此，当应用在后台运行时，您无法创建 microphone 前台服务，也无法从 BOOT_COMPLETED 接收器启动 microphone 前台服务，但有少数例外情况。如需了解详情，请参阅与启动需要“使用时”权限的前台服务相关的限制。

说明

在后台继续捕获麦克风内容，例如录音器或通信应用。

Telefonanruf

要在清单中声明的前台服务类型，位于

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 来过滤来电。

Remote-Messaging

Typ des Dienstes im Vordergrund, der im Manifest unter

android:foregroundServiceType

remoteMessaging

Berechtigung, die in Ihrem Manifest deklariert werden muss

FOREGROUND_SERVICE_REMOTE_MESSAGING

Konstante, die an startForeground() übergeben werden soll

FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING

Laufzeitvoraussetzungen

Keine

Beschreibung

Sie können Nachrichten von einem Gerät auf ein anderes übertragen. Unterstützt Nutzer beim Wechseln des Geräts, ohne dass die Messaging-Aufgaben weiter ausgeführt werden.

Kurzer Service

Typ des Dienstes im Vordergrund, der im Manifest unter

android:foregroundServiceType

shortService

Berechtigung, die in Ihrem Manifest deklariert werden muss

Keine

Konstante, die an startForeground() übergeben werden soll

FOREGROUND_SERVICE_TYPE_SHORT_SERVICE

Laufzeitvoraussetzungen

Keine

Beschreibung

Sie können wichtige Aufgaben, die nicht unterbrochen oder verschoben werden können, schnell erledigen.

Dieser Typ hat einige einzigartige Eigenschaften:

• Kann nur für einen kurzen Zeitraum (ca. 3 Minuten) ausgeführt werden.
• Keine Unterstützung für persistente Dienste im Vordergrund.
• Andere Dienste im Vordergrund können nicht gestartet werden.
• Erfordert keine typspezifische Berechtigung, aber die Berechtigung FOREGROUND_SERVICE.
• Ein shortService kann nur zu einem anderen Diensttyp wechseln, wenn die App derzeit berechtigt ist, einen neuen Dienst im Vordergrund zu starten.
• Ein Dienst im Vordergrund kann seinen Typ jederzeit in shortService ändern. Ab diesem Zeitpunkt beginnt die Zeitüberschreitung.

Das Zeitlimit für shortService beginnt, sobald Service.startForeground() aufgerufen wird. Die App sollte Service.stopSelf() oder Service.stopForeground() aufrufen, bevor die Zeitüberschreitung eintritt. Andernfalls wird der neue Service.onTimeout() aufgerufen, wodurch Apps kurzzeitig die Möglichkeit haben, stopSelf() oder stopForeground() aufzurufen, um ihren Dienst zu beenden.

Kurz nach dem Aufruf von Service.onTimeout() wechselt die App in den Cache-Status und wird nicht mehr als App im Vordergrund betrachtet, es sei denn, der Nutzer interagiert aktiv mit der App. Kurz nachdem die App im Cache gespeichert wurde und der Dienst nicht beendet wurde, erhält die App eine ANR. In der ANR-Nachricht wird FOREGROUND_SERVICE_TYPE_SHORT_SERVICE erwähnt. Aus diesen Gründen wird empfohlen, den Service.onTimeout()-Callback zu implementieren.

Der Service.onTimeout()-Callback ist unter Android 13 und niedriger nicht vorhanden. Wenn derselbe Dienst auf solchen Geräten ausgeführt wird, erhält er weder ein Zeitlimit noch eine ANR. Der Dienst muss beendet werden, sobald die Verarbeitungsaufgabe abgeschlossen ist, auch wenn der Service.onTimeout()-Callback noch nicht empfangen wurde.

Wenn das Zeitlimit der shortService nicht eingehalten wird, wird für die App ein ANR ausgegeben, auch wenn andere gültige Dienste im Vordergrund oder andere App-Lebenszyklus-Prozesse ausgeführt werden.

Wenn eine App für den Nutzer sichtbar ist oder eine der Ausnahmen erfüllt, die es ermöglichen, Dienste im Vordergrund aus dem Hintergrund zu starten, wird die Zeitüberschreitung durch einen erneuten Aufruf von Service.StartForeground() mit dem Parameter FOREGROUND_SERVICE_TYPE_SHORT_SERVICE um weitere drei Minuten verlängert. Wenn die App für den Nutzer nicht sichtbar ist und keinen der Ausnahmen erfüllt, führt jeder Versuch, einen weiteren Dienst im Vordergrund zu starten, unabhängig vom Typ, zu einer ForegroundServiceStartNotAllowedException.

Wenn ein Nutzer die Akku-Optimierung für Ihre App deaktiviert, ist sie weiterhin vom Zeitlimit für shortService-FGS betroffen.

Wenn Sie einen Dienst im Vordergrund starten, der den Typ shortService und einen anderen Typ von Dienst im Vordergrund enthält, wird die Deklaration des Typs shortService vom System ignoriert. Der Dienst muss jedoch weiterhin die Voraussetzungen der anderen angegebenen Typen erfüllen. Weitere Informationen finden Sie in der Dokumentation zu Diensten im Vordergrund.

Spezielle Anwendungsfälle

要在清单中声明的前台服务类型

android:foregroundServiceType

specialUse

在清单中声明的权限

FOREGROUND_SERVICE_SPECIAL_USE

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_SPECIAL_USE

运行时前提条件

无

说明

涵盖其他前台服务类型未涵盖的所有有效前台服务用例。

除了声明 FOREGROUND_SERVICE_TYPE_SPECIAL_USE 前台服务类型之外，开发者还应在清单中声明用例。为此，他们会在 <service> 元素内指定 <property> 元素。这些值和相应的应用场景 。用途 您提供的案例均为自由形式，因此，您应确保提供足够的 相关信息，让审核人员了解您为何需要使用 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>

Vom System ausgenommen

要在其清单中声明的前台服务类型

android:foregroundServiceType

systemExempted

在清单中声明的权限

FOREGROUND_SERVICE_SYSTEM_EXEMPTED

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED

运行时前提条件

无

说明

为系统应用和特定系统集成预留，以便继续使用前台服务。

如需使用此类型，应用必须至少满足以下条件之一：

• 设备处于演示模式状态
• 应用是设备所有者
• 应用是性能分析器所有者
• 属于具有 ROLE_EMERGENCY 角色的安全应用
• 属于设备管理应用
• 具有 SCHEDULE_EXACT_ALARM 或 USE_EXACT_ALARM 权限的应用

• VPN 应用（通过设置 > 网络和互联网 > VPN 进行配置）

  否则，声明此类型会导致系统抛出 ForegroundServiceTypeNotAllowedException。

Durchsetzung der Google Play-Richtlinien für die Verwendung von Diensttypen im Vordergrund

如果您的应用以 Android 14 或更高版本为目标平台，您需要在 Play 管理中心的“应用内容”页面（政策 > 应用内容）中声明应用的前台服务类型。如需详细了解如何在 Play 管理中心内声明前台服务类型，请参阅了解前台服务和全屏 intent 要求。