Live-Updates für Android

Pushwoosh unterstützt Android Live-Updates über das Modul pushwoosh-liveupdates (SDK 6.9.0 und höher). Ein Live-Update ist eine fortlaufende Benachrichtigung im Fortschrittsstil, die das System auf dem Sperrbildschirm, in der Benachrichtigungsschublade und als Status-Chip in der Statusleiste hervorhebt, sodass Benutzer eine Aktivität verfolgen können, ohne Ihre App zu öffnen.

Der gesamte Lebenszyklus wird vom Server gesteuert: Ihr Backend sendet einen Push, wenn die Aktivität beginnt, weitere Pushes, während sie fortschreitet, und einen letzten Push, wenn sie endet. Das SDK rendert jeden einzelnen automatisch.

Was sind Live-Updates

Live-Updates wurden in Android 16 (API 36) eingeführt, um eine vom Benutzer initiierte, zeitkritische Aktivität von Anfang bis Ende anzuzeigen. Sie bauen auf den fortschrittsorientierten Benachrichtigungen der Plattform und der Notification.ProgressStyle-API auf. Konzeptionell sind sie das Android-Gegenstück zu den iOS Live Activities.

Diese Seite behandelt nur die Pushwoosh-Integration. Informationen zum Plattformverhalten, zu den Regeln für die Hervorhebung und zu Designrichtlinien finden Sie in der offiziellen Android-Dokumentation:

• Fortschrittsorientierte Benachrichtigungen
• Live-Update-Benachrichtigungen erstellen (Views)
• Live-Update-Benachrichtigungen erstellen (Compose)

Wann sollten Live-Updates verwendet werden

Live-Updates sind für eine Aktivität gedacht, die fortlaufend, vom Benutzer initiiert und zeitkritisch ist – etwas mit einem klaren Anfang und Ende, das dem Benutzer im Moment aktiv wichtig ist. Typische Szenarien für Pushwoosh-Kunden:

• Essenslieferung – Bestellung angenommen, wird vorbereitet, wird geliefert, kommt an.
• Fahrdienste und Taxi – Fahrer zugewiesen, auf dem Weg, kommt an, Fahrt läuft.
• Bestell- und Sendungsverfolgung – Live-Status einer Bestellung, die sich aktiv im Transit befindet.
• Live-Sport und Medien – Spielstand und Zeit, während das Spiel läuft.
• Fitness – ein aktives Training oder ein Lauf mit verstrichener Zeit und Fortschritt.
• Fintech – ein Transaktions- oder Verifizierungsprozess, der seine Phasen durchläuft.

Da der Lebenszyklus von realen Ereignissen gesteuert wird, die Ihr Backend bereits kennt (eine Bestellung ändert ihren Status, ein Kurier bewegt sich), ist ein Live-Update in der Regel ein API-Aufruf, der in Ihren bestehenden Ereignisfluss integriert ist – nicht etwas, das eine Person von Hand sendet.

Vorsicht

Verwenden Sie Live-Updates nicht für Werbeaktionen, Chat-Nachrichten oder allgemeine Informationen und posten Sie niemals ein Live-Update erneut, das der Benutzer geschlossen hat. Android kann der App die Fähigkeit entziehen, hervorgehobene Benachrichtigungen zu posten. Befolgen Sie die Android-Anleitung zur angemessenen Verwendung.

Anforderungen

• Android 16 (API 36) oder neuer. Auf älteren Geräten bleibt das Modul inaktiv und jeder Live-Update-API-Aufruf ist eine sichere No-Op.
• Pushwoosh Android SDK 6.9.0 oder höher.

Das Modul pushwoosh-liveupdates hinzufügen

Fügen Sie die Abhängigkeit zu Ihrer app/build.gradle hinzu:

dependencies {
    implementation 'com.pushwoosh:pushwoosh-liveupdates:<latest-version>'
}

Ersetzen Sie <latest-version> durch die aktuelle Version von Maven Central.

Das Modul wird beim Start automatisch erkannt. Es deklariert die erforderliche Berechtigung POST_PROMOTED_NOTIFICATIONS, registriert seinen eigenen Benachrichtigungskanal und fängt Live-Update-Pushes vor dem Standard-Benachrichtigungspfad ab. Es ist kein zusätzlicher Initialisierungscode erforderlich – das SDK setzt die Flags für fortlaufende und hervorgehobene Benachrichtigungen, lädt das große Symbol herunter, ordnet Aktionsschaltflächen zu und postet die Benachrichtigung für Sie.

Ein Live-Update senden

Sie senden Live-Updates über die Messaging API v2, indem Sie Live-Update-Felder zum root_params-Objekt des android-Inhaltsblocks hinzufügen. Verwenden Sie eine transactional-Anfrage – ein Live-Update zielt auf den spezifischen Benutzer, dessen Aktivität es verfolgt. Das schedule-Feld ist erforderlich; { "after": "0s" } sendet sofort. Der Lebenszyklus hat drei Operationen, die in pw_live_op festgelegt werden:

• start – erster Push für eine Aktivität. Postet die fortlaufende Benachrichtigung.
• update – ein späterer Push für dieselbe Aktivität. Aktualisiert sie an Ort und Stelle, ohne Ton.
• end – abschließender Push. Schließt die Benachrichtigung.

Alle Pushes, die zur selben Aktivität gehören, müssen dieselbe pw_live_id haben. Diese ID verbindet die Updates miteinander und wird auch verwendet, um das Update aus der App zu schließen.

Jeder Push beschreibt die Benachrichtigung vollständig – es wird nichts vom vorherigen Push übernommen. Senden Sie bei jedem update jedes Feld, das Sie beibehalten möchten, wie z. B. die Segmente und das große Symbol, erneut; ein ausgelassenes Feld wird als nicht vorhanden gerendert.

Live-Update-Parameter

Diese Schlüssel gehören in das root_params-Objekt des android-Inhaltsblocks. Titel, Text und großes Symbol verwenden die Standard-Android-Push-Felder (title, body, custom_icon).

Parameter	Typ	Beschreibung
pw_live_op	string	Lebenszyklus-Operation: start, update oder end. Erforderlich.
pw_live_id	string	Stabile Aktivitäts-ID, die von allen Pushes eines Live-Updates geteilt wird. Erforderlich.
pw_live_progress	int	Fortschrittswert, gemessen an den summierten Segmentlängen.
pw_live_progress_indeterminate	bool	Zeigt eine unbestimmte Animation anstelle eines konkreten Wertes an.
pw_live_segments	JSON string	Geordnete Fortschrittssegmente, jeweils {"color": "#RRGGBB", "length": N}.
pw_live_extras	JSON string	Beliebige Daten, die an einen benutzerdefinierten Style-Provider übergeben werden.
pw_live_when	long	Zeitanker der Kopfzeile, in Epochen-Millisekunden.
pw_live_chronometer	bool	Zeigt die Kopfzeilenzeit als laufenden Timer an.
pw_live_chronometer_count_down	bool	Ein laufender Timer zählt rückwärts statt vorwärts.
pw_live_show_when	bool	Zeigt die Zeitspalte der Kopfzeile überhaupt an. Standard ist true.

Hinweis

Werte in root_params werden als Strings an das Gerät geliefert, daher müssen pw_live_segments und pw_live_extras als JSON-kodierte Strings übergeben werden, wie in den folgenden Beispielen gezeigt.

Die vier Zeitfelder kombinieren sich wie folgt: Wenn pw_live_show_when auf false gesetzt ist, wird die Zeit ausgeblendet; andernfalls ist pw_live_when der Anker, pw_live_chronometer verwandelt ihn in einen Live-Zähler und pw_live_chronometer_count_down lässt diesen Zähler rückwärts laufen.

Start-Push

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["ANDROID"],
      "users": { "list": ["customer-42"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "android": {
                "title": "Order #4521",
                "body": "We are preparing your order",
                "custom_icon": "https://example.com/restaurant.png",
                "root_params": {
                  "pw_live_op": "start",
                  "pw_live_id": "order_4521",
                  "pw_live_progress": "1",
                  "pw_live_segments": "[{\"color\":\"#34A853\",\"length\":3},{\"color\":\"#FBBC05\",\"length\":4},{\"color\":\"#4285F4\",\"length\":3}]",
                  "pw_live_extras": "{\"eta\":\"18:40\"}"
                }
              }
            }
          }
        }
      },
      "schedule": { "after": "0s" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL"
    }
  }'

Update-Push

Senden Sie ein update mit derselben pw_live_id, wann immer die Aktivität fortschreitet. Wiederholen Sie die Segmente und das Symbol – ein Update, das sie auslässt, wird ohne sie gerendert.

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["ANDROID"],
      "users": { "list": ["customer-42"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "android": {
                "title": "Order #4521",
                "body": "Your courier is on the way",
                "custom_icon": "https://example.com/restaurant.png",
                "root_params": {
                  "pw_live_op": "update",
                  "pw_live_id": "order_4521",
                  "pw_live_progress": "7",
                  "pw_live_segments": "[{\"color\":\"#34A853\",\"length\":3},{\"color\":\"#FBBC05\",\"length\":4},{\"color\":\"#4285F4\",\"length\":3}]"
                }
              }
            }
          }
        }
      },
      "schedule": { "after": "0s" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL"
    }
  }'

End-Push

Der abschließende Push benötigt nur die Operation und die ID.

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["ANDROID"],
      "users": { "list": ["customer-42"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "android": {
                "root_params": {
                  "pw_live_op": "end",
                  "pw_live_id": "order_4521"
                }
              }
            }
          }
        }
      },
      "schedule": { "after": "0s" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL"
    }
  }'

Das Erscheinungsbild anpassen

