API des schémas de Live Activity

Un schéma de Live Activity est un schéma JSON pour un type ActivityAttributes dans votre application (par exemple FlightAttributes), couvrant les deux moitiés de la carte : les champs ContentState qui changent pendant que l’activité est en cours, et les champs fixes pour toute sa durée de vie. Publiez un schéma pour que l’élément Live Activity d’un parcours puisse construire des champs nommés pour les deux moitiés à partir de celui-ci, au lieu d’un éditeur JSON brut et d’une liste de champs libres. La carte et sa mise en page sont toujours construites dans le code de votre application. Le schéma ne décrit que les données qu’un parcours remplit.

Cette API est destinée aux développeurs qui intègrent les Live Activities. Consultez l’API des Live Activities iOS pour démarrer et mettre à jour les activités elles-mêmes.

Écrire un schéma

attributesType est le nom du type Swift qui se conforme à ActivityAttributes dans votre application. Pushwoosh ne lit pas votre code ni ne valide le nom par rapport à celui-ci — c’est simplement la chaîne de caractères que l’API stocke et la chaîne que vous passez au champ attributes-type de startLiveActivity.

jsonSchema couvre les deux moitiés de ce type, à deux endroits distincts :

Les champs ContentState, ceux qui changent pendant que l’activité est en cours, comme la porte d’embarquement, le statut ou l’heure d’arrivée estimée d’un vol, vont dans les properties racine du schéma.
Les champs ActivityAttributes, fixes pour toute la durée de vie de l’activité et définis une seule fois à son démarrage, comme un numéro de vol, vont dans une section attributes distincte, avec ses propres properties et une liste required optionnelle.

La section attributes est optionnelle. Sans elle, les champs ActivityAttributes restent une liste libre de noms/valeurs de champs sur l’élément Live Activity au lieu de champs nommés. Vous passez toujours les valeurs d’attributs réelles via live_activity.attributes sur startLiveActivity — le schéma ne fait que déclarer leurs noms, leurs types et lesquels sont requis.

Exemple

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

    var flightNumber: String
}

flightNumber se trouve dans ActivityAttributes. gate, status et estimatedTime se trouvent dans ContentState. Publiez les deux moitiés comme le schéma pour attributesType: "FlightAttributes" :

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

required à l’intérieur d’attributes rend flightNumber obligatoire à l’étape Start de l’élément Live Activity : le laisser vide y est rejeté. Les properties racine pour les champs ContentState n’ont pas une telle liste. Un parcours n’est jamais obligé de remplir gate, status ou estimatedTime.

Une fois publié, l’élément Live Activity d’un parcours lit cette forme pour proposer des champs nommés pour gate, status et estimatedTime dans Card content, au lieu d’un éditeur de content-state brut. La même chose se produit pour flightNumber dans Card attributes, au lieu d’une liste libre de noms/valeurs de champs.

Consultez les Conventions ci-dessous pour les règles de format et d’immuabilité qui s’appliquent à jsonSchema, et Gérer les schémas dans le Panneau de configuration à la fin de cette page pour les mêmes actions sans appeler l’API directement.

URL de base

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

Authentification

Chaque requête doit inclure un en-tête Authorization avec votre jeton d’API serveur :

Authorization: Api VOTRE_JETON_API

Conventions

La nomination des champs est asymétrique. Les requêtes acceptent à la fois le lowerCamelCase et le nom proto. Les réponses reviennent toujours avec les noms de champs proto, en snake_case (attributes_type, json_schema) — les exemples ci-dessous utilisent cette casse.
Les versions sont immuables. Une version publiée ne peut pas être modifiée — il n’y a pas de méthode Update. Publier à nouveau avec les mêmes attributesType et version échoue avec AlreadyExists. Un changement de widget est toujours une nouvelle version. Omettez version lors de la Create pour publier la prochaine version disponible pour cet attributesType.
Format de jsonSchema : doit être un objet JSON avec "type": "object", jusqu’à 64 Ko. null, un nombre, une chaîne de caractères brute, ou un objet sans "type": "object" sont tous rejetés, car le formulaire que Pushwoosh construit a besoin de champs nommés, que seul un schéma d’objet possède. La section optionnelle attributes, lorsqu’elle est présente, doit elle-même être un objet avec ses propres properties et, éventuellement, un tableau required qui ne nomme que des champs déclarés dans attributes.properties. Un nom de champ ne peut pas apparaître à la fois dans properties et dans attributes.properties.

