Diensttypen im Vordergrund

Ab Android 14 (API-Ebene 34) müssen Sie für jeden Dienst im Vordergrund einen geeigneten Diensttyp deklarieren. Sie müssen also den Diensttyp in Ihrem App-Manifest deklarieren und zusätzlich zur Berechtigung FOREGROUND_SERVICE die entsprechende Berechtigung für Dienste im Vordergrund für diesen Typ anfordern. Je nach Typ des Diensts im Vordergrund können Sie außerdem Sie müssen Laufzeitberechtigungen anfordern, bevor Sie den Dienst starten.

Kamera

Typ des Diensts im Vordergrund, der im Manifest unter android:foregroundServiceType deklariert werden soll
camera
Berechtigung, die in Ihrem Manifest deklariert werden muss
FOREGROUND_SERVICE_CAMERA
Konstante zur Übergabe an startForeground()
FOREGROUND_SERVICE_TYPE_CAMERA
Laufzeitvoraussetzungen

Laufzeitberechtigung CAMERA anfordern und erhalten

Beschreibung

Zugriff auf die Kamera im Hintergrund, z. B. Videochat-Apps, weiterhin möglich die Multitasking ermöglichen.

Verbundenes Gerät

Typ des Dienstes im Vordergrund, der im Manifest deklariert werden soll unter
android:foregroundServiceType
connectedDevice
Deklarierungsberechtigung im Manifest
FOREGROUND_SERVICE_CONNECTED_DEVICE
Konstante zur Übergabe an startForeground()
FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
Laufzeitvoraussetzungen

Es muss mindestens eine der folgenden Bedingungen erfüllt sein:

Beschreibung

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

Alternativen

Wenn Ihre App eine kontinuierliche Datenübertragung an ein externes Gerät durchführen muss, verwenden Sie stattdessen den Companion-Gerätemanager. Mit der Companion Device Presence API können Sie dafür sorgen, dass Ihre App auch dann ausgeführt wird, wenn sich das Begleitgerät in Reichweite befindet.

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

Datensynchronisierung

Typ des Dienstes im Vordergrund, der im Manifest unter
android:foregroundServiceType
dataSync
Erklärung in deinem Manifest
FOREGROUND_SERVICE_DATA_SYNC
Konstante zur Übergabe an startForeground()
FOREGROUND_SERVICE_TYPE_DATA_SYNC
Laufzeitvoraussetzungen
Keine
Beschreibung

Datenübertragungsvorgänge, z. B.:

  • Daten hochladen oder herunterladen
  • Sicherungs- und Wiederherstellungsvorgänge
  • Import- oder Exportvorgänge
  • Daten abrufen
  • Lokale Dateiverarbeitung
  • Daten über ein Netzwerk zwischen einem Gerät und der Cloud übertragen
Alternativen

Ausführliche Informationen finden Sie unter Alternativen zu Diensten im Vordergrund für die Datensynchronisierung.

Zustand

Typ des Dienstes 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:

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:

.
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

Typ des Dienstes im Vordergrund, der im Manifest unter
android:foregroundServiceType
mediaPlayback
Berechtigung, die in Ihrem Manifest deklariert werden muss
FOREGROUND_SERVICE_MEDIA_PLAYBACK
Konstante, die an startForeground() übergeben werden soll
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
Laufzeitvoraussetzungen
Keine
Beschreibung

Fortsetzung der Audio‑ oder Videowiedergabe im Hintergrund. Support für digitale Videos Aufzeichnungsfunktion (DVR) unter Android TV

Alternativen

Wenn du den Bild-im-Bild-Modus nutzt, verwende Bild-im-Bild-Modus:

Medien werden verarbeitet.

要在其清单中声明的前台服务类型
android:foregroundServiceType
mediaProcessing
在清单中声明的权限
FOREGROUND_SERVICE_MEDIA_PROCESSING
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING
运行时前提条件
无
说明

用于对媒体资源执行耗时操作的服务，例如将媒体转换为不同格式。系统允许此服务有有限的运行时间；在正常情况下，此时间限制为每 24 小时 6 小时。（此限制由应用的所有 mediaProcessing 前台服务共享。）

您的应用应在以下情况下手动停止媒体处理服务：

