实时活动 Schema API

实时活动 schema 是针对您应用中一种 ActivityAttributes 类型（例如 FlightAttributes）的 JSON Schema，涵盖卡片的两个部分：活动运行时会变化的 ContentState 字段，以及在其整个生命周期内固定不变的字段。发布一个 schema，以便 Journey 的 实时活动元素 可以据此为这两部分构建命名字段，而不是使用原始的 JSON 编辑器和自由格式的字段列表。卡片及其布局仍然在您的应用代码中构建。该 schema 仅描述 Journey 填充的数据。

此 API 适用于集成实时活动的开发人员。有关启动和更新活动本身的信息，请参阅 iOS 实时活动 API。

编写 schema

attributesType 是您应用中遵循 ActivityAttributes 的 Swift 类型的名称。Pushwoosh 不会读取您的代码或验证该名称——它只是 API 存储的字符串，也是您传递给 startLiveActivity 的 attributes-type 字段的字符串。

jsonSchema 涵盖该类型的两个部分，分别位于两处：

• ContentState 字段——活动运行时会变化的字段，例如航班的登机口、状态或预计到达时间——放在 schema 根级的 properties 中。
• ActivityAttributes 字段——在活动的整个生命周期内固定不变、并在活动开始时设置一次的字段，例如航班号——放在一个独立的 attributes 部分中，该部分有自己的 properties 和可选的 required 列表。

attributes 部分是可选的。省略它，ActivityAttributes 字段将在实时活动元素上保留为一个自由的字段名称/值列表，而不是命名字段。您始终通过 startLiveActivity 上的 live_activity.attributes 传递实际的属性值——该 schema 只声明它们的名称、类型以及哪些是必需的。

示例

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" 的 schema 发布：

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

attributes 内的 required 会使 flightNumber 在实时活动元素的 Start 步骤中成为必填项：在那里留空会被拒绝。ContentState 字段所在的根级 properties 没有这样的列表。Journey 从不要求填写 gate、status 或 estimatedTime。

发布后，Journey 的 实时活动元素 会读取此形状，在 Card content 中为 gate、status 和 estimatedTime 提供命名字段，而不是一个原始的 content-state 编辑器。flightNumber 在 Card attributes 中也是如此，而不是一个自由的字段名称/值列表。

有关适用于 jsonSchema 的格式和不可变性规则，请参阅下文的 约定；有关不直接调用 API 而执行相同操作的方法，请参阅本页末尾的 在 Control Panel 中管理 schema。

基础 URL

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

身份验证

每个请求都必须包含一个 Authorization 标头，其中包含您的 服务器 API 令牌：

Authorization: Api YOUR_API_TOKEN

约定

• 字段命名是不对称的。 请求同时接受 lowerCamelCase 和 proto 名称。响应始终返回 proto 字段名称，采用 snake_case 格式（attributes_type、json_schema）——下面的示例使用了这种大小写格式。
• 版本是不可变的。 已发布的版本无法编辑——没有 Update 方法。使用相同的 attributesType 和 version 再次发布会失败，并返回 AlreadyExists。小组件的任何更改都意味着一个新版本。在 Create 时省略 version，将为此 attributesType 发布下一个可用的版本。
• jsonSchema 格式： 必须是带有 "type": "object" 的 JSON 对象，最大 64 KB。null、数字、裸字符串或缺少 "type": "object" 的对象都将被拒绝，因为 Pushwoosh 构建的表单需要命名字段，而只有对象 schema 才有这些字段。可选的 attributes 部分（如果存在）本身必须是一个对象，具有自己的 properties，以及可选的 required 数组，该数组只能列出 attributes.properties 中声明的字段。字段名称不能同时出现在 properties 和 attributes.properties 中。

端点

方法	路径	描述
GET	/api/live_activity_schemas	列出应用程序的 schema
GET	/api/live_activity_schemas/{attributesType}/{version}	获取一个 schema 版本
POST	/api/live_activity_schemas	发布一个新的 schema 版本
DELETE	/api/live_activity_schemas/{attributesType}/{version}	删除一个 schema 版本

列表

列出应用程序已为其发布 schema 的每个 attributesType，包括其所有版本，最新版本在前。

GET /api/live_activity_schemas

查询参数

参数	类型	必需	描述
application	string	是	要列出 schema 的 应用程序代码。
attributesType	string	否	将列表限制为一种 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"
    }
  ]
}

获取

返回一个 schema 版本。

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

路径参数

参数	类型	必需	描述
attributesType	string	是	ActivityAttributes 类型的名称。
version	integer	是	Schema 版本。

查询参数

参数	类型	必需	描述
application	string	是	该 schema 所属的应用程序代码。

响应

返回 { "schema": { ... } }，即上面 列表 中显示的 schema 对象。

创建

为 attributesType 发布一个新的 schema 版本。返回创建的 schema，包括分配给它的版本。

POST /api/live_activity_schemas

请求正文

参数	类型	必需	描述
application	string	是	要在其中发布 schema 的应用程序代码。
attributesType	string	是	在您的应用中声明的 ActivityAttributes 类型的名称。
jsonSchema	string	是	ContentState 和 attributes 的 JSON Schema。请参阅上文的 编写 schema。
version	integer	否	要发布的版本。省略此项可获取此 attributesType 的下一个可用版本。

请求示例

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

响应

返回 { "schema": { ... } }，即创建的 schema 对象。

警告

发布已存在的 attributesType/version 对会失败并返回 AlreadyExists——版本是不可变的，因此无法覆盖。发布时不带 version 以获取下一个可用版本。

删除

永久删除一个 schema 版本。

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

路径参数

参数	类型	必需	描述
attributesType	string	是	ActivityAttributes 类型的名称。
version	integer	是	要删除的 schema 版本。

查询参数

参数	类型	必需	描述
application	string	是	该 schema 所属的应用程序代码。

响应

成功时返回一个空对象。

危险

此操作无法撤销。基于已删除版本构建的 Journey 的 实时活动元素 会保留其已保存的内容和属性值。它只是从那时起失去了两者的表单提示：内容会退回到原始的 JSON 编辑器，属性会退回到自由的字段名称/值列表。

错误响应

HTTP 状态	含义
400 Bad Request	无效参数：缺少必填字段，jsonSchema 不符合上述格式规则（包括无效的 attributes 部分），或 jsonSchema 超过 64 KB。
401 Unauthorized	缺少或无效的 Authorization 标头。
403 Forbidden	该应用程序不属于调用者的帐户。
404 Not Found	未找到该应用程序或 attributesType/version 对。
409 Conflict	使用已存在的 attributesType/version 对调用了 Create（在线路上为 AlreadyExists）。
500 Internal Server Error	意外的服务器端故障。

在 Control Panel 中管理 schema

Control Panel 提供了与 API 相同的操作，无需直接调用 API：按类型列出版本、发布新版本、查看版本的 JSON 以及删除版本（带有确认，因为删除是永久性的）。有关点击路径，请参阅 iOS 实时活动 schema 配置。