API схем Live Activity

Схема Live Activity — это JSON-схема для одного типа ActivityAttributes в вашем приложении (например, FlightAttributes), охватывающая обе половины карточки: поля ContentState, которые изменяются во время выполнения активности, и поля, зафиксированные на весь ее жизненный цикл. Опубликуйте схему, чтобы элемент Live Activity в Journey мог создавать именованные поля для обеих половин на ее основе, а не с помощью простого редактора JSON и произвольного списка полей. Карточка и ее макет по-прежнему создаются в коде вашего приложения. Схема описывает только данные, которые заполняются в Journey.

Этот API предназначен для разработчиков, интегрирующих Live Activities. Информацию о запуске и обновлении самих активностей см. в API iOS Live Activities.

Написание схемы

attributesType — это имя типа Swift, который соответствует ActivityAttributes в вашем приложении. Pushwoosh не читает ваш код и не проверяет имя на соответствие — это просто строка, которую хранит API, и строка, которую вы передаете в поле attributes-type метода startLiveActivity.

jsonSchema охватывает обе половины этого типа, в двух отдельных местах:

• Поля ContentState — те, что изменяются во время выполнения активности, например, номер выхода на посадку, статус или предполагаемое время прибытия рейса, — указываются в корневом properties схемы.
• Поля ActivityAttributes — зафиксированные на весь жизненный цикл активности и устанавливаемые один раз при ее запуске, например, номер рейса, — указываются в отдельном разделе attributes, с собственным properties и необязательным списком required.

Раздел attributes необязателен. Без него поля ActivityAttributes остаются свободным списком имя/значение поля на элементе Live Activity, а не именованными полями. Фактические значения атрибутов вы всегда передаете через live_activity.attributes в методе startLiveActivity — схема лишь объявляет их имена, типы и то, какие из них обязательны.

Пример

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

    var flightNumber: String
}

flightNumber находится в ActivityAttributes. gate, status и estimatedTime находятся в ContentState. Опубликуйте обе половины как схему для attributesType: "FlightAttributes":

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

required внутри attributes делает flightNumber обязательным на шаге Start элемента Live Activity: оставить его пустым там нельзя. У корневого properties для полей ContentState такого списка нет. Заполнять gate, status или estimatedTime в Journey никогда не обязательно.

После публикации элемент Live Activity в Journey считывает эту форму, чтобы предложить именованные поля для gate, status и estimatedTime в Card content вместо простого редактора content-state. То же самое происходит для flightNumber в Card attributes вместо свободного списка имя/значение поля.

См. Соглашения ниже для ознакомления с правилами формата и неизменяемости, которые применяются к jsonSchema, и Управление схемами в Панели управления в конце этой страницы для выполнения тех же действий без прямого вызова API.

Базовый URL

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

Аутентификация

Каждый запрос должен содержать заголовок Authorization с вашим токеном Server API:

Authorization: Api YOUR_API_TOKEN

Соглашения

• Именование полей асимметрично. Запросы принимают как lowerCamelCase, так и имя proto. Ответы всегда возвращаются с именами полей proto в snake_case (attributes_type, json_schema) — в примерах ниже используется этот регистр.
• Версии неизменяемы. Опубликованную версию нельзя редактировать — метод Update отсутствует. Повторная публикация с теми же attributesType и version завершится ошибкой AlreadyExists. Изменение виджета всегда означает новую версию. Опустите version при Create, чтобы опубликовать следующую свободную версию для этого attributesType.
• Формат jsonSchema: должен быть объектом JSON с "type": "object", размером до 64 КБ. null, число, простая строка или объект без "type": "object" будут отклонены, поскольку для формы, которую создает Pushwoosh, требуются именованные поля, которые есть только в схеме объекта. Необязательный раздел attributes, если он присутствует, сам должен быть объектом с собственным properties и, опционально, массивом required, который называет только поля, объявленные в attributes.properties. Имя поля не может присутствовать одновременно в properties и в attributes.properties.