如果达到超时期限，系统会调用服务的 Service.onTimeout(int, int) 方法。此时，服务有几秒钟时间来调用 Service.stopSelf()。如果服务未调用 Service.stopSelf()，将发生 ANR，并显示以下错误消息：“<fgs_type> 的前台服务未在其超时内停止：<component_name>”。

注意：Service.onTimeout(int, int) 不适用于 Android 14 或更低版本。在运行这些版本的设备上，如果媒体处理服务达到超时期限，系统会立即缓存应用。因此，您的应用不应等待收到超时通知。而是应尽快终止前台服务或将其更改为后台服务。

Medienprojektion

Typ des Dienstes im Vordergrund, der im Manifest unter
android:foregroundServiceType
mediaProjection
Berechtigung, die in Ihrem Manifest deklariert werden muss
FOREGROUND_SERVICE_MEDIA_PROJECTION
Konstante zur Übergabe an startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
Laufzeitvoraussetzungen

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

Nachdem Sie den Dienst im Vordergrund erstellt haben, können Sie MediaProjectionManager.getMediaProjection()

Beschreibung

Inhalte mit dem MediaProjection APIs Diese Inhalte müssen nicht ausschließlich Medieninhalte sein.

Alternativen

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

Mikrofon

Typ von Dienst im Vordergrund, der im Manifest deklariert werden soll unter
android:foregroundServiceType
microphone
Berechtigung, die in Ihrem Manifest deklariert werden muss
FOREGROUND_SERVICE_MICROPHONE
Konstante zur Übergabe an startForeground()
FOREGROUND_SERVICE_TYPE_MICROPHONE
Laufzeitvoraussetzungen

Fordern Sie die Laufzeitberechtigung RECORD_AUDIO an, um ihnen die Laufzeitberechtigung zu gewähren.

Beschreibung

Mikrofonaufzeichnung im Hintergrund fortsetzen, z. B. bei Sprachrekordern oder Kommunikations-Apps

Telefonanruf

Typ von Dienst im Vordergrund, der im Manifest deklariert werden soll unter
android:foregroundServiceType
phoneCall
Erklärung in deinem Manifest
FOREGROUND_SERVICE_PHONE_CALL
Konstante, die an startForeground() übergeben werden soll
FOREGROUND_SERVICE_TYPE_PHONE_CALL
Laufzeitvoraussetzungen

Mindestens eine der folgenden Bedingungen muss erfüllt sein:

  • Die App hat die Berechtigung MANAGE_OWN_CALLS in ihrem Manifest deklariert -Datei.
  • Die App ist die Standard-App fürs Telefonieren über die Rolle ROLE_DIALER.
Beschreibung

Fortsetzen eines laufenden Anrufs mit den ConnectionService APIs

Alternativen

Für Telefon-, Video- oder VoIP-Anrufe sollten Sie die android.telecom-Bibliothek.

Sie können CallScreeningService verwenden, um Anrufe zu filtern.

Remote-Messaging

要在其清单中声明的前台服务类型
android:foregroundServiceType
remoteMessaging
在清单中声明的权限
FOREGROUND_SERVICE_REMOTE_MESSAGING
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
运行时前提条件
无
说明
将短信从一台设备转移到另一台设备。在用户切换设备时，帮助确保用户消息任务的连续性。

Kurze Verbindung

Typ des Dienstes im Vordergrund, der im Manifest deklariert werden soll unter
android:foregroundServiceType
shortService
Deklarierungsberechtigung im Manifest
Keine
Konstante zur Übergabe an startForeground()
FOREGROUND_SERVICE_TYPE_SHORT_SERVICE
Laufzeitvoraussetzungen
Keine
Beschreibung

Sie können wichtige Arbeiten, die nicht unterbrochen oder verschoben werden können, schnell abschließen.

Dieser Typ hat einige besondere Merkmale:

  • Kann nur für kurze Zeit (ca. 3 Minuten) ausgeführt werden.
  • Keine Unterstützung für fixierte 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 dann in einen anderen Diensttyp geändert werden, wenn die App derzeit einen neuen Dienst im Vordergrund starten kann.
  • Ein Dienst im Vordergrund kann seinen Typ jederzeit in shortService ändern. Danach beginnt das Zeitlimit.