Das SDK liefert einen Standard-Fortschrittsstil, der aus pw_live_progress, pw_live_progress_indeterminate und pw_live_segments erstellt wird. Um die volle Kontrolle über die Fortschrittsleiste zu übernehmen, implementieren Sie LiveUpdateProgressStyleProvider und gestalten Sie selbst einen Notification.ProgressStyle.

Der Provider ist der einzige Anpassungspunkt. Das SDK ist weiterhin für die Kanaleinrichtung, die Flags für fortlaufende und hervorgehobene Benachrichtigungen, das große Symbol, die Aktionsschaltflächen und die Kopfzeilenzeit zuständig – ein benutzerdefinierter Provider kann nur die Fortschrittsleiste gestalten, sodass er die Berechtigung zur Hervorhebung nicht beeinträchtigen kann. Er muss zustandslos sein: Leiten Sie den zurückgegebenen Stil nur aus dem bereitgestellten LiveUpdateState ab. Wenn er eine Ausnahme auslöst, greift das SDK auf den Standardstil zurück und die Benachrichtigung wird trotzdem gepostet.

Java

import android.app.Notification;
import androidx.annotation.NonNull;
import com.pushwoosh.liveupdates.LiveUpdateProgressStyleProvider;
import com.pushwoosh.liveupdates.LiveUpdateSegment;
import com.pushwoosh.liveupdates.LiveUpdateState;
import java.util.List;

public class OrderStyleProvider implements LiveUpdateProgressStyleProvider {
    @NonNull
    @Override
    public Notification.ProgressStyle createStyle(@NonNull LiveUpdateState state) {
        Notification.ProgressStyle style = new Notification.ProgressStyle();
        if (state.getProgress() != null) {
            style.setProgress(state.getProgress());
        }
        style.setProgressIndeterminate(state.isProgressIndeterminate());

        List<LiveUpdateSegment> segments = state.getSegments();
        int boundary = 0;
        for (int i = 0; i < segments.size(); i++) {
            LiveUpdateSegment seg = segments.get(i);
            style.addProgressSegment(
                new Notification.ProgressStyle.Segment(seg.getLength()).setColor(seg.getColor()));
            boundary += seg.getLength();
            if (i < segments.size() - 1) {
                style.addProgressPoint(new Notification.ProgressStyle.Point(boundary));
            }
        }
        return style;
    }
}

Kotlin

import android.app.Notification
import com.pushwoosh.liveupdates.LiveUpdateProgressStyleProvider
import com.pushwoosh.liveupdates.LiveUpdateState

class OrderStyleProvider : LiveUpdateProgressStyleProvider {
    override fun createStyle(state: LiveUpdateState): Notification.ProgressStyle {
        val style = Notification.ProgressStyle()
        state.progress?.let { style.setProgress(it) }
        style.setProgressIndeterminate(state.isProgressIndeterminate)

        val segments = state.segments
        var boundary = 0
        segments.forEachIndexed { i, seg ->
            style.addProgressSegment(
                Notification.ProgressStyle.Segment(seg.length).setColor(seg.color))
            boundary += seg.length
            if (i < segments.size - 1) {
                style.addProgressPoint(Notification.ProgressStyle.Point(boundary))
            }
        }
        return style
    }
}

Registrieren Sie den Provider mit einem <meta-data>-Tag in der AndroidManifest.xml. Die Klasse muss einen öffentlichen, parameterlosen Konstruktor haben.

<meta-data
    android:name="com.pushwoosh.LIVE_UPDATE_STYLE_PROVIDER"
    android:value="com.example.OrderStyleProvider" />

Verwenden Sie LiveUpdateState.getExtras(), um das JSON zu lesen, das Sie in pw_live_extras gesendet haben, und passen Sie den Stil an Ihre eigenen Geschäftsdaten an.

Live-Updates aus Ihrer App verwalten

Der Server steuert jeden start, update und end, daher gibt es keine app-seitige API, um ein Live-Update zu posten oder zu aktualisieren. Die PushwooshLiveUpdates-Fassade deckt nur ab, was der Server nicht tun kann – ein Update lokal zu schließen und zu überprüfen, welche auf dem Bildschirm angezeigt werden.

import com.pushwoosh.liveupdates.PushwooshLiveUpdates;

// Ein bestimmtes Live-Update schließen, wenn der Benutzer die Aktivität in der App beendet,
// ohne auf den abschließenden "end"-Push des Servers zu warten
PushwooshLiveUpdates.endLiveUpdate("order_4521");

// Die Aktivitäts-IDs auflisten, die derzeit von dieser App angezeigt werden
List<String> active = PushwooshLiveUpdates.getActiveIds();

// Alles löschen, was diese App anzeigt, zum Beispiel beim Abmelden
PushwooshLiveUpdates.endAllLiveUpdates();

Alle Methoden können sicher von jedem Thread aus aufgerufen werden und sind auf Geräten unter Android 16 eine No-Op.

Verwandte Links

• Pushwoosh Android SDK Übersicht
• Pushwoosh Android SDK API-Referenz
• Messaging API
• Fortschrittsorientierte Benachrichtigungen für Android