Laufende Aktivitäten anzeigen

Wear OS-Geräte werden häufig für lang andauernde Aktivitäten wie das Aufzeichnen eines Trainings verwendet. Das ist ein Problem für die Nutzerfreundlichkeit: Wenn ein Nutzer eine Aufgabe startet und dann zum Zifferblatt zurückkehrt, wie kommt er dann wieder zurück? Die Rückkehr zur App über den Launcher kann schwierig sein, insbesondere unterwegs, was unnötige Probleme verursacht.

Die Lösung besteht darin, eine Benachrichtigung über laufende Aktivitäten mit einem OngoingActivity zu verknüpfen. So kann das Gerät Informationen zur lang andauernden Aktivität in der gesamten Benutzeroberfläche anzeigen und Funktionen wie das tippable Symbol unten auf dem Zifferblatt ermöglichen. So werden Nutzer über die Hintergrundaufgabe informiert und können mit nur einem Tippen zur App zurückkehren.

Durch eine laufende Aktivität bleibt deine App auch länger sichtbar und das System kehrt nach einer gewissen Zeit der Inaktivität nicht zum Zifferblatt zurück. Weitere Informationen finden Sie unter App auf Wear sichtbar halten.

In dieser Trainings-App können die Informationen beispielsweise auf dem Zifferblatt des Nutzers als tippable Laufsymbol angezeigt werden:

Abbildung 1. Aktivitätsanzeige.

Eine Benachrichtigung über laufende Aktivitäten zeigt auch Informationen im Bereich Letzte des globalen App-Launchers an. So haben Nutzer eine weitere praktische Möglichkeit, den Status ihrer Aufgabe zu sehen und die App wieder zu verwenden:

Abbildung 2: Globaler Launcher

Die folgenden Situationen eignen sich gut für die Verwendung einer Benachrichtigung über laufende Aktivitäten, die mit einer laufenden Aktivität verknüpft ist:

Abbildung 3: Timer:Zählt die Zeit aktiv herunter und endet, wenn der Timer pausiert oder beendet wird.

Abbildung 4: Detaillierte Routenführung:Ansage von Wegbeschreibungen zu einem Ziel. Wird beendet, wenn der Nutzer das Ziel erreicht oder die Navigation beendet.

Abbildung 5: Medien:Spielt während einer Sitzung Musik ab. Endet sofort, nachdem der Nutzer die Sitzung pausiert hat.

Wear erstellt laufende Aktivitäten automatisch für Media-Apps.

Im Codelab für laufende Aktivitäten finden Sie ein ausführliches Beispiel für das Erstellen laufender Aktivitäten für andere Arten von Apps.

Einrichtung

Wenn Sie die Ongoing Activity API in Ihrer App verwenden möchten, fügen Sie der Datei build.gradle Ihrer App die folgenden Abhängigkeiten hinzu:

dependencies {
  implementation "androidx.wear:wear-ongoing:1.1.0"
  implementation "androidx.core:core:1.18.0"
}

Laufende Aktivität erstellen

Der Prozess umfasst drei Schritte:

1. Erstellen Sie eine Standard-NotificationCompat.Builder und konfigurieren Sie sie als fortlaufend.
2. Erstellen und konfigurieren Sie ein OngoingActivity-Objekt und übergeben Sie den Notification.Builder daran.
3. Wende die laufende Aktivität auf den Benachrichtigungs-Builder an und sende die resultierende Benachrichtigung.

Benachrichtigung erstellen und konfigurieren

Erstellen Sie zuerst eine NotificationCompat.Builder. Der entscheidende Schritt ist der Aufruf von setOngoing(true), um die Benachrichtigung als Benachrichtigung über laufende Aktivitäten zu markieren. Sie können in dieser Phase auch andere Benachrichtigungseigenschaften festlegen, z. B. das kleine Symbol und die Kategorie.

// Create a PendingIntent to pass to the notification builder
val pendingIntent =
    PendingIntent.getActivity(
        this,
        0,
        Intent(this, AlwaysOnActivity::class.java).apply {
            flags = Intent.FLAG_ACTIVITY_SINGLE_TOP
        },
        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
    )

val notificationBuilder = NotificationCompat.Builder(this, CHANNEL_ID)
    .setContentTitle("Always On Service")
    .setContentText("Service is running in background")
    .setSmallIcon(R.drawable.animated_walk)
    // Category helps the system prioritize the ongoing activity
    .setCategory(NotificationCompat.CATEGORY_WORKOUT)
    .setContentIntent(pendingIntent)
    .setVisibility(NotificationCompat.VISIBILITY_PUBLIC)
    .setOngoing(true) // Important!
AlwaysOnService.kt

OngoingActivity erstellen

Erstellen Sie als Nächstes eine Instanz von OngoingActivity mit dem Builder. Für OngoingActivity.Builder sind eine Context, eine Benachrichtigungs-ID und die NotificationCompat.Builder erforderlich, die Sie im vorherigen Schritt erstellt haben.

Konfigurieren Sie die wichtigsten Attribute, die auf den neuen UI-Oberflächen angezeigt werden sollen:

