Dienste im Vordergrund

Dienste im Vordergrund führen Vorgänge aus, die für den Nutzer erkennbar sind.

Bei Diensten im Vordergrund wird eine Statusleiste angezeigt. , um Nutzer darauf hinzuweisen, App führt eine Aufgabe im Vordergrund aus und verbraucht Systemressourcen.

Beispiele für Apps, die Dienste im Vordergrund verwenden, sind:

• Eine Musikplayer-App, die Musik in einem Dienst im Vordergrund abspielt. Die Benachrichtigung wird möglicherweise der aktuell abgespielte Titel angezeigt.
• Bei einer Fitness-App, die den Lauf eines Nutzers in einem Dienst im Vordergrund aufzeichnet, nachdem der eine Berechtigung vom Nutzer erhält. In der Benachrichtigung wird möglicherweise die Entfernung angezeigt, die der Nutzer während der aktuellen Fitnesssitzung zurückgelegt hat.

Verwende einen Dienst im Vordergrund nur, wenn deine App eine Aufgabe ausführen muss die der Nutzer bemerkbar macht, auch wenn er nicht direkt in der App. Wenn die Aktion von geringer Wichtigkeit ist, Benachrichtigung mit der niedrigsten Priorität, erstellen Sie einen Hintergrund .

In diesem Dokument wird die erforderliche Berechtigung für die Verwendung von Diensten im Vordergrund beschrieben. und wie Sie einen Dienst im Vordergrund starten und aus dem Hintergrund entfernen. Außerdem beschreibt, wie bestimmte Anwendungsfälle mit Typen von Diensten im Vordergrund verknüpft werden. Die Zugriffsbeschränkungen, die wirksam werden, wenn Sie einen Dienst im Vordergrund starten über eine App, die im Hintergrund ausgeführt wird.

Der Nutzer kann Benachrichtigungen standardmäßig schließen

Ab Android 13 (API-Level 33) können Nutzer die Benachrichtigung schließen die standardmäßig mit einem Dienst im Vordergrund verknüpft sind. Dazu wischen die Nutzenden auf die Benachrichtigung. Normalerweise wird die Benachrichtigung wird nur dann geschlossen, wenn der Dienst im Vordergrund beendet oder entfernt wird. aus dem Vordergrund.

Wenn Sie möchten, dass der Nutzer die Benachrichtigung nicht schließen kann, gehen Sie true in setOngoing() wenn Sie die Benachrichtigung mit Notification.Builder erstellen.

Dienste, bei denen sofort eine Benachrichtigung angezeigt wird

Wenn ein Dienst im Vordergrund mindestens eine der folgenden Eigenschaften hat, gilt Folgendes: zeigt das System die zugehörige Benachrichtigung sofort nach Dienststart an. auch auf Geräten mit Android 12 oder höher:

• Der Dienst ist mit einer Benachrichtigung verknüpft, die eine Aktion enthält. .
• Der Dienst hat ein foregroundServiceType von mediaPlayback, mediaProjection oder phoneCall
• Der Dienst bietet einen Anwendungsfall im Zusammenhang mit Telefonanrufen, Navigation oder Medien. Wiedergabe entsprechend der Definition in der Kategorie der Benachrichtigung Attribut
• Der Dienst hat der Verhaltensänderung unterbunden, indem er FOREGROUND_SERVICE_IMMEDIATE in setForegroundServiceBehavior() wenn Sie die Benachrichtigung einrichten.

Unter Android 13 (API-Level 33) oder höher, wenn der Nutzer Berechtigung zum Senden von Benachrichtigungen sehen sie trotzdem Hinweise zu Diensten im Vordergrund Task-Manager aber nicht in der Benachrichtigungsleiste.

Dienste im Vordergrund in deinem Manifest deklarieren