Эндпоинты

Method	Path	Description
GET	/api/live_activity_schemas	Получить список схем приложения
GET	/api/live_activity_schemas/{attributesType}/{version}	Получить одну версию схемы
POST	/api/live_activity_schemas	Опубликовать новую версию схемы
DELETE	/api/live_activity_schemas/{attributesType}/{version}	Удалить версию схемы

List (Получение списка)

Возвращает список всех attributesType, для которых приложение опубликовало схемы, со всеми их версиями, начиная с самой новой.

GET /api/live_activity_schemas

Параметры запроса

Parameter	Type	Required	Description
application	string	Yes	Код приложения, для которого нужно получить список схем.
attributesType	string	No	Ограничить список одним типом ActivityAttributes.

Пример ответа

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

Get (Получение)

Возвращает одну версию схемы.

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

Параметры пути

Parameter	Type	Required	Description
attributesType	string	Yes	Имя типа ActivityAttributes.
version	integer	Yes	Версия схемы.

Параметры запроса

Parameter	Type	Required	Description
application	string	Yes	Код приложения, которому принадлежит схема.

Ответ

Возвращает { "schema": { ... } }, объект схемы, показанный в разделе List выше.

Create (Создание)

Публикует новую версию схемы для attributesType. Возвращает созданную схему, включая присвоенную ей версию.

POST /api/live_activity_schemas

Тело запроса

Parameter	Type	Required	Description
application	string	Yes	Код приложения, в котором публикуется схема.
attributesType	string	Yes	Имя типа ActivityAttributes, объявленного в вашем приложении.
jsonSchema	string	Yes	JSON-схема полей ContentState и attributes. См. Написание схемы выше.
version	integer	No	Версия для публикации. Опустите, чтобы получить следующую свободную версию для этого attributesType.

Пример запроса

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

Ответ

Возвращает { "schema": { ... } }, объект созданной схемы.

Осторожно

Публикация пары attributesType/version, которая уже существует, завершится ошибкой AlreadyExists — версии неизменяемы, поэтому перезаписать их невозможно. Публикуйте без version, чтобы получить следующую версию.

Delete (Удаление)

Безвозвратно удаляет одну версию схемы.

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

Параметры пути

Parameter	Type	Required	Description
attributesType	string	Yes	Имя типа ActivityAttributes.
version	integer	Yes	Версия схемы для удаления.

Параметры запроса

Parameter	Type	Required	Description
application	string	Yes	Код приложения, которому принадлежит схема.

Ответ

В случае успеха возвращает пустой объект.

Опасно

Это действие необратимо. Элемент Live Activity в Journey, созданный на основе удаленной версии, сохраняет уже сохраненные значения контента и атрибутов. С этого момента он просто теряет подсказки формы для обоих: контент возвращается к простому редактору JSON, а атрибуты — к свободному списку имя/значение поля.

Ответы об ошибках

HTTP status	Meaning
400 Bad Request	Недопустимый аргумент: отсутствует обязательное поле, jsonSchema не соответствует правилу формата, указанному выше (включая недействительный раздел attributes), или jsonSchema превышает 64 КБ.
401 Unauthorized	Отсутствует или недействителен заголовок Authorization.
403 Forbidden	Приложение не принадлежит учетной записи вызывающей стороны.
404 Not Found	Приложение или пара attributesType/version не найдены.
409 Conflict	Create был вызван с парой attributesType/version, которая уже существует (AlreadyExists при передаче).
500 Internal Server Error	Неожиданный сбой на стороне сервера.

Управление схемами в Панели управления

Панель управления предлагает те же действия, что и API, без прямого вызова: получение списка версий по типу, публикация новой версии, просмотр JSON версии и удаление версии (с подтверждением, поскольку удаление является безвозвратным). Путь для выполнения этих действий см. в разделе Конфигурация схем iOS Live Activity.