• Animierte und statische Symbole: Geben Sie Symbole an, die im aktiven und im Inaktivmodus auf dem Zifferblatt angezeigt werden.
• Touch-Intent: Ein PendingIntent, der den Nutzer zu Ihrer App zurückbringt, wenn er auf das Symbol für laufende Aktivitäten tippt. Sie können die im vorherigen Schritt erstellte pendingIndent wiederverwenden.

val ongoingActivity =
    OngoingActivity.Builder(applicationContext, NOTIFICATION_ID, notificationBuilder)
        // Sets the icon that appears on the watch face in active mode.
        .setAnimatedIcon(R.drawable.animated_walk)
        // Sets the icon that appears on the watch face in ambient mode.
        .setStaticIcon(R.drawable.ic_walk)
        // Sets the tap target to bring the user back to the app.
        .setTouchIntent(pendingIntent)
        .build()
AlwaysOnService.kt

Auf die Benachrichtigung und den Beitrag anwenden

Im letzten Schritt verknüpfen Sie die OngoingActivity mit der Benachrichtigung und posten sie. Bei der Methode ongoingActivity.apply() wird der ursprüngliche Benachrichtigungs-Builder geändert und die erforderlichen Daten werden hinzugefügt, damit das System die Benachrichtigung auf den zusätzlichen Oberflächen anzeigen kann. Danach können Sie die Benachrichtigung wie gewohnt erstellen und posten.

// This call modifies notificationBuilder to include the ongoing activity data.
ongoingActivity.apply(applicationContext)

// Post the notification.
startForeground(NOTIFICATION_ID, notificationBuilder.build())
AlwaysOnService.kt

Dynamischen Statustext zum Launcher hinzufügen

Mit dem obigen Code wird dem Zifferblatt das antippbare Symbol hinzugefügt. Wenn Sie noch umfangreichere Echtzeit-Updates im Bereich Zuletzt verwendet des Launchers bereitstellen möchten, erstellen Sie ein Status-Objekt und hängen Sie es an Ihr OngoingActivity an. Wenn Sie keinen benutzerdefinierten Status angeben, wird standardmäßig der Inhaltstext der Benachrichtigung verwendet (mit setContentText() festgelegt). Wenn Sie dynamischen Text anzeigen möchten, verwenden Sie einen Status.Builder. Sie können einen Vorlagenstring mit Platzhaltern definieren und Status.Part-Objekte bereitstellen, um diese Platzhalter zu füllen. Die Status.Part kann dynamisch sein, z. B. eine Stoppuhr oder ein Timer.

Das folgende Beispiel zeigt, wie Sie einen Status erstellen, in dem „Laufen für [Stoppuhr]“ angezeigt wird:

// Define a template with placeholders for the activity type and the timer.
val statusTemplate = "#type# for #time#"

// Set the start time for a stopwatch.
// Use SystemClock.elapsedRealtime() for time-based parts.
val runStartTime = SystemClock.elapsedRealtime()

val ongoingActivityStatus = Status.Builder()
    // Sets the template string.
    .addTemplate(statusTemplate)
    // Fills the #type# placeholder with a static text part.
    .addPart("type", Status.TextPart("Run"))
    // Fills the #time# placeholder with a stopwatch part.
    .addPart("time", Status.StopwatchPart(runStartTime))
    .build()
AlwaysOnService.kt

Verknüpfen Sie schließlich diese Status mit Ihrer OngoingActivity, indem Sie setStatus() auf der OngoingActivity.Builder aufrufen.

val ongoingActivity =
    OngoingActivity.Builder(applicationContext, NOTIFICATION_ID, notificationBuilder)
        // ...
        // Add the status to the OngoingActivity.
        .setStatus(ongoingActivityStatus)
        .build()
AlwaysOnService.kt

Zusätzliche Anpassungen

Neben Status können Sie Ihre laufende Aktivität oder Benachrichtigungen auf folgende Weise anpassen. Je nach Implementierung des OEM werden diese Anpassungen jedoch möglicherweise nicht verwendet.

Laufende Benachrichtigung

• Die festgelegte Kategorie bestimmt die Priorität der laufenden Aktivität.
  • CATEGORY_CALL:ein eingehender Sprach- oder Videoanruf oder eine ähnliche synchrone Kommunikationsanfrage
  • CATEGORY_NAVIGATION:eine Karte oder eine detaillierte Routenführung
  • CATEGORY_TRANSPORT:Steuerung des Medientransports für die Wiedergabe
  • CATEGORY_ALARM:Wecker oder Timer
  • CATEGORY_WORKOUT:ein Workout
  • CATEGORY_LOCATION_SHARING: Kategorie für temporäre Standortfreigabe
  • CATEGORY_STOPWATCH:Stoppuhr

Laufende Aktivität

• Animiertes Symbol:ein Schwarz-Weiß-Vektor, vorzugsweise mit transparentem Hintergrund. Wird auf dem Zifferblatt im Aktivmodus angezeigt. Wenn das animierte Symbol nicht angegeben ist, wird das Standardbenachrichtigungssymbol verwendet. Das Standardsymbol für Benachrichtigungen ist für jede Anwendung unterschiedlich.