Deklarieren Sie im Manifest Ihrer App die einzelnen Dienste im Vordergrund Ihrer App mit <service> -Elements. Verwenden Sie für jeden Dienst ein android:foregroundServiceType-Attribut um die Art der Dienstleistung zu deklarieren.

Wenn Ihre App beispielsweise einen Dienst im Vordergrund erstellt, über den Musik wiedergegeben wird, den Dienst wie folgt deklarieren:

<manifest xmlns:android="http://schemas.android.com/apk/res/android" ...>
  <application ...>

    <service
        android:name=".MyMediaPlaybackService"
        android:foregroundServiceType="mediaPlayback"
        android:exported="false">
    </service>
  </application>
</manifest>

Wenn für Ihren Dienst mehrere Typen gelten, trennen Sie sie mit |. . Beispiel: Ein Dienst, der Kamera und Mikrofon verwendet wie folgt deklarieren:

android:foregroundServiceType="camera|microphone"

Berechtigungen für Dienste im Vordergrund anfordern

Apps, die auf Android 9 (API-Level 28) oder höher ausgerichtet sind und Dienste im Vordergrund verwenden müssen Sie die FOREGROUND_SERVICE im App-Manifest ein, wie im folgenden Code-Snippet gezeigt. Dies ist ein normaler Berechtigung gibt, damit das System automatisch der anfragenden App zu.

Wenn die App auf API-Level 34 oder höher ausgerichtet ist, muss sie das API-Level Berechtigungstyp für die Art der Arbeit, die der Dienst im Vordergrund ist was Sie tun. Jeder Typ von Diensten im Vordergrund einen entsprechenden Berechtigungstyp hat. Startet eine App beispielsweise eine die die Kamera verwendet, müssen Sie sowohl den FOREGROUND_SERVICE und FOREGROUND_SERVICE_CAMERA Berechtigungen. Dabei handelt es sich alles um normale Berechtigungen, die vom System erteilt werden. wenn sie im Manifest aufgeführt sind.

<manifest xmlns:android="http://schemas.android.com/apk/res/android" ...>

    <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA"/>

    <application ...>
        ...
    </application>
</manifest>

Voraussetzungen für Dienste im Vordergrund

Ab Android 14 (API-Level 34) gilt: Wenn Sie einen Dienst im Vordergrund starten, prüft das System je nach Diensttyp auf bestimmte Voraussetzungen. Beispiel: Wenn Sie versuchen, einen Dienst im Vordergrund vom Typ location zu starten, prüft das System um sicherzustellen, dass Ihre App entweder die ACCESS_COARSE_LOCATION- oder Berechtigung ACCESS_FINE_LOCATION. Ist dies nicht der Fall, SecurityException

Aus diesem Grund müssen Sie bestätigen, dass die erforderlichen Voraussetzungen erfüllt sind. bevor Sie einen Dienst im Vordergrund starten. Der Dienst im Vordergrund type-Dokumentation werden die erforderlichen Voraussetzungen für jeden Typ von Diensten im Vordergrund aufgeführt.

Dienst im Vordergrund starten

Bevor Sie das System auffordern, einen Dienst als Dienst im Vordergrund auszuführen, starten Sie den Dienst selbst:

val intent = Intent(...) // Build the intent for the service
context.startForegroundService(intent)

Context context = getApplicationContext();
Intent intent = new Intent(...); // Build the intent for the service
context.startForegroundService(intent);

Innerhalb des Dienstes, normalerweise in onStartCommand(), können Sie dass Ihr Dienst im Vordergrund ausgeführt wird. Rufen Sie dazu unter ServiceCompat.startForeground() (verfügbar ab Androidx-Core-Version 1.12). Diese Methode verwendet Parameter:

• Dienst
• Eine positive Ganzzahl, die die Benachrichtigung in der Statusleiste eindeutig identifiziert
• Das Objekt Notification selbst
• Die Typen von Diensten im Vordergrund die vom Dienst geleistete Arbeit

