iOS Live Activities API

Apple-Dokumentation:

• Über Live-Aktivitäten
• Aktualisieren und Beenden von Live-Aktivitäten mit ActivityKit-Push-Benachrichtigungen

startLiveActivity

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

Ermöglicht das Erstellen von iOS Live-Aktivitäten.

Anfragekörper

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 mit Nachrichtenparametern. Details finden Sie in der nachstehenden Tabelle „Benachrichtigungen“.

Benachrichtigungen

Parameter, die im notifications-Array verwendet werden:

Parameter	Typ	Erforderlich/Optional	Beschreibung
content	String	Erforderlich	Fallback-Inhalt für Geräte mit iOS-Versionen unter 16.1, die Live-Aktivitäten nicht unterstützen. Auf iOS 16.1+ (mit Unterstützung für Live-Aktivitäten) stammt der Inhalt aus dem Feld live_activity.
title	String	Optional	Der Titel der Benachrichtigung.
live_activity	Object	Erforderlich	Live-Aktivitätsdaten zum Erstellen einer Live-Aktivität in iOS.
live_activity.content-state	Object	Erforderlich	Inhalt für die Live-Aktivitäts-Benachrichtigung.
live_activity.attributes-type	String	Erforderlich	Der Typ der in der Live-Aktivität verwendeten Attribute.
live_activity.attributes	Object	Erforderlich	Attribute für die Live-Aktivität.
live_activity_id	String	Erforderlich	Ein eindeutiger Bezeichner für die Live-Aktivität. Wird verwendet, um diese Aktivität beim Aufruf von updateLiveActivity gezielt anzusprechen. Muss pro Aktivitätssitzung eindeutig sein.
filter	String	Optional	Der Name eines Pushwoosh-Filters (Segments). Siehe Segment- / Filtername. Die Live-Aktivität wird auf allen Geräten gestartet, die diesem Filter entsprechen.
devices	Array of Strings	Optional	Eine Liste von Geräte-Tokens. Die Live-Aktivität wird nur auf den angegebenen Geräten gestartet.
send_date	String	Optional	Plant den Push, der die Live-Aktivität startet, für ein bestimmtes Datum und eine bestimmte Uhrzeit – funktioniert entweder mit filter- oder devices-Targeting. Verwenden Sie das Format JJJJ-MM-TT HH:mm oder now, um sofort zu starten (dies ist auch der Standard, wenn der Parameter weggelassen wird). Das Datum 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-Aktivitäts-Push. Akzeptiert 10 (hohe Priorität, zugestellt mit dem Header apns-priority: 10 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-Aktivitäts-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.

Vorsicht

Der Remote-Start einer Live-Aktivität ü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-Aktivität mit einer Remote-Push-Benachrichtigung starten.

Wenn Sie auf einen filter (Segment) abzielen, 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-Aktivitäts-Pushes nicht mit send_rate angepasst werden kann.

Anfragebeispiel

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"
      }
    ]
  }
}

Antwortbeispiel

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

Hinweis:

Lesen Sie diesen Artikel, um mehr über die Arbeit mit Live-Aktivitäten 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-Aktivitäten

Anfragekörper

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 mit Nachrichtenparametern. Details finden Sie in der nachstehenden Tabelle „Benachrichtigungen“.

Benachrichtigungen

Parameter, die im notifications-Array verwendet werden:

Parameter	Typ	Erforderlich/Optional	Beschreibung
live_activity	Object	Erforderlich	Live-Aktivitätsdaten zum Aktualisieren einer Live-Aktivität in iOS.
live_activity.event	String	Erforderlich	Gibt den Ereignistyp an. Verwenden Sie "update", um die Live-Aktivität 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-Aktivität zu übergeben, um deren Inhalt zu aktualisieren.
live_activity.dismissal-date	Integer	Optional	Die Zeit (in Sekunden), zu der die Live-Aktivität enden soll.
live_activity_id	String	Erforderlich	Der eindeutige Bezeichner der zu aktualisierenden Live-Aktivität. 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-Aktivität 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-Aktivität veraltet oder nicht mehr aktuell ist.
apns_priority	Integer	Optional	Steuert die APNs-Zustellpriorität für diesen Live-Aktivitäts-Push. Akzeptiert 10 (hohe Priorität, zugestellt mit dem Header apns-priority: 10 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-Aktivitäts-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: relevance-score beeinflusst nur die Anzeigereihenfolge mehrerer aktiver Live-Aktivitäten 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.

Anfragebeispiel

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

Antwortbeispiel

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

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

Zeitkritische Push-Benachrichtigungen und Zustellpriorität

Standardmäßig liefert Apple Live-Aktivitäts-Updates mit niedriger Priorität (apns-priority: 5) aus, 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 im Zusammenhang mit dem Schalter „Zeitkritische Push-Benachrichtigung“

Der Schalter Zeitkritische Push-Benachrichtigung im Pushwoosh Control Panel legt den interruption-level nur für Standard-Push-Benachrichtigungen fest. Er hat keine Auswirkung auf die über diese API gesendete Zustellpriorität von Live-Aktivitäten – Live-Aktivitäten verwenden einen separaten Zustellpfad, der ausschließlich durch den Anfrageparameter apns_priority 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) reservieren Sie apns_priority: 10 für kritische Ereignisse und verwenden Sie apns_priority: 5 oder weniger Updates für routinemäßige Änderungen. Das Aktivieren von NSSupportsLiveActivitiesFrequentUpdates in der Info.plist Ihrer App (siehe die Anleitung zum iOS SDK) erhöht dieses Budget für Anwendungsfälle mit hoher Frequenz.

Mehrere Aktivitäten pro Gerät

Sie können mehrere Live-Aktivitäten 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-Aktivitäten 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.