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

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:

Description

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

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.

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.

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
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

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.

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 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

Foreground service type to declare in manifest under
android:foregroundServiceType
specialUse
Permission to declare in your manifest
FOREGROUND_SERVICE_SPECIAL_USE
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
Runtime prerequisites
None
Description

Covers any valid foreground service use cases that aren't covered by the other foreground service types.

In addition to declaring the FOREGROUND_SERVICE_TYPE_SPECIAL_USE foreground service type, developers should declare use cases in the manifest. To do so, they specify the <property> element within the <service> element. These values and corresponding use cases are reviewed when you submit your app in the Google Play Console. The use cases you provide are free-form, and you should make sure to provide enough information to let the reviewer see why you need to use the specialUse type.

<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

Wenn Ihre App auf Android 14 oder höher ausgerichtet ist, müssen Sie die Typen der Dienste im Vordergrund Ihrer App auf der Seite „App-Inhalte“ in der Play Console (Richtlinie > App-Inhalte) deklarieren. Weitere Informationen dazu, wie Sie die Typen Ihrer Dienste im Vordergrund in der Play Console deklarieren, finden Sie unter Anforderungen für Dienste im Vordergrund und Full-Screen Intents.