Diese Typen können eine Teilmenge der im Manifest deklarierten Typen sein. je nach Anwendungsfall. Wenn Sie weitere Diensttypen hinzufügen möchten, können Sie noch einmal startForeground() anrufen.

Angenommen, eine Fitness-App betreibt einen Lauf-Tracker-Dienst, der immer benötigt location-Informationen, muss aber möglicherweise keine Medien wiedergeben. Ich müssen im Manifest sowohl location als auch mediaPlayback deklarieren. Wenn ein Nutzer startet einen Lauf und möchte nur, dass ihr Standort erfasst wird. Ihre App sollte dann startForeground() und nur die Berechtigung ACCESS_FINE_LOCATION übergeben. Gehen Sie dann so vor: Wenn der Nutzer die Audiowiedergabe starten möchte, ruf noch einmal startForeground() auf und die bitweise Kombination aller Typen von Diensten im Vordergrund (in diesem Fall ACCESS_FINE_LOCATION|FOREGROUND_SERVICE_MEDIA_PLAYBACK).

Hier ist ein Beispiel, wie ein Kamera- Vordergrunddienst gestartet wird:

class MyCameraService: Service() {

  private fun startForeground() {
    // Before starting the service as foreground check that the app has the
    // appropriate runtime permissions. In this case, verify that the user has
    // granted the CAMERA permission.
    val cameraPermission =
            PermissionChecker.checkSelfPermission(this, Manifest.permission.CAMERA)
    if (cameraPermission != PermissionChecker.PERMISSION_GRANTED) {
        // Without camera permissions the service cannot run in the foreground
        // Consider informing user or updating your app UI if visible.
        stopSelf()
        return
    }

    try {
        val notification = NotificationCompat.Builder(this, "CHANNEL_ID")
            // Create the notification to display while the service is running
            .build()
        ServiceCompat.startForeground(
            /* service = */ this,
            /* id = */ 100, // Cannot be 0
            /* notification = */ notification,
            /* foregroundServiceType = */
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
                ServiceInfo.FOREGROUND_SERVICE_TYPE_CAMERA
            } else {
                0
            },
        )
    } catch (e: Exception) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S
                && e is ForegroundServiceStartNotAllowedException) {
            // App not in a valid state to start foreground service
            // (e.g. started from bg)
        }
        // ...
    }
  }
}

public class MyCameraService extends Service {

    private void startForeground() {
        // Before starting the service as foreground check that the app has the
        // appropriate runtime permissions. In this case, verify that the user
        // has granted the CAMERA permission.
        int cameraPermission =
            ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA);
        if (cameraPermission == PackageManager.PERMISSION_DENIED) {
            // Without camera permissions the service cannot run in the
            // foreground. Consider informing user or updating your app UI if
            // visible.
            stopSelf();
            return;
        }

        try {
            Notification notification =
                new NotificationCompat.Builder(this, "CHANNEL_ID")
                    // Create the notification to display while the service
                    // is running
                    .build();
            int type = 0;
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
                type = ServiceInfo.FOREGROUND_SERVICE_TYPE_CAMERA;
            }
            ServiceCompat.startForeground(
                    /* service = */ this,
                    /* id = */ 100, // Cannot be 0
                    /* notification = */ notification,
                    /* foregroundServiceType = */ type
            );
        } catch (Exception e) {
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S &&
                    e instanceof ForegroundServiceStartNotAllowedException
            ) {
                // App not in a valid state to start foreground service
                // (e.g started from bg)
            }
            // ...
        }
    }

    //...
}

Dienst aus dem Vordergrund entfernen

Rufen Sie zum Entfernen des Dienstes aus dem Vordergrund Folgendes auf: stopForeground() Diese Methode verwendet einen booleschen Wert, der angibt, ob die Statusleiste entfernt werden soll Benachrichtigungen an. Beachten Sie, dass der Dienst weiterhin ausgeführt wird.

