Live Activity Schemas API

Ein Live-Activity-Schema ist ein JSON-Schema für einen ActivityAttributes-Typ in Ihrer App (zum Beispiel FlightAttributes) und deckt beide Hälften der Karte ab: die ContentState-Felder, die sich während der Ausführung der Aktivität ändern, und die Felder, die für ihre gesamte Lebensdauer festgelegt sind. Veröffentlichen Sie ein Schema, damit das Live-Activity-Element einer Journey daraus benannte Felder für beide Hälften erstellen kann, anstatt einen reinen JSON-Editor und eine frei formulierbare Feldliste zu verwenden. Die Karte und ihr Layout werden weiterhin im Code Ihrer App erstellt. Das Schema beschreibt nur die Daten, die eine Journey ausfüllt.

Diese API ist für Entwickler gedacht, die Live Activities integrieren. Informationen zum Starten und Aktualisieren von Aktivitäten selbst finden Sie in der iOS Live Activities API.

Ein Schema schreiben

attributesType ist der Name des Swift-Typs, der in Ihrer App mit ActivityAttributes konform ist. Pushwoosh liest Ihren Code nicht und validiert den Namen nicht dagegen – es ist nur die Zeichenfolge, die die API speichert und die Sie an das attributes-type-Feld von startLiveActivity übergeben.

jsonSchema deckt beide Hälften dieses Typs ab, an zwei getrennten Stellen:

• Die ContentState-Felder – die, die sich während der Ausführung der Aktivität ändern, wie das Gate, der Status oder die voraussichtliche Ankunftszeit eines Fluges – kommen in die properties auf oberster Ebene des Schemas.
• Die ActivityAttributes-Felder – für die gesamte Lebensdauer der Aktivität festgelegt und einmal beim Start gesetzt, wie eine Flugnummer – kommen in einen separaten attributes-Abschnitt mit eigenen properties und einer optionalen required-Liste.

Der attributes-Abschnitt ist optional. Ohne ihn bleiben die ActivityAttributes-Felder eine freie Feldname/Wert-Liste auf dem Live-Activity-Element, statt benannter Felder. Sie übergeben die tatsächlichen Attributwerte immer über live_activity.attributes bei startLiveActivity – das Schema deklariert nur deren Namen, Typen und welche davon erforderlich sind.

Beispiel

struct FlightAttributes: ActivityAttributes {
    struct ContentState: Codable, Hashable {
        var gate: String
        var status: String
        var estimatedTime: String
    }

    var flightNumber: String
}

flightNumber befindet sich in ActivityAttributes. gate, status und estimatedTime befinden sich in ContentState. Veröffentlichen Sie beide Hälften als Schema für attributesType: "FlightAttributes":

{
  "type": "object",
  "properties": {
    "gate": { "type": "string" },
    "status": { "type": "string" },
    "estimatedTime": { "type": "string" }
  },
  "attributes": {
    "properties": {
      "flightNumber": { "type": "string" }
    },
    "required": ["flightNumber"]
  }
}

required innerhalb von attributes macht flightNumber auf dem Start-Schritt des Live-Activity-Elements verpflichtend: Wird es dort leer gelassen, wird das abgelehnt. Die properties auf oberster Ebene für die ContentState-Felder haben keine solche Liste. Eine Journey muss gate, status oder estimatedTime nie ausfüllen.

Nach der Veröffentlichung liest das Live-Activity-Element einer Journey diese Form, um benannte Felder für gate, status und estimatedTime im Karteninhalt anzubieten, anstatt eines reinen Editors für den Content-State. Dasselbe geschieht für flightNumber in den Kartenattributen, anstatt einer freien Feldname/Wert-Liste.

Siehe Konventionen unten für die Format- und Unveränderlichkeitsregeln, die für jsonSchema gelten, und Verwalten von Schemas im Control Panel am Ende dieser Seite für die gleichen Aktionen, ohne die API direkt aufzurufen.

Basis-URL

https://rpc-api.svc-nue.pushwoosh.com

Authentifizierung

Jede Anfrage muss einen Authorization-Header mit Ihrem Server-API-Token enthalten:

Authorization: Api YOUR_API_TOKEN

Konventionen

• Die Feldbenennung ist asymmetrisch. Anfragen akzeptieren sowohl lowerCamelCase als auch den Proto-Namen. Antworten kommen immer mit den Proto-Feldnamen in snake_case (attributes_type, json_schema) zurück – die folgenden Beispiele verwenden diese Schreibweise.
• Versionen sind unveränderlich. Eine veröffentlichte Version kann nicht bearbeitet werden – es gibt keine Update-Methode. Eine erneute Veröffentlichung mit demselben attributesType und derselben version schlägt mit AlreadyExists fehl. Eine Widget-Änderung ist immer eine neue Version. Lassen Sie version bei Create weg, um die nächste freie Version für diesen attributesType zu veröffentlichen.
• jsonSchema-Format: muss ein JSON-Objekt mit "type": "object" sein, bis zu 64 KB groß. null, eine Zahl, eine reine Zeichenfolge oder ein Objekt ohne "type": "object" werden alle abgelehnt, weil das Formular, das Pushwoosh erstellt, benannte Felder benötigt, die nur ein Objektschema hat. Der optionale attributes-Abschnitt muss, wenn vorhanden, selbst ein Objekt mit eigenen properties und optional einem required-Array sein, das nur Felder benennt, die in attributes.properties deklariert sind. Ein Feldname darf nicht gleichzeitig in properties und in attributes.properties vorkommen.

Endpunkte

Methode	Pfad	Beschreibung
GET	/api/live_activity_schemas	Schemas einer Anwendung auflisten
GET	/api/live_activity_schemas/{attributesType}/{version}	Eine Schema-Version abrufen
POST	/api/live_activity_schemas	Eine neue Schema-Version veröffentlichen
DELETE	/api/live_activity_schemas/{attributesType}/{version}	Eine Schema-Version löschen

