API de Esquemas de Live Activity

Un esquema de Live Activity es un Esquema JSON para un tipo de ActivityAttributes en su aplicación (por ejemplo, FlightAttributes), que cubre las dos mitades de la tarjeta: los campos de ContentState que cambian mientras la actividad se ejecuta, y los campos fijos durante toda su vida útil. Publique un esquema para que el elemento de Live Activity de un journey pueda construir campos con nombre para ambas mitades a partir de él, en lugar de un editor JSON sin formato y una lista de campos de nombre/valor libre. La tarjeta y su diseño todavía se construyen en el código de su aplicación. El esquema solo describe los datos que un journey rellena.

Esta API es para desarrolladores que integran Live Activities. Consulte la API de Live Activities de iOS para iniciar y actualizar las actividades en sí.

Escribir un esquema

attributesType es el nombre del tipo de Swift que se ajusta a ActivityAttributes en su aplicación. Pushwoosh no lee su código ni valida el nombre contra él; es solo la cadena que la API almacena y la cadena que pasa al campo attributes-type de startLiveActivity.

jsonSchema cubre ambas mitades de ese tipo, en dos lugares separados:

• Los campos de ContentState, los que cambian mientras la actividad se ejecuta, como la puerta de embarque, el estado o la hora estimada de llegada (ETA) de un vuelo, van en las properties raíz del esquema.
• Los campos de ActivityAttributes, fijos durante toda la vida de la actividad y establecidos una vez cuando comienza, como un número de vuelo, van en una sección attributes separada, con sus propias properties y una lista required opcional.

La sección attributes es opcional. Sin ella, los campos de ActivityAttributes siguen siendo una lista libre de nombre/valor de campo en el elemento de Live Activity, en lugar de campos con nombre. Usted siempre pasa los valores reales de los atributos a través de live_activity.attributes en startLiveActivity — el esquema solo declara sus nombres, tipos y cuáles son obligatorios.

Ejemplo

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

    var flightNumber: String
}

flightNumber se encuentra en ActivityAttributes. gate, status y estimatedTime se encuentran en ContentState. Publique ambas mitades como el esquema para attributesType: "FlightAttributes":

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

required dentro de attributes hace que flightNumber sea obligatorio en el paso Start del elemento de Live Activity: dejarlo en blanco allí se rechaza. Las properties raíz para los campos de ContentState no tienen esa lista. Un journey nunca está obligado a rellenar gate, status o estimatedTime.

Una vez publicado, el elemento de Live Activity de un journey lee esta forma para ofrecer campos con nombre para gate, status y estimatedTime en Card content, en lugar de un editor de estado de contenido sin formato. Lo mismo ocurre con flightNumber en Card attributes, en lugar de una lista libre de nombre/valor de campo.

Consulte las Convenciones a continuación para conocer las reglas de formato e inmutabilidad que se aplican a jsonSchema, y Gestionar esquemas en el Panel de Control al final de esta página para realizar las mismas acciones sin llamar directamente a la API.

URL base

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

Autenticación

Cada solicitud debe incluir un encabezado Authorization con su token de API del servidor:

Authorization: Api YOUR_API_TOKEN

Convenciones

• La nomenclatura de campos es asimétrica. Las solicitudes aceptan tanto lowerCamelCase como el nombre proto. Las respuestas siempre devuelven los nombres de campo proto, en snake_case (attributes_type, json_schema); los ejemplos a continuación utilizan esa grafía.
• Las versiones son inmutables. Una versión publicada no se puede editar; no existe un método Update. Publicar de nuevo con el mismo attributesType y version falla con AlreadyExists. Un cambio en el widget siempre es una nueva versión. Omita version en Create para publicar la siguiente versión libre para ese attributesType.
• Formato de jsonSchema: debe ser un objeto JSON con "type": "object", de hasta 64 KB. null, un número, una cadena simple o un objeto que carezca de "type": "object" son todos rechazados, porque el formulario que Pushwoosh construye necesita campos con nombre, que solo un esquema de objeto tiene. La sección opcional attributes, cuando está presente, debe ser en sí misma un objeto con sus propias properties y, opcionalmente, un array required que solo nombre campos declarados en attributes.properties. Un nombre de campo no puede aparecer tanto en properties como en attributes.properties.

