iOS 实时活动 API

Apple 文档：

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

要让 Customer Journey 的实时活动点能够从字段名称而不是原始 JSON 编辑器构建其内容状态表单，请为您的 attributes-type 发布一个模式——请参阅 Live Activity Schemas API。

startLiveActivity

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

允许创建 iOS 实时活动。

请求正文

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

通知

notifications 数组中使用的参数：

参数	类型	必需/可选	描述
content	String	必需*	启动实时活动的推送的提醒正文，以及在低于 16.1 版本的 iOS 设备上显示的回退文本。
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 过滤器（分群）的名称。请参阅 Segment / Filter name。实时活动将在所有匹配此过滤器的设备上启动。
devices	Array of Strings	可选	设备令牌 列表。实时活动将仅在指定的设备上启动。
send_date	String	可选	安排在特定日期和时间启动实时活动的推送——适用于 filter 或 devices 定位。使用格式 YYYY-MM-DD HH:mm，或使用 now 立即启动（省略该参数时这也是默认值）。时间必须在过去 1 天内或未来 30 天内，否则请求将被验证错误拒绝。
timezone	String	可选	用于解析 send_date 的时区。如果省略，send_date 将以 UTC 时间解析。
apns_priority	Integer	可选	控制此实时活动推送的 APNs 投递优先级。接受 10（高优先级，通过 apns-priority: 10 标头投递，以便在锁定屏幕上即时渲染）或 5（低优先级，通过 apns-priority: 5 投递以节省设备电池）。任何其他值都将被视为 5，不会产生验证错误。无论是否携带提醒内容（content/title），每个实时活动推送都默认为优先级 5——要请求高优先级投递，请明确设置 apns_priority: 10。请参阅下文的时间敏感推送和投递优先级。

注意： * content 或 title 中至少有一个必须非空。Pushwoosh 会拒绝两者都为空的启动请求。

警告

通过 startLiveActivity 远程启动实时活动需要设备上的 iOS 17.2+——早期版本不支持此端点所依赖的 pushToStartTokenUpdates API。请参阅使用远程推送通知启动实时活动。

当定位一个 filter（分群）时，计划的发送时间是 Pushwoosh 开始分派推送的时间，而不是一个保证的投递瞬间——对于大型受众，投递到单个设备可能会比 send_date 延迟几分钟，因为实时活动推送的发送速率无法通过 send_rate 自定义。

重复的推送启动调用会静默耗尽。在大约十次快速连续启动后，Apple 会停止投递底层的推送启动通知，且不会返回任何错误，而 startLiveActivity 仍然返回 200。在活动测试期间，这看起来像是“API 工作正常，但设备上没有任何反应”。请隔开连续的测试启动。

请求示例

使用过滤器

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "apns_priority": 10,
        "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",
        "apns_priority": 10,
        "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 access token (API 访问令牌)。
application	String	必需	Pushwoosh application code (应用代码)
notifications	Array	必需	消息参数的 JSON 数组。详情请参见下方的“通知”表。

通知

notifications 数组中使用的参数：

参数	类型	必需/可选	描述
live_activity	Object	必需	用于在 iOS 中更新实时活动的数据。
live_activity.event	String	必需	指定事件类型。使用 "update" 更新实时活动，或使用 "end" 关闭它。
live_activity.content-state	Object	必需	包含键值对的对象，用于向实时活动传递数据以更新其内容。
live_activity.dismissal-date	Integer	可选	实时活动应结束的时间（以秒为单位）。在 end 时，省略此字段可让卡片一直显示其最后的 content-state，直到 iOS 自行将其撤下——见下方说明。设置一个过去的日期，则会在此更新到达后立即撤下卡片。
live_activity_id	String	必需	要更新的实时活动的唯一标识符。必须与 startLiveActivity 中使用的 live_activity_id 匹配。更新将被投递到所有启动了此活动的设备上。
live_activity.relevance-score	Integer	可选	告知 iOS 系统哪个实时活动比其他活动具有更高的优先级。接受从 1 到无穷大的值（建议使用最高为 100 的值）。
live_activity.stale-date	Integer	可选	表示实时活动变为过时或过期的日期的时间（以秒为单位）。
apns_priority	Integer	可选	控制此实时活动推送的 APNs 投递优先级。接受 10（高优先级，通过 apns-priority: 10 标头投递，以便在锁定屏幕上即时渲染）或 5（低优先级，通过 apns-priority: 5 投递以节省设备电池）。任何其他值都将被视为 5，不会产生验证错误。无论是否携带提醒内容（content/title），每个实时活动推送都默认为优先级 5——要请求高优先级投递，请明确设置 apns_priority: 10。请参阅下文的时间敏感推送和投递优先级。
content	String	可选	此更新的提醒正文。常见情况是仅更新内容状态，此时不设置 content、title 或 subtitle，并且完全不携带提醒。
title	String	可选	此更新的提醒标题。设置 content、title 或 subtitle 会触发提醒，并允许 ios_sound 播放。如果这三者都未设置，更新将保持静默，这是仅更新内容状态的默认行为。
subtitle	String	可选	此更新的提醒副标题。与上面的 content/title 一样，具有触发提醒的作用。
ios_sound	String	可选	应用主包中的声音文件名。它与 content/title/subtitle 一起位于 aps.alert 内部，而不是顶层的 aps.sound（ActivityKit 会忽略实时活动的这个字段），因此只有在本次更新也设置了这三者中至少一个时才会播放。iOS 也会自行对实时活动提醒进行速率限制。观察到相同的有效负载在一次投递时带有声音，而在下一次投递时则没有，这种情况在设备和模拟器上都出现过。

注意： relevance-score 仅影响同一设备上多个活动实时活动的显示顺序——它不影响投递的紧急性。使用 apns_priority 来控制更新的投递紧急程度。

注意

不带 dismissal-date 的 end 不会移除卡片。它会继续显示在锁屏上，展示此次更新发送的 content-state，Apple 自己的 Live Activity 系统最长会在 4 小时内自行将其撤下。

请求示例

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "apns_priority": 10,
        "title": "Live Activity Update",
        "live_activity": {
          "event": "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 处理实时活动的信息。

时间敏感推送和投递优先级

默认情况下，Apple 以低优先级（apns-priority: 5）投递实时活动更新以节省电池。当设备锁定时，低优先级更新会在后台处理，只有在用户解锁设备后才会在锁定屏幕上可见。在已解锁的设备上，它仍然会立即渲染。使用上面描述的 apns_priority 参数来请求高优先级（apns-priority: 10）投递，以便更新能立即在锁定屏幕上渲染，无需解锁。

与时间敏感推送开关无关

Pushwoosh 控制面板中的 时间敏感推送 开关仅设置标准推送通知的 interruption-level。它对此 API 发送的实时活动投递优先级没有影响——实时活动使用一个单独的投递路径，完全由 apns_priority 请求参数控制。

即使有 apns_priority: 10 可用，Apple 也会限制其使用频率。

APNs 高优先级预算

Apple 限制了应用每小时可以发送的高优先级（apns-priority: 10）推送的数量。对于频繁更新的活动（例如，实时比分），请为关键事件保留 apns_priority: 10，并为常规变更使用 apns_priority: 5 或更少的更新。在应用的 Info.plist 中启用 NSSupportsLiveActivitiesFrequentUpdates（请参阅 iOS SDK 指南）可以为高频使用场景提高此预算。

每台设备的多个活动

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

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

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

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