Das Zeitlimit für shortService beginnt mit dem Aufruf von Service.startForeground(). Die App ruft vor dem Zeitlimit Service.stopSelf() oder Service.stopForeground() auf. Andernfalls wird die neue Service.onTimeout() aufgerufen. Dadurch haben Apps die Möglichkeit, kurz stopSelf() oder stopForeground() aufzurufen, um ihren Dienst zu beenden.

Kurz nach dem Aufruf von Service.onTimeout() geht die Anwendung in einen Cache-Status ein und gilt nicht mehr als Vordergrundmodus, es sei denn, der Nutzer interagiert aktiv mit der App. Kurz nachdem die App im Cache gespeichert und der Dienst nicht beendet wurde, empfängt die App einen ANR-Fehler. Die ANR-Nachricht enthält FOREGROUND_SERVICE_TYPE_SHORT_SERVICE. Aus diesen Gründen gilt es als Best Practice, 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 keine Zeitüberschreitung und kein ANR-Fehler. Achten Sie darauf, dass Ihr Dienst beendet wird, sobald er die Verarbeitungsaufgabe abgeschlossen hat, auch wenn er den Service.onTimeout()-Callback noch nicht erhalten hat.

Wichtig: Wenn das Zeitlimit von shortService nicht eingehalten wird, löst die Anwendung auch dann einen ANR-Fehler aus, wenn andere gültige Dienste im Vordergrund oder andere Lebenszyklusprozesse von Anwendungen ausgeführt werden.

Wenn eine App für den Nutzer sichtbar ist oder eine der Ausnahmen erfüllt, die das Starten von Diensten im Vordergrund aus dem Hintergrund ermöglichen, wird das Zeitlimit um weitere 3 Minuten verlängert, wenn Service.StartForeground() noch einmal mit dem Parameter FOREGROUND_SERVICE_TYPE_SHORT_SERVICE aufgerufen wird. Wenn die App für den Nutzer nicht sichtbar ist und keine der Ausnahmen erfüllt, wird bei jedem Versuch, einen anderen Dienst im Vordergrund zu starten, unabhängig vom Typ ein ForegroundServiceStartNotAllowedException ausgelöst.

Wenn ein Nutzer die Akkuoptimierung 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 Dienst im Vordergrund enthält, ignoriert das System die Deklaration des Typs shortService. Der Dienst muss jedoch weiterhin die Voraussetzungen der anderen deklarierten Typen erfüllen. Weitere Informationen finden Sie in der Dokumentation zu Diensten im Vordergrund.

Spezielle Anwendungsfälle

Typ von Dienst im Vordergrund, der im Manifest deklariert werden soll unter
android:foregroundServiceType
specialUse
Erklärung in deinem Manifest
FOREGROUND_SERVICE_SPECIAL_USE
Konstante zur Übergabe an startForeground()
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
Laufzeitvoraussetzungen
Keine
Beschreibung

Umfasst alle gültigen Anwendungsfälle für Dienste im Vordergrund, die nicht vom anderen Typen von Diensten im Vordergrund.

Zusätzlich zur Deklaration der FOREGROUND_SERVICE_TYPE_SPECIAL_USE Dienst im Vordergrund verwenden, sollten Entwickler Anwendungsfälle in der Manifests. Dazu geben sie das Element <property> im <service>-Element. Diese Werte und entsprechenden Anwendungsfälle wenn du deine App in der Google Play Console einreichst. Die Verwendung sind kostenlos formulierte Anfragen und Sie sollten darauf achten, damit der Prüfer weiß, warum du die specialUse verwenden musst Typ.

<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

Typ des Dienstes im Vordergrund, der im Manifest deklariert werden soll unter
android:foregroundServiceType
systemExempted
Deklarierungsberechtigung im Manifest
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
Konstante zur Übergabe an startForeground()
FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
Laufzeitvoraussetzungen
Keine
Beschreibung

Ist für Systemanwendungen und bestimmte Systemintegrationen vorgesehen, um weiterhin Dienste im Vordergrund zu verwenden.

Zur Verwendung dieses Typs muss eine App mindestens eines der folgenden Kriterien erfüllen:

Google Play-Richtlinienerzwingung für die Verwendung von Typen von Diensten im Vordergrund

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