Endpoints

Método	Ruta	Descripción
GET	/api/live_activity_schemas	Listar los esquemas de una aplicación
GET	/api/live_activity_schemas/{attributesType}/{version}	Obtener una versión de esquema
POST	/api/live_activity_schemas	Publicar una nueva versión de esquema
DELETE	/api/live_activity_schemas/{attributesType}/{version}	Eliminar una versión de esquema

Listar

Lista cada attributesType para el que una aplicación ha publicado esquemas, con todas sus versiones, la más nueva primero.

GET /api/live_activity_schemas

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
application	string	Sí	El código de aplicación para el cual listar los esquemas.
attributesType	string	No	Restringir la lista a un tipo de ActivityAttributes.

Ejemplo de respuesta

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

Obtener

Devuelve una versión de esquema.

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

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
attributesType	string	Sí	Nombre del tipo ActivityAttributes.
version	integer	Sí	Versión del esquema.

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
application	string	Sí	El código de aplicación al que pertenece el esquema.

Respuesta

Devuelve { "schema": { ... } }, el objeto de esquema mostrado en Listar arriba.

Crear

Publica una nueva versión de esquema para un attributesType. Devuelve el esquema creado, incluyendo la versión que se le asignó.

POST /api/live_activity_schemas

Cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
application	string	Sí	El código de aplicación en el que se publicará el esquema.
attributesType	string	Sí	Nombre del tipo ActivityAttributes declarado en su aplicación.
jsonSchema	string	Sí	Esquema JSON tanto de ContentState como de attributes. Consulte Escribir un esquema arriba.
version	integer	No	Versión a publicar. Omita para obtener la siguiente versión libre para este attributesType.

Ejemplo de solicitud

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

Respuesta

Devuelve { "schema": { ... } }, el objeto de esquema creado.

Precaución

Publicar un par attributesType/version que ya existe falla con AlreadyExists; las versiones son inmutables, por lo que no hay forma de sobrescribir una. Publique sin version para obtener la siguiente en su lugar.

Eliminar

Elimina permanentemente una versión de esquema.

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

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
attributesType	string	Sí	Nombre del tipo ActivityAttributes.
version	integer	Sí	Versión del esquema a eliminar.

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
application	string	Sí	El código de aplicación al que pertenece el esquema.

Respuesta

Devuelve un objeto vacío en caso de éxito.

Peligro

Esta acción no se puede deshacer. El elemento de Live Activity de un journey construido contra la versión eliminada conserva sus valores de contenido y atributos ya guardados. Simplemente pierde las sugerencias del formulario para ambos a partir de ese momento: el contenido vuelve a un editor JSON sin formato, y los atributos vuelven a una lista libre de nombre/valor de campo.

Respuestas de error

Estado HTTP	Significado
400 Bad Request	Argumento no válido: falta un campo obligatorio, jsonSchema no cumple la regla de formato anterior (incluida una sección attributes no válida), o jsonSchema excede los 64 KB.
401 Unauthorized	Encabezado Authorization ausente o no válido.
403 Forbidden	La aplicación no pertenece a la cuenta del solicitante.
404 Not Found	No se encontró la aplicación o el par attributesType/version.
409 Conflict	Se llamó a Create con un par attributesType/version que ya existe (AlreadyExists en la transmisión).
500 Internal Server Error	Fallo inesperado del lado del servidor.

Gestionar esquemas en el Panel de Control

El Panel de Control ofrece las mismas acciones que la API sin necesidad de llamarla directamente: listar versiones por tipo, publicar una nueva versión, ver el JSON de una versión y eliminar una versión (con una confirmación, ya que la eliminación es permanente). Consulte la configuración de esquemas de Live Activity de iOS para ver la ruta de clics.