Auflisten

Listet jeden attributesType, für den eine Anwendung Schemas veröffentlicht hat, mit all ihren Versionen, die neueste Version zuerst.

GET /api/live_activity_schemas

Abfrageparameter

Parameter	Typ	Erforderlich	Beschreibung
application	string	Ja	Der Anwendungscode, für den Schemas aufgelistet werden sollen.
attributesType	string	Nein	Beschränkt die Liste auf einen ActivityAttributes-Typ.

Antwortbeispiel

{
  "schemas": [
    {
      "application": "XXXXX-XXXXX",
      "attributes_type": "FlightAttributes",
      "version": 2,
      "json_schema": "{\"type\":\"object\",\"properties\":{\"gate\":{\"type\":\"string\"}},\"attributes\":{\"properties\":{\"flightNumber\":{\"type\":\"string\"}},\"required\":[\"flightNumber\"]}}",
      "created": "2026-09-01T10:00:00Z",
      "updated": "2026-09-01T10:00:00Z"
    },
    {
      "application": "XXXXX-XXXXX",
      "attributes_type": "FlightAttributes",
      "version": 1,
      "json_schema": "{\"type\":\"object\",\"properties\":{\"gate\":{\"type\":\"string\"},\"status\":{\"type\":\"string\"}}}",
      "created": "2026-08-15T10:00:00Z",
      "updated": "2026-08-15T10:00:00Z"
    }
  ]
}

Abrufen

Gibt eine Schema-Version zurück.

GET /api/live_activity_schemas/{attributesType}/{version}

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
attributesType	string	Ja	Name des ActivityAttributes-Typs.
version	integer	Ja	Schema-Version.

Abfrageparameter

Parameter	Typ	Erforderlich	Beschreibung
application	string	Ja	Der Anwendungscode, zu dem das Schema gehört.

Antwort

Gibt { "schema": { ... } } zurück, das Schema-Objekt, das oben unter Auflisten gezeigt wird.

Erstellen

Veröffentlicht eine neue Schema-Version für einen attributesType. Gibt das erstellte Schema zurück, einschließlich der ihm zugewiesenen Version.

POST /api/live_activity_schemas

Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
application	string	Ja	Der Anwendungscode, in dem das Schema veröffentlicht werden soll.
attributesType	string	Ja	Name des in Ihrer App deklarierten ActivityAttributes-Typs.
jsonSchema	string	Ja	JSON-Schema von sowohl ContentState als auch attributes. Siehe Ein Schema schreiben oben.
version	integer	Nein	Zu veröffentlichende Version. Weglassen, um die nächste freie Version für diesen attributesType zu erhalten.

Anfragebeispiel

{
  "application": "XXXXX-XXXXX",
  "attributesType": "FlightAttributes",
  "jsonSchema": "{\"type\":\"object\",\"properties\":{\"gate\":{\"type\":\"string\"},\"status\":{\"type\":\"string\"}},\"attributes\":{\"properties\":{\"flightNumber\":{\"type\":\"string\"}},\"required\":[\"flightNumber\"]}}"
}

Antwort

Gibt { "schema": { ... } } zurück, das erstellte Schema-Objekt.

Vorsicht

Die Veröffentlichung eines bereits existierenden attributesType/version-Paares schlägt mit AlreadyExists fehl – Versionen sind unveränderlich, daher gibt es keine Möglichkeit, eine zu überschreiben. Veröffentlichen Sie ohne version, um stattdessen die nächste zu erhalten.

Löschen

Löscht eine Schema-Version endgültig.

DELETE /api/live_activity_schemas/{attributesType}/{version}

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
attributesType	string	Ja	Name des ActivityAttributes-Typs.
version	integer	Ja	Zu löschende Schema-Version.

Abfrageparameter

Parameter	Typ	Erforderlich	Beschreibung
application	string	Ja	Der Anwendungscode, zu dem das Schema gehört.

Antwort

Gibt bei Erfolg ein leeres Objekt zurück.

Gefahr

Dies kann nicht rückgängig gemacht werden. Das Live-Activity-Element einer Journey, das mit der gelöschten Version erstellt wurde, behält seine bereits gespeicherten Content- und Attributwerte. Es verliert von da an nur die Formularhinweise für beide: Der Content fällt auf einen reinen JSON-Editor zurück, und die Attribute fallen auf eine freie Feldname/Wert-Liste zurück.

Fehlerantworten

HTTP-Status	Bedeutung
400 Bad Request	Ungültiges Argument: ein erforderliches Feld fehlt, jsonSchema verstößt gegen die obige Formatregel (einschließlich eines ungültigen attributes-Abschnitts), oder jsonSchema überschreitet 64 KB.
401 Unauthorized	Fehlender oder ungültiger Authorization-Header.
403 Forbidden	Die Anwendung gehört nicht zum Konto des Aufrufers.
404 Not Found	Die Anwendung oder das attributesType/version-Paar wurde nicht gefunden.
409 Conflict	Create wurde mit einem bereits existierenden attributesType/version-Paar aufgerufen (AlreadyExists auf der Leitung).
500 Internal Server Error	Unerwarteter serverseitiger Fehler.

Verwalten von Schemas im Control Panel

Das Control Panel bietet die gleichen Aktionen wie die API, ohne sie direkt aufzurufen: Versionen nach Typ auflisten, eine neue Version veröffentlichen, das JSON einer Version anzeigen und eine Version löschen (mit einer Bestätigung, da das Löschen endgültig ist). Den Klickpfad finden Sie unter Konfiguration der iOS Live Activity-Schemas.