Points de terminaison

Méthode	Chemin	Description
`GET`	`/api/live_activity_schemas`	Lister les schémas d’une application
`GET`	`/api/live_activity_schemas/{attributesType}/{version}`	Obtenir une version de schéma
`POST`	`/api/live_activity_schemas`	Publier une nouvelle version de schéma
`DELETE`	`/api/live_activity_schemas/{attributesType}/{version}`	Supprimer une version de schéma

Lister

Liste chaque attributesType pour lequel une application a publié des schémas, avec toutes leurs versions, la plus récente en premier.

GET /api/live_activity_schemas

Paramètres de requête

Paramètre	Type	Requis	Description
`application`	string	Oui	Le code d’application pour lequel lister les schémas.
`attributesType`	string	Non	Restreindre la liste à un seul type `ActivityAttributes`.

Exemple de réponse

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

Obtenir

Retourne une version de schéma.

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

Paramètres de chemin

Paramètre	Type	Requis	Description
`attributesType`	string	Oui	Nom du type `ActivityAttributes`.
`version`	integer	Oui	Version du schéma.

Paramètres de requête

Paramètre	Type	Requis	Description
`application`	string	Oui	Le code d’application auquel le schéma appartient.

Réponse

Retourne { "schema": { ... } }, l’objet schéma montré dans Lister ci-dessus.

Créer

Publie une nouvelle version de schéma pour un attributesType. Retourne le schéma créé, y compris la version qui lui a été attribuée.

POST /api/live_activity_schemas

Corps de la requête

Paramètre	Type	Requis	Description
`application`	string	Oui	Le code d’application dans lequel publier le schéma.
`attributesType`	string	Oui	Nom du type `ActivityAttributes` déclaré dans votre application.
`jsonSchema`	string	Oui	Schéma JSON à la fois de `ContentState` et d’`attributes`. Voir Écrire un schéma ci-dessus.
`version`	integer	Non	Version à publier. Omettez pour obtenir la prochaine version disponible pour cet `attributesType`.

Exemple de requête

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

Réponse

Retourne { "schema": { ... } }, l’objet schéma créé.

Supprimer

Supprime définitivement une version de schéma.

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

Paramètres de chemin

Paramètre	Type	Requis	Description
`attributesType`	string	Oui	Nom du type `ActivityAttributes`.
`version`	integer	Oui	Version du schéma à supprimer.

Paramètres de requête

Paramètre	Type	Requis	Description
`application`	string	Oui	Le code d’application auquel le schéma appartient.

Réponse

Retourne un objet vide en cas de succès.

Réponses d’erreur

Statut HTTP	Signification
`400 Bad Request`	Argument invalide : un champ obligatoire est manquant, `jsonSchema` ne respecte pas la règle de format ci-dessus (y compris une section `attributes` invalide), ou `jsonSchema` dépasse 64 Ko.
`401 Unauthorized`	En-tête `Authorization` manquant ou invalide.
`403 Forbidden`	L’application n’appartient pas au compte de l’appelant.
`404 Not Found`	L’application, ou la paire `attributesType`/`version`, n’a pas été trouvée.
`409 Conflict`	`Create` a été appelé avec une paire `attributesType`/`version` qui existe déjà (`AlreadyExists` sur le réseau).
`500 Internal Server Error`	Échec inattendu côté serveur.

Gérer les schémas dans le Panneau de configuration

Le Panneau de configuration offre les mêmes actions que l’API sans l’appeler directement : lister les versions par type, publier une nouvelle version, voir le JSON d’une version, et supprimer une version (avec une confirmation, car la suppression est permanente). Consultez la configuration des schémas de Live Activity iOS pour le parcours de clics.