iOS Live Activities API

Apple-Dokumentation:

• Über Live Activities
• Aktualisieren und Beenden von Live Activities mit ActivityKit-Push-Benachrichtigungen

Damit ein Customer Journey Live Activity-Punkt sein Content-State-Formular aus Feldnamen anstelle eines reinen JSON-Editors erstellen kann, veröffentlichen Sie ein Schema für Ihren attributes-type – siehe die Live Activity Schemas API.

startLiveActivity

POST https://api.pushwoosh.com/json/1.3/startLiveActivity

Ermöglicht das Erstellen von iOS Live Activities.

Request-Body

Parameter	Typ	Erforderlich/Optional	Beschreibung
application	String	Erforderlich	Pushwoosh-Anwendungscode
auth	String	Erforderlich	API-Zugriffstoken aus dem Pushwoosh Control Panel.
notifications	Array	Erforderlich	JSON-Array von Nachrichtenparametern. Details finden Sie in der nachstehenden Tabelle „Notifications“.

Notifications

Parameter, die im notifications-Array verwendet werden:

Parameter	Typ	Erforderlich/Optional	Beschreibung
content	String	Erforderlich*	Text der Benachrichtigung für den Push, der die Live Activity startet, und der Fallback-Text, der auf Geräten mit iOS-Versionen unter 16.1 angezeigt wird.
title	String	Erforderlich*	Titel der Benachrichtigung für den Push, der die Live Activity startet.
live_activity	Object	Erforderlich	Live Activity-Daten zum Erstellen einer Live Activity in iOS.
live_activity.content-state	Object	Erforderlich	Inhalt für die Live Activity-Benachrichtigung.
live_activity.attributes-type	String	Erforderlich	Der Typ der Attribute, die in der Live Activity verwendet werden.
live_activity.attributes	Object	Erforderlich	Attribute für die Live Activity.
live_activity_id	String	Erforderlich	Ein eindeutiger Bezeichner für die Live Activity. Wird verwendet, um diese Aktivität beim Aufruf von updateLiveActivity anzusprechen. Muss pro Aktivitätssitzung eindeutig sein.
filter	String	Optional	Der Name eines Pushwoosh-Filters (Segments). Siehe Segment- / Filtername. Die Live Activity wird auf allen Geräten gestartet, die diesem Filter entsprechen.
devices	Array von Strings	Optional	Eine Liste von Geräte-Tokens. Die Live Activity wird nur auf den angegebenen Geräten gestartet.
send_date	String	Optional	Plant den Push, der die Live Activity startet, für ein bestimmtes Datum und eine bestimmte Uhrzeit – funktioniert entweder mit filter- oder devices-Targeting. Verwenden Sie das Format YYYY-MM-DD HH:mm oder now, um sofort zu starten (dies ist auch der Standard, wenn der Parameter weggelassen wird). Darf nicht mehr als 1 Tag in der Vergangenheit oder 30 Tage in der Zukunft liegen, andernfalls wird die Anfrage mit einem Validierungsfehler abgelehnt.
timezone	String	Optional	Die Zeitzone, die zur Interpretation von send_date verwendet wird. Wenn weggelassen, wird send_date in UTC interpretiert.
apns_priority	Integer	Optional	Steuert die APNs-Zustellpriorität für diesen Live Activity-Push. Akzeptiert 10 (hohe Priorität, zugestellt mit dem apns-priority: 10-Header für sofortiges Rendern auf einem gesperrten Bildschirm) oder 5 (niedrige Priorität, zugestellt mit apns-priority: 5, um den Akku des Geräts zu schonen). Jeder andere Wert wird als 5 behandelt, ohne Validierungsfehler. Jeder Live Activity-Push hat standardmäßig die Priorität 5, unabhängig davon, ob er Benachrichtigungsinhalte (content/title) enthält – setzen Sie apns_priority: 10 explizit, um eine Zustellung mit hoher Priorität anzufordern. Siehe Zeitkritische Push-Benachrichtigungen und Zustellpriorität unten.

Hinweis: * Mindestens einer der Parameter content oder title muss nicht leer sein. Pushwoosh lehnt eine Startanfrage ab, bei der beide leer sind.

Vorsicht

Der Remote-Start einer Live Activity über startLiveActivity erfordert iOS 17.2+ auf dem Gerät – frühere Versionen unterstützen die pushToStartTokenUpdates-API nicht, auf die dieser Endpunkt angewiesen ist. Siehe Live Activity mit einer Remote-Push-Benachrichtigung starten.

Beim Targeting eines filter (Segments) ist die geplante Sendezeit der Zeitpunkt, zu dem Pushwoosh mit dem Versand des Pushs beginnt, nicht ein garantierter Zustellzeitpunkt – bei großen Zielgruppen kann die Zustellung an einzelne Geräte um einige Minuten hinter send_date zurückbleiben, da die Senderate für Live Activity-Pushs nicht mit send_rate angepasst werden kann.

