iOS 实时活动 API

Apple 文档：

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

startLiveActivity

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

允许创建 iOS 实时活动。

请求正文

参数	类型	必需/可选	描述
application	String	必需	Pushwoosh application code
auth	String	必需	来自 Pushwoosh Control Panel 的 API access token。
notifications	Array	必需	消息参数的 JSON 数组。详情请参见下方的 Notifications 表。

Notifications

在 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 filter (segment) 的名称。请参阅 Segment / Filter name。实时活动将在所有匹配此筛选器的设备上启动。
devices	Array of Strings	可选	device tokens 列表。实时活动将仅在指定的设备上启动。
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。请参阅下文的 时间敏感推送和交付优先级。

警告

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

当定位 filter (segment) 时，预定的发送时间是 Pushwoosh 开始分派推送的时间，而不是保证的交付时刻——对于大型受众，单个设备的交付可能会比 send_date 延迟几分钟，因为实时活动推送的发送速率无法通过 send_rate 自定义。

请求示例

使用筛选器

{
  "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 Control Panel 的 API access token。
application	String	必需	Pushwoosh application code
notifications	Array	必需	消息参数的 JSON 数组。详情请参见下方的 Notifications 表。

Notifications

在 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	可选	表示实时活动变得陈旧或过时日期的时间（以秒为单位）。
apns_priority	Integer	可选	控制此实时活动推送的 APNs 交付优先级。接受 10（高优先级，通过 apns-priority: 10 标头交付，以便在锁定屏幕上即时渲染）或 5（低优先级，通过 apns-priority: 5 标头交付，以节省设备电池）。任何其他值都将被视为 5，且不会出现验证错误。无论是否携带警报内容（content/title），每个实时活动推送都默认为优先级 5——要请求高优先级交付，请明确设置 apns_priority: 10。请参阅下文的 时间敏感推送和交付优先级。

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

请求示例

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

时间敏感推送和交付优先级

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

与时间敏感推送开关无关

Pushwoosh Control Panel 中的 Time Sensitive Push 开关仅为标准推送通知设置 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 指南）可以为高频使用场景提高此预算。

每台设备的多个活动

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

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

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

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