Diensttypen im Vordergrund

Ab Android 14 (API-Level 34) musst du 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. Außerdem müssen Sie abhängig vom Diensttyp im Vordergrund möglicherweise Laufzeitberechtigungen anfordern, bevor Sie den Dienst starten.

Kamera

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

Laufzeitberechtigung CAMERA anfordern und erhalten

Beschreibung

Zugriff auf die Kamera im Hintergrund ist weiterhin möglich, z. B. über Videoanruf-Apps, die Multitasking zulassen.

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 von Dienst im Vordergrund, der im Manifest deklariert werden soll unter
android:foregroundServiceType
dataSync
Berechtigung, die in Ihrem Manifest deklariert werden muss
FOREGROUND_SERVICE_DATA_SYNC
Konstante, die an startForeground() übergeben werden soll
FOREGROUND_SERVICE_TYPE_DATA_SYNC
Laufzeitvoraussetzungen
Keine
Beschreibung

Datenübertragungsvorgänge, z. B.:

  • Datenupload oder -download
  • Sicherungs- und Wiederherstellungsvorgänge
  • Import- oder Exportvorgänge
  • Daten abrufen
  • Lokale Dateiverarbeitung
  • Daten zwischen einem Gerät und der Cloud über ein Netzwerk ü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 Anwendungsfälle mit langer Ausführungszeit zur Unterstützung von Apps in der Fitnesskategorie, z. B. Fitness-Tracker.

Standort

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:

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.

Medien

Typ von Dienst im Vordergrund, der im Manifest deklariert werden soll 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. Unterstützung der Funktion „Digitaler Videorekorder“ (DVR) auf Android TV

Alternativen

Wenn Sie ein Bild-im-Bild-Video anzeigen, verwenden Sie den Bild-im-Bild-Modus.

Medien werden verarbeitet.

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

Dienst für zeitaufwendige Vorgänge wie die Umwandlung von Medien in verschiedene Formate mit Medien-Assets Das System lässt die Ausführung dieses Dienstes für eine begrenzte Zeit zu. Unter normalen Umständen beträgt dieses Zeitlimit 6 Stunden von jeweils 24 Stunden. Dieses Limit gilt für alle mediaProcessing-Dienste im Vordergrund einer App.

Ihre Anwendung sollte den Medienverarbeitungsdienst im folgenden Szenario manuell beenden:

Wenn das Zeitlimit erreicht ist, ruft das System die Methode Service.onTimeout(int, int) des Dienstes auf. Derzeit hat der Dienst einige Sekunden Zeit, Service.stopSelf() aufzurufen. Wenn der Dienst Service.stopSelf() nicht aufruft, tritt ein ANR-Fehler mit der folgenden Fehlermeldung auf: „A Vorwärtsdienst von <fgs_type> wurde nicht innerhalb des Zeitlimits beendet: <component_name>“.

Hinweis: Service.onTimeout(int, int) ist für Android 14 oder niedriger nicht verfügbar. Auf Geräten mit diesen Versionen speichert das System die App sofort im Cache, wenn ein Medienverarbeitungsdienst das Zeitlimit erreicht. Aus diesem Grund sollte Ihre App nicht auf eine Zeitüberschreitungsbenachrichtigung warten. Stattdessen sollte er so schnell wie angemessen den Dienst im Vordergrund beenden oder zu einem Hintergrunddienst wechseln.

Medienprojektion

Typ des Dienstes im Vordergrund, der im Manifest unter
android:foregroundServiceType
mediaProjection
Erklärung in deinem Manifest
FOREGROUND_SERVICE_MEDIA_PROJECTION
Konstante, die an startForeground() übergeben werden soll
FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
Laufzeitvoraussetzungen

Rufen Sie die Methode createScreenCaptureIntent() auf, bevor Sie den Dienst im Vordergrund starten. 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() aufrufen.

Beschreibung

Übertragung von Inhalten mit MediaProjection APIs auf nicht primäre Displays oder externe Geräte. Dabei muss es sich nicht ausschließlich um Medieninhalte handeln.

Alternativen

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

Mikrofon

Typ des Dienstes im Vordergrund, der im Manifest 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 und erhalten Sie sie.

Beschreibung

Setzen Sie die Mikrofonaufnahme im Hintergrund fort, z. B. mit Sprachrekordern oder Kommunikations-Apps.

Telefonanruf

Typ des Dienstes im Vordergrund, der im Manifest 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 ihrer Manifestdatei deklariert.
  • Die Anwendung ist die Standard-Telefon-App über die Rolle ROLE_DIALER.
Beschreibung

Setzen Sie einen laufenden Anruf mit den ConnectionService APIs fort.

Alternativen

Wenn Sie Telefon-, Video- oder VoIP-Anrufe starten möchten, können Sie die android.telecom-Bibliothek verwenden.

Du kannst zum Filtern von Anrufen CallScreeningService verwenden.

Remote-Messaging

Typ des Dienstes im Vordergrund, der im Manifest deklariert werden soll unter
android:foregroundServiceType
remoteMessaging
Deklarierungsberechtigung im Manifest
FOREGROUND_SERVICE_REMOTE_MESSAGING
Konstante zur Übergabe an startForeground()
FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
Laufzeitvoraussetzungen
Keine
Beschreibung
Nachrichten lassen sich von einem Gerät auf ein anderes übertragen. Unterstützt Nutzer beim Wechseln des Geräts dabei, dass ihre Messaging-Aufgaben weiter ausgeführt werden.

Kurze Wartung

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>

Systemausnahme

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

Wenn Ihre App auf Android 14 oder höher ausgerichtet ist, müssen Sie in der Play Console auf der Seite mit den App-Inhalten (Richtlinie > App-Inhalte) die Typen der Dienste im Vordergrund deklarieren. Weitere Informationen zum Deklarieren der Typen von Diensten im Vordergrund in der Play Console findest du unter Anforderungen für Dienste im Vordergrund und Full-Screen Intents.