Wiederholte Push-to-Start-Aufrufe werden stillschweigend erschöpft. Nach etwa zehn Starts in schneller Folge stellt Apple die Zustellung der zugrunde liegenden Push-to-Start-Benachrichtigung ohne Fehler ein, und startLiveActivity gibt weiterhin 200 zurück. Während des Kampagnentests sieht dies so aus, als ob „die API funktioniert, aber auf dem Gerät nichts passiert“. Planen Sie aufeinanderfolgende Teststarts mit etwas Abstand.

Request-Beispiel

Mit Filter

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "apns_priority": 10,
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "FIRST_LIVE_ACTIVITY",
        "filter": "FILTER_NAME_1"
      }
    ]
  }
}

Mit Geräten

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "apns_priority": 10,
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "SECOND_LIVE_ACTIVITY",
        "devices": ["first_third", "second_device"]
      }
    ]
  }
}

Geplanter Start

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "THIRD_LIVE_ACTIVITY",
        "filter": "FILTER_NAME_1",
        "send_date": "2026-06-16 16:00"
      }
    ]
  }
}

Response-Beispiel

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "Messages": [
      "XXXXX-XXXXXXXX-XXXXXXXX"
    ]
  }
}

Hinweis:

Lesen Sie diesen Artikel, um mehr über die Arbeit mit Live Activities mit dem Pushwoosh iOS SDK zu erfahren.

updateLiveActivity

POST https://api.pushwoosh.com/json/1.3/updateLiveActivity

Ermöglicht das Aktualisieren und Beenden von iOS Live Activities

Request-Body

Parameter	Typ	Erforderlich/Optional	Beschreibung
auth	String	Erforderlich	API-Zugriffstoken aus dem Pushwoosh Control Panel.
application	String	Erforderlich	Pushwoosh-Anwendungscode
notifications	Array	Erforderlich	JSON-Array von Nachrichtenparametern. Details finden Sie in der nachstehenden Tabelle „Notifications“.

Notifications

Parameter, die im notifications-Array verwendet werden:

Parameter	Typ	Erforderlich/Optional	Beschreibung
live_activity	Object	Erforderlich	Live Activity-Daten zum Aktualisieren einer Live Activity in iOS.
live_activity.event	String	Erforderlich	Gibt den Ereignistyp an. Verwenden Sie "update", um die Live Activity zu aktualisieren, oder "end", um sie zu schließen.
live_activity.content-state	Object	Erforderlich	Objekt mit Schlüssel-Wert-Paaren, das verwendet wird, um Daten an die Live Activity zu übergeben, um deren Inhalt zu aktualisieren.
live_activity.dismissal-date	Integer	Optional	Die Zeit (in Sekunden), zu der die Live Activity enden soll.
live_activity_id	String	Erforderlich	Der eindeutige Bezeichner der zu aktualisierenden Live Activity. Muss mit der in startLiveActivity verwendeten live_activity_id übereinstimmen. Das Update wird an alle Geräte zugestellt, auf denen diese Aktivität gestartet wurde.
live_activity.relevance-score	Integer	Optional	Teilt dem iOS-System mit, welche Live Activity eine höhere Priorität als andere hat. Akzeptiert Werte von 1 bis unendlich (Werte bis 100 werden empfohlen).
live_activity.stale-date	Integer	Optional	Die Zeit (in Sekunden), die das Datum darstellt, an dem eine Live Activity veraltet oder nicht mehr aktuell ist.
apns_priority	Integer	Optional	Steuert die APNs-Zustellpriorität für diesen Live Activity-Push. Akzeptiert 10 (hohe Priorität, zugestellt mit dem apns-priority: 10-Header für sofortiges Rendern auf einem gesperrten Bildschirm) oder 5 (niedrige Priorität, zugestellt mit apns-priority: 5, um den Akku des Geräts zu schonen). Jeder andere Wert wird als 5 behandelt, ohne Validierungsfehler. Jeder Live Activity-Push hat standardmäßig die Priorität 5, unabhängig davon, ob er Benachrichtigungsinhalte (content/title) enthält – setzen Sie apns_priority: 10 explizit, um eine Zustellung mit hoher Priorität anzufordern. Siehe Zeitkritische Push-Benachrichtigungen und Zustellpriorität unten.
content	String	Optional	Text der Benachrichtigung für dieses Update. Der übliche Fall ist ein reines Content-State-Update, das weder content, title noch subtitle setzt und überhaupt keine Benachrichtigung enthält.
title	String	Optional	Titel der Benachrichtigung für dieses Update. Das Setzen von content, title oder subtitle löst eine Benachrichtigung aus und lässt ios_sound abspielen. Wenn keiner der drei gesetzt ist, bleibt das Update stumm, was der Standard für reine Content-State-Updates ist.
subtitle	String	Optional	Untertitel der Benachrichtigung für dieses Update. Hat die gleiche benachrichtigungsauslösende Rolle wie content/title oben.
ios_sound	String	Optional	Name der Sounddatei im Haupt-Bundle der App. Er befindet sich innerhalb von aps.alert neben content/title/subtitle, nicht im übergeordneten aps.sound, das von ActivityKit für Live Activities ignoriert wird. Daher wird er nur abgespielt, wenn dieses Update auch mindestens einen dieser drei Parameter setzt. iOS begrenzt auch die Rate von Live Activity-Benachrichtigungen von sich aus. Es wurde beobachtet, dass dieselbe Payload bei einer Zustellung mit Ton und bei der nächsten ohne Ton ankommt, sowohl auf dem Gerät als auch im Simulator.

