# iOS 实时活动 API

> Apple 文档：
> 
> * [关于实时活动](https://developer.apple.com/design/human-interface-guidelines/live-activities)
> * [使用 ActivityKit 推送通知更新和结束实时活动](https://developer.apple.com/documentation/activitykit/updating-and-ending-your-live-activity-with-activitykit-push-notifications)

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



## startLiveActivity



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

允许创建 iOS 实时活动。

### 请求正文

| 参数 | 类型 | 必需/可选 | 描述 |
|---------------|--------|-------------------|-----------------------------------------------------------------------------|
| application | String | 必需 | [Pushwoosh application code (应用代码)](/zh/developer/api-reference/api-identifiers/#application-code) |
| auth | String | 必需 | 来自 Pushwoosh 控制面板的 [API access token (API 访问令牌)](/zh/developer/api-reference/api-identifiers/#api-access-token)。 |
| 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](/zh/developer/api-reference/api-identifiers/#segment--filter-name)。实时活动将在所有匹配此过滤器的设备上启动。 |
| devices | Array of Strings | 可选 | [设备令牌](/zh/developer/api-reference/api-identifiers/#push-token) 列表。实时活动将仅在指定的设备上启动。 |
| 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`。请参阅下文的[时间敏感推送和投递优先级](#time-sensitive-push-and-delivery-priority)。 |

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

<Aside type="caution">
通过 `startLiveActivity` 远程启动实时活动需要设备上的 **iOS 17.2+**——早期版本不支持此端点所依赖的 `pushToStartTokenUpdates` API。请参阅[使用远程推送通知启动实时活动](/zh/developer/pushwoosh-sdk/ios-sdk/ios-live-activities/#start-live-activity-with-a-remote-push-notification)。

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

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

### 请求示例

<Tabs>
<TabItem label="使用过滤器">
```json
{
  "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"
      }
    ]
  }
}
```
</TabItem>
<TabItem label="使用设备">
```json
{
  "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"]
      }
    ]
  }
}
```
</TabItem>
<TabItem label="定时启动">
```json
{
  "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"
      }
    ]
  }
}
```
</TabItem>
</Tabs>

### 响应示例

```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "Messages": [
      "XXXXX-XXXXXXXX-XXXXXXXX"
    ]
  }
}
```
> **注意：**
> 
> 阅读[这篇文章](/zh/developer/pushwoosh-sdk/ios-sdk/ios-live-activities)以了解更多关于使用 Pushwoosh iOS SDK 处理实时活动的信息。


## updateLiveActivity


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

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

### 请求正文

| 参数 | 类型 | 必需/可选 | 描述 |
|----------------|--------|-------------------|------------------------------------------------------------------------|
| auth | String | 必需 | 来自 Pushwoosh 控制面板的 [API access token (API 访问令牌)](/zh/developer/api-reference/api-identifiers/#api-access-token)。 |
| application | String | 必需 | [Pushwoosh application code (应用代码)](/zh/developer/api-reference/api-identifiers/#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`。请参阅下文的[时间敏感推送和投递优先级](#time-sensitive-push-and-delivery-priority)。 |
| 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` 来控制更新的投递紧急程度。

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

### 请求示例

```json

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

### 响应示例

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

> [阅读这篇文章](/zh/developer/pushwoosh-sdk/ios-sdk/ios-live-activities/)以了解更多关于使用 Pushwoosh iOS SDK 处理实时活动的信息。


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

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

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

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

<Aside type="note" title="APNs 高优先级预算">
Apple 限制了应用每小时可以发送的高优先级（`apns-priority: 10`）推送的数量。对于频繁更新的活动（例如，实时比分），请为关键事件保留 `apns_priority: 10`，并为常规变更使用 `apns_priority: 5` 或更少的更新。在应用的 Info.plist 中启用 `NSSupportsLiveActivitiesFrequentUpdates`（请参阅 [iOS SDK 指南](/zh/developer/pushwoosh-sdk/ios-sdk/ios-live-activities/#infoplist-configuration)）可以为高频使用场景提高此预算。
</Aside>

## 每台设备的多个活动

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

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

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

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