Wenn Sie den Dienst beenden, während er im Vordergrund ausgeführt wird, wird die entsprechende Benachrichtigung wird entfernt.

Vom Nutzer initiiertes Beenden von Apps verarbeiten, in denen Dienste im Vordergrund ausgeführt werden

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

Ab Android 13 (API-Level 33) können Nutzer einen Workflow über die Benachrichtigungsleiste eine App mit laufenden Diensten im Vordergrund unabhängig von der SDK-Zielversion. Dieses Angebot, das sogenannte Task-Manager, zeigt eine Liste der Apps an, derzeit ein Dienst im Vordergrund ausgeführt wird.

Diese Liste heißt Aktive Apps. Neben jeder App befindet sich die Schaltfläche Beenden. Abbildung 1 veranschaulicht die Task-Manager-Workflow auf einem Gerät, das ausgeführt wird Android 13.

Wenn der Nutzer auf die Schaltfläche Stopp neben Ihrer App in der Task-Manager führen, werden die folgenden Aktionen ausgeführt:

• Ihre App wird vom System aus dem Arbeitsspeicher entfernt. Daher wird die gesamte App gestoppt, nicht nur den ausgeführten Dienst im Vordergrund.
• Das System entfernt den Aktivitäten-Back-Stack Ihrer App.
• Die Medienwiedergabe wird beendet.
• Die mit dem Dienst im Vordergrund verknüpfte Benachrichtigung wird entfernt.
• Deine App bleibt im Verlauf.
• Geplante Jobs werden zum geplanten Zeitpunkt ausgeführt.
• Der Wecker wird zur festgelegten Zeit oder im festgelegten Zeitfenster gestellt.

Um zu testen, ob sich Ihre App wie erwartet verhält, während und nachdem ein Nutzer Ihre App beendet hat -App, führen Sie den folgenden ADB-Befehl in einem Terminalfenster aus:

adb shell cmd activity stop-app PACKAGE_NAME

Ausnahmen

Für bestimmte App-Typen gibt es mehrere Ausnahmestufen: die in den folgenden Abschnitten beschrieben werden.

Ausnahmen gelten pro Anwendung, nicht pro Prozess. Wenn das System einen Prozess in einem sind alle anderen Prozesse in der App ebenfalls ausgenommen.

Ausnahmen von der Anzeige im Task-Manager

Die folgenden Apps können einen Dienst im Vordergrund ausführen und werden nicht in der Task-Manager:

• Apps auf Systemebene
• Sicherheits-Apps also Apps mit der Rolle ROLE_EMERGENCY
• Geräte in diesem Demomodus

Ausnahmen, die nicht von Nutzern aufgehalten werden können

Wenn die folgenden App-Typen einen Dienst im Vordergrund ausführen, werden sie in der Task-Manager, aber es gibt keine Schaltfläche Stopp neben dem App-Namen, auf den der Nutzer tippen kann:

• Apps von Geräteeigentümern
• Profilinhaber Apps
• Dauerhafte Apps
• Apps mit der Rolle ROLE_DIALER

Für viele Anwendungsfälle gibt es Plattform- oder Jetpack-APIs, die Sie für die Arbeit nutzen können für die Sie normalerweise einen Dienst im Vordergrund verwenden. Wenn es eine geeignete zweckgebundene API verwenden, sollten Sie diese fast immer anstelle eines Vordergrunds verwenden, . Speziell entwickelte APIs bieten oft zusätzliche anwendungsfallspezifische die Sie sonst selbst aufbauen müssten. Beispiel: verarbeitet die Bubbles API die komplexe UI-Logik für Messaging-Apps, die Chat-Bubble-Funktionen implementieren müssen.

In der Dokumentation für die Typen von Diensten im Vordergrund als Alternative zu Diensten im Vordergrund.

Einschränkungen beim Starten eines Dienstes im Vordergrund aus dem Hintergrund