Hinweis: relevance-score beeinflusst nur die Anzeigereihenfolge zwischen mehreren aktiven Live Activities auf demselben Gerät – es hat keinen Einfluss auf die Dringlichkeit der Zustellung. Verwenden Sie apns_priority, um zu steuern, wie dringend ein Update zugestellt wird.

Hinweis

Ein end ohne dismissal-date entfernt die Karte nicht. Sie bleibt auf dem Sperrbildschirm sichtbar und zeigt den mit diesem Update gesendeten content-state, bis Apples eigenes Live-Activity-System sie innerhalb von bis zu 4 Stunden von selbst entfernt.

Request-Beispiel

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "apns_priority": 10,
        "title": "Live Activity Update",
        "live_activity": {
          "event": "update",
          "content-state": {
            "status": "second 66",
            "estimatedTime": "66 min",
            "emoji": "👨‍"
          },
          "relevance-score": 60
        },
        "live_activity_id": "FIRST_LIVE_ACTIVITY"
      }
    ]
  }
}

Response-Beispiel

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "Messages": [
      "XXXXX-XXXXXXXX-XXXXXXXX"
    ]
  }
}

Lesen Sie diesen Artikel, um mehr über die Arbeit mit Live Activities mit dem Pushwoosh iOS SDK zu erfahren.

Zeitkritische Push-Benachrichtigungen und Zustellpriorität

Standardmäßig stellt Apple Live Activity-Updates mit niedriger Priorität (apns-priority: 5) zu, um den Akku zu schonen. Wenn ein Gerät gesperrt ist, wird ein Update mit niedriger Priorität im Hintergrund verarbeitet und wird erst auf dem Sperrbildschirm sichtbar, wenn der Benutzer das Gerät entsperrt. Auf einem bereits entsperrten Gerät wird es dennoch sofort gerendert. Verwenden Sie den oben beschriebenen Parameter apns_priority, um eine Zustellung mit hoher Priorität (apns-priority: 10) anzufordern, damit das Update sofort auf dem Sperrbildschirm gerendert wird, ohne Entsperren.

Nicht mit dem Schalter für zeitkritische Push-Benachrichtigungen verbunden

Der Schalter Zeitkritische Push-Benachrichtigung im Pushwoosh Control Panel setzt den interruption-level nur für Standard-Push-Benachrichtigungen. Er hat keine Auswirkung auf die Zustellpriorität von Live Activities, die über diese API gesendet werden – Live Activities verwenden einen separaten Zustellpfad, der ausschließlich durch den apns_priority-Request-Parameter gesteuert wird.

Auch mit apns-priority: 10 begrenzt Apple, wie oft es verwendet werden kann.

APNs-Budget für hohe Priorität

Apple begrenzt, wie viele Push-Benachrichtigungen mit hoher Priorität (apns-priority: 10) eine App pro Stunde senden kann. Bei häufig aktualisierten Aktivitäten (z. B. Live-Ergebnisse) sollten Sie apns-priority: 10 für kritische Ereignisse reservieren und apns-priority: 5 oder weniger Updates für routinemäßige Änderungen verwenden. Das Aktivieren von NSSupportsLiveActivitiesFrequentUpdates in der Info.plist Ihrer App (siehe den iOS SDK-Leitfaden) erhöht dieses Budget für Anwendungsfälle mit hoher Frequenz.

Mehrere Aktivitäten pro Gerät

Sie können mehrere Live Activities auf demselben Gerät starten, indem Sie startLiveActivity mehrmals mit unterschiedlichen live_activity_id-Werten aufrufen.

Wenn Sie beispielsweise zwei Aktivitäten starten: FIRST_LIVE_ACTIVITY mit filter: FILTER_NAME_1 und SECOND_LIVE_ACTIVITY mit filter: FILTER_NAME_2, wird ein Gerät, das beiden Filtern entspricht, beide Aktivitäten gleichzeitig ausführen.

Um eine davon zu aktualisieren, übergeben Sie ihre live_activity_id an updateLiveActivity. Das Update wird an alle Geräte zugestellt, auf denen diese Aktivität erstellt wurde. Die andere Aktivität ist nicht betroffen.

Der Parameter relevance-score steuert die Anzeigepriorität, wenn mehrere Live Activities auf demselben Gerät aktiv sind. Wenn der Bildschirmplatz begrenzt ist oder Aktivitäten gruppiert sind, wird die Aktivität mit einem höheren Wert mit höherer Priorität angezeigt.