iOS 实时活动 API

Apple 文档：

关于实时活动

使用 ActivityKit 推送通知更新和结束实时活动

startLiveActivity

POST https://api.pushwoosh.com/json/1.3/startLiveActivity

允许创建 iOS 实时活动。

请求正文

参数	类型	必需/可选	描述
application	String	必需	Pushwoosh 应用代码
auth	String	必需	来自 Pushwoosh 控制面板的 API 访问令牌。
notifications	Array	必需	消息参数的 JSON 数组。详细信息请参见下方的“通知”表。

通知

notifications 数组中使用的参数：

参数	类型	必需/可选	描述
content	String	必需	为运行 iOS 16.1 以下版本且不支持实时活动的设备提供的备用内容。在 iOS 16.1+（支持实时活动）上，内容来源于 `live_activity` 字段。
title	String	可选	通知消息的标题。
live_activity	Object	必需	用于在 iOS 中创建实时活动的实时活动数据。
live_activity.content-state	Object	必需	实时活动通知的内容。
live_activity.attributes-type	String	必需	实时活动中使用的属性类型。
live_activity.attributes	Object	必需	实时活动的属性。
live_activity_id	String	必需	实时活动的唯一标识符。用于在调用 `updateLiveActivity` 时定位此活动。每个活动会话必须唯一。
filter	String	可选	Pushwoosh 筛选器（分群）的名称。请参阅分群/筛选器名称。实时活动将在所有匹配此筛选器的设备上启动。
devices	Array of Strings	可选	设备令牌列表。实时活动将仅在指定的设备上启动。
send_date	String	可选	安排在特定日期和时间启动实时活动的推送——适用于 `filter` 或 `devices` 定位。使用格式 `YYYY-MM-DD HH:mm`，或 `now` 立即启动（如果省略该参数，这也是默认值）。时间必须在过去 1 天内或未来 30 天内，否则请求将被拒绝并返回验证错误。
timezone	String	可选	用于解释 `send_date` 的时区。如果省略，`send_date` 将以 UTC 时间解释。

请求示例

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "FIRST_LIVE_ACTIVITY",
        "filter": "FILTER_NAME_1"
      }
    ]
  }
}

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "SECOND_LIVE_ACTIVITY",
        "devices": ["first_third", "second_device"]
      }
    ]
  }
}

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "THIRD_LIVE_ACTIVITY",
        "filter": "FILTER_NAME_1",
        "send_date": "2026-06-16 16:00"
      }
    ]
  }
}

响应示例

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "Messages": [
      "XXXXX-XXXXXXXX-XXXXXXXX"
    ]
  }
}

注意：

阅读这篇文章，了解更多关于使用 Pushwoosh iOS SDK 处理实时活动的信息。

updateLiveActivity

POST https://api.pushwoosh.com/json/1.3/updateLiveActivity

允许更新和结束 iOS 实时活动。

请求正文

参数	类型	必需/可选	描述
auth	String	必需	来自 Pushwoosh 控制面板的 API 访问令牌。
application	String	必需	Pushwoosh 应用代码
notifications	Array	必需	消息参数的 JSON 数组。详细信息请参见下方的“通知”表。

通知

notifications 数组中使用的参数：

参数	类型	必需/可选	描述
live_activity	Object	必需	用于在 iOS 中更新实时活动的实时活动数据。
live_activity.event	String	必需	指定事件类型。使用 `"update"` 更新实时活动，或使用 `"end"` 关闭它。
live_activity.content-state	Object	必需	用于向实时活动传递数据以更新其内容的键值对对象。
live_activity.dismissal-date	Integer	可选	实时活动应结束的时间（以秒为单位）。
live_activity_id	String	必需	要更新的实时活动的唯一标识符。必须与 startLiveActivity 中使用的 `live_activity_id` 匹配。更新将被发送到所有启动了此活动的设备。
live_activity.relevance-score	Integer	可选	告知 iOS 系统哪个实时活动比其他活动具有更高的优先级。接受从 1 到无穷大的值（建议值最高为 100）。
live_activity.stale-date	Integer	可选	表示实时活动变得陈旧或过时日期的时间（以秒为单位）。

请求示例

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "live_activity": {
          "event": "update",
          "title": "Live Activity Update",
          "content-state": {
            "status": "second 66",
            "estimatedTime": "66 min",
            "emoji": "👨‍"
          },
          "relevance-score": 60
        },
        "live_activity_id": "FIRST_LIVE_ACTIVITY"
      }
    ]
  }
}

响应示例

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "Messages": [
      "XXXXX-XXXXXXXX-XXXXXXXX"
    ]
  }
}

阅读这篇文章，了解更多关于使用 Pushwoosh iOS SDK 处理实时活动的信息。

每台设备的多个活动

您可以通过多次调用 startLiveActivity 并使用不同的 live_activity_id 值，在同一设备上启动多个实时活动。

例如，如果您启动了两个活动：FIRST_LIVE_ACTIVITY 使用 filter: FILTER_NAME_1 和 SECOND_LIVE_ACTIVITY 使用 filter: FILTER_NAME_2，那么同时匹配这两个筛选器的设备将同时运行这两个活动。

要更新其中一个活动，请将其 live_activity_id 传递给 updateLiveActivity。更新将被发送到所有创建了该活动的设备上。另一个活动不受影响。

当同一设备上有多个实时活动处于活动状态时，relevance-score 参数控制显示优先级。如果屏幕空间有限或活动被分组，具有较高值的活动将以更高的优先级显示。