Apps, die auf Android 12 oder höher ausgerichtet sind, können keinen Vordergrund starten ausgeführt werden, während die App im Hintergrund ausgeführt wird. Hiervon ausgenommen sind einige spezielle Cases. Wenn eine App versucht, Dienst im Vordergrund, während die App im Hintergrund ausgeführt wird, einen dieser Ausnahmefälle nicht erfüllt, wirft das System eine ForegroundServiceStartNotAllowedException

Wenn eine App einen Dienst im Vordergrund starten möchte, Berechtigungen für während der Verwendung, z. B. für Körpersensoren, Kamera, Mikrofon oder Standort Berechtigungen enthält, kann der Dienst nicht erstellt werden, während die App im Hintergrund ausgeführt wird. auch wenn die App unter eine der Ausnahmen vom Hintergrundstart fällt. Einschränkungen. Der Grund hierfür wird im Abschnitt Einschränkungen für Starten von Diensten im Vordergrund, die während der Nutzung benötigt werden Berechtigungen

Ausnahmen von Einschränkungen beim Starten des Hintergrunds

In den folgenden Situationen kann Ihre App Dienste im Vordergrund starten, auch wenn Ihre App im Hintergrund ausgeführt wird:

• Ihre App wechselt aus einem für den Nutzer sichtbaren Zustand, z. B. activity sein.
• Ihre App kann eine Aktivität über das Hintergrund, es sei denn, bei denen die App eine Aktivität im Back-Stack einer vorhandenen Aufgabe hat.

• Ihre App erhält eine Nachricht mit hoher Priorität über Firebase Cloud Nachrichten:

• Der Nutzer führt eine Aktion für ein UI-Element aus, das sich auf Ihre App bezieht. Beispiel: interagieren sie möglicherweise mit einer Blase, Benachrichtigung, Widget oder Aktivität.

• Deine App löst einen genauen Alarm aus, um eine vom Nutzer angeforderte Aktion ausführen.

• Ihre App ist der aktuelle Eingang des Geräts .

• Deine App empfängt ein Ereignis im Zusammenhang mit Geofencing oder Aktivitäten Übergang zur Erkennung.

• Nachdem das Gerät neu gestartet und die ACTION_BOOT_COMPLETED, ACTION_LOCKED_BOOT_COMPLETED, oder ACTION_MY_PACKAGE_REPLACED Intent-Aktion an einem Broadcast-Empfänger ausführen.

• Deine App erhält die ACTION_TIMEZONE_CHANGED, ACTION_TIME_CHANGED, oder ACTION_LOCALE_CHANGED Intent-Aktion an einen Broadcast-Empfänger.

• Deine App erhält die ACTION_TRANSACTION_DETECTED Termin von NfcService.

• Apps mit bestimmten Systemrollen oder Berechtigungen, z. B. Gerät Inhaber und Profil Inhaber.

• Ihre App verwendet den Companion-Geräte-Manager und deklariert die REQUEST_COMPANION_START_FOREGROUND_SERVICES_FROM_BACKGROUND oder die REQUEST_COMPANION_RUN_IN_BACKGROUND Berechtigung. Verwenden Sie nach Möglichkeit REQUEST_COMPANION_START_FOREGROUND_SERVICES_FROM_BACKGROUND

• Ihre App enthält die SYSTEM_ALERT_WINDOW Berechtigung.

• Der Nutzer deaktiviert die Akkuoptimierungen für Ihre App.

Einschränkungen beim Starten von Diensten im Vordergrund, für die Berechtigungen während der Nutzung erforderlich sind

Unter Android 14 (API-Level 34) oder höher sind besondere Situationen zu beachten. ob Sie einen Dienst im Vordergrund starten, für den während der Nutzung Berechtigungen erforderlich sind.

Wenn deine App auf Android 14 oder höher ausgerichtet ist, wenn Sie einen Dienst im Vordergrund erstellen, um sicherzugehen, dass Ihre App alle die entsprechenden Berechtigungen für diesen Diensttyp haben. Wenn Sie beispielsweise eine Dienst im Vordergrund des Typs Mikrofon, dem bestätigt das System, dass Ihre App RECORD_AUDIO Berechtigung. Wenn Sie diese Berechtigung nicht haben, gibt das System eine SecurityException

Bei Berechtigungen, die gerade verwendet werden, verursacht dies ein potenzielles Problem. Wenn Ihre App eine „Während der Nutzung“ gewährt sie nur diese Berechtigung, solange es sich im Vordergrund. Das heißt, wenn sich Ihre App im Hintergrund befindet und versucht, einem Dienst im Vordergrund vom Typ „Kamera“, „Standort“ oder „Mikrofon“, dass Ihre App derzeit nicht die erforderlichen Berechtigungen hat, und Sie SecurityException

Wenn sich Ihre App im Hintergrund befindet und eine Gesundheitsdienst, der die Berechtigung BODY_SENSORS_BACKGROUND benötigt, die App verfügt derzeit nicht über diese Berechtigung und das System gibt eine Ausnahme aus. Dies trifft nicht zu, wenn es sich um einen Gesundheitsdienst handelt, wie ACTIVITY_RECOGNITION. PermissionChecker.checkSelfPermission() verhindert dieses Problem nicht. Ob Ihre App während der Nutzung eine Berechtigung hat und Sie ruft checkSelfPermission() auf, um zu prüfen, ob sie diese Berechtigung hat. Die Methode gibt PERMISSION_GRANTED zurück, auch wenn die App im Hintergrund ausgeführt wird. Wenn der Parameter gibt PERMISSION_GRANTED zurück, was bedeutet, dass deine App diese Berechtigung hat während die App verwendet wird.“

Wenn also für Ihren Dienst im Vordergrund eine Berechtigung während der Nutzung erforderlich ist, muss Context.startForegroundService() oder Context.bindService() aufrufen, während Ihre App eine sichtbare Aktivität aufweist, es sei denn, der Dienst fällt in eine der ausgenommene Ausnahmen.

In einigen Situationen kann selbst dann, wenn während der App ein Dienst im Vordergrund gestartet wird, Läufe im Hintergrund ausgeführt werden, kann das Gerät weiterhin auf den Standort zugreifen, Kamera- und Mikrofoninformationen, während die App im Vordergrund ausgeführt wird („während der Nutzung“).

Wenn der Dienst in diesen Fällen ein Typ des Diensts im Vordergrund von location ist und von einer App gestartet wird, die hat die ACCESS_BACKGROUND_LOCATION kann dieser Dienst jederzeit auf Standortinformationen zugreifen, auch wenn die App im Hintergrund ausgeführt wird.

Diese Situationen sind in der folgenden Liste aufgeführt:

• Eine Systemkomponente startet den Dienst.
• Der Dienst beginnt, indem er mit der App interagiert. Widgets.
• Der Dienst beginnt mit einer Benachrichtigung.
• Der Dienst beginnt als PendingIntent, das von einem eine andere, sichtbare App.
• Der Dienst beginnt mit einer App, die eine Geräterichtlinie ist Controller, der im Modus „Geräteinhaber“ ausgeführt wird.
• Der Dienst beginnt von einer App, die die VoiceInteractionService bereitstellt.
• Der Dienst beginnt mit einer App, die über START_ACTIVITIES_FROM_BACKGROUND privilegierte Berechtigung.

Ermitteln, welche Dienste in Ihrer Anwendung betroffen sind

Starten Sie beim Testen Ihrer App die Dienste im Vordergrund. Wenn ein gestarteter Dienst eingeschränkter Zugriff auf Standort, Mikrofon und Kamera, die folgende Meldung erscheint in Logcat:

Foreground service started from background can not have \
location/camera/microphone access: service SERVICE_NAME