• Statisches Symbol:Ein Vektorsymbol mit transparentem Hintergrund. Wird im Inaktivmodus auf dem Zifferblatt angezeigt. Wenn das animierte Symbol nicht festgelegt ist, wird das statische Symbol im Aktivmodus auf dem Zifferblatt verwendet. Wenn nichts angegeben ist, wird das Benachrichtigungssymbol verwendet. Wenn keines von beiden festgelegt ist, wird eine Ausnahme ausgelöst. (Im App-Launcher wird weiterhin das App-Symbol verwendet.)

• OngoingActivityStatus:Nur Text oder ein Chronometer. Wird im App Launcher im Bereich Zuletzt verwendet angezeigt. Wenn nichts angegeben ist, wird der Kontexttext der Benachrichtigung verwendet.

• Touch-Intent:Ein PendingIntent, der verwendet wird, um zur App zurückzukehren, wenn der Nutzer auf das Symbol für laufende Aktivitäten tippt. Wird auf dem Zifferblatt oder im Launcher-Element angezeigt. Sie kann sich von der ursprünglichen Absicht unterscheiden, mit der die App gestartet wurde. Wenn sie nicht angegeben ist, wird die Inhaltsabsicht der Benachrichtigung verwendet. Wenn keines der beiden festgelegt ist, wird eine Ausnahme ausgelöst.

• LocusId:ID, die der Launcher-Verknüpfung zugewiesen wird, der die laufende Aktivität entspricht. Wird im Launcher im Bereich Letzte angezeigt, während die Aktivität läuft. Wenn nicht angegeben, werden im Launcher alle App-Elemente im Bereich Letzte Aktivitäten aus demselben Paket ausgeblendet und nur die laufende Aktivität wird angezeigt.

• ID der laufenden Aktivität:ID, die verwendet wird, um Aufrufe von fromExistingOngoingActivity() zu disambiguieren, wenn eine Anwendung mehrere laufende Aktivitäten hat.

Laufende Aktivität aktualisieren

Sie sollten die laufende Aktivität für die vorhandene Benachrichtigung aktualisieren, wenn Sie den Status ändern müssen, anstatt eine neue Benachrichtigung und laufende Aktivität zu erstellen. Wenn Sie die laufende Aktivität und die gepostete Benachrichtigung aktualisieren möchten, verwenden Sie das zuvor erstellte Objekt und rufen Sie update() auf, wie im folgenden Beispiel gezeigt:

ongoingActivity.update(context, newStatus)
AlwaysOnService.kt

In den Fällen, in denen es nicht möglich ist, einen Verweis auf die laufende Aktivität zu speichern, gibt es eine statische Methode zum Abrufen der laufenden Aktivität. Das ist jedoch weniger empfehlenswert:

OngoingActivity.recoverOngoingActivity(context)
    ?.update(context, newStatus)
AlwaysOnService.kt

Laufende Aktivität beenden

Wenn die App als laufende Aktivität beendet wird, muss nur die Benachrichtigung über laufende Aktivitäten abgebrochen werden.

Sie können die Benachrichtigung oder die laufende Aktivität auch abbrechen, wenn sie in den Vordergrund kommt, und sie dann neu erstellen, wenn sie wieder in den Hintergrund geht. Das ist jedoch nicht erforderlich.

Laufende Aktivität pausieren

Wenn Ihre App eine explizite Stoppaktion hat, setzen Sie die laufende Aktivität fort, nachdem sie entpausiert wurde. Bei einer App ohne explizite Stoppaktion beenden Sie die Aktivität, wenn sie pausiert wird.

Wichtige Überlegungen

Beachten Sie bei der Arbeit mit der Ongoing Activity API Folgendes:

• Legen Sie ein statisches Symbol für Ihre laufende Aktivität fest, entweder explizit oder als Fallback über die Benachrichtigung. Andernfalls erhalten Sie eine IllegalArgumentException.

• Verwenden Sie schwarz-weiße Vektorsymbole mit transparentem Hintergrund.

• Legen Sie für Ihre laufende Aktivität entweder explizit oder als Fallback über die Benachrichtigung eine Touch-Intention fest. Andernfalls erhalten Sie eine IllegalArgumentException.

• Wenn in der Manifestdatei Ihrer App mehr als eine MAIN LAUNCHER-Aktivität deklariert ist, veröffentlichen Sie eine dynamische Verknüpfung und verknüpfen Sie sie mit Ihrer laufenden Aktivität über LocusId.

Media-Benachrichtigungen bei der Wiedergabe von Medien auf Wear OS-Geräten veröffentlichen

Wenn auf einem Wear OS-Gerät Medieninhalte wiedergegeben werden, veröffentlichen Sie eine Medienbenachrichtigung. So kann das System die entsprechende laufende Aktivität erstellen.

Wenn Sie Media3 verwenden, wird die Benachrichtigung automatisch veröffentlicht. Wenn Sie die Benachrichtigung manuell erstellen, sollte sie MediaStyleNotificationHelper.MediaStyle verwenden und die entsprechende MediaSession sollte die Sitzungsaktivität enthalten.