> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Live Activities

> 了解如何在 OneSignal 中使用 iOS Live Activities，直接在锁屏和 Dynamic Island 上提供实时更新。为体育比分、配送等事件启用无缝跟踪。

Live Activities 允许您的 iOS 和 iPadOS 应用程序向锁屏和 Dynamic Island 提供实时更新，让用户无需打开应用程序即可了解信息。iOS 16.1 中引入并扩展到 iOS 17，Live Activities 非常适合时效性信息，如配送跟踪、游戏比分或交通更新。

<Note>
  Live Activities 是 iOS 功能，但您可以通过 [Android Live Notifications](./android-live-notifications) 实现类似功能。
</Note>

<Frame caption="Live Activities 示例">
  <img src="https://mintcdn.com/onesignal/MUgio66t0sYhGEvj/images/docs/67688a22bb44b87b57a4bd27f114eea45298dfa4d1d48f1b64b2d449ea93c206-channel-setup-live-activities.jpg?fit=max&auto=format&n=MUgio66t0sYhGEvj&q=85&s=dde03fd57c37604ed28894c0d49d1480" width="1280" height="720" data-path="images/docs/67688a22bb44b87b57a4bd27f114eea45298dfa4d1d48f1b64b2d449ea93c206-channel-setup-live-activities.jpg" />
</Frame>

***

## 为什么使用 Live Activities？

Live Activities 非常适合实时、事务性或时限性更新。

* 可见时间长达 8 小时
* 临时性 — 显示首个 Live Activity 无需权限
* 在锁屏和 Dynamic Island 等高端设备界面上具有高参与度和可见性

<Note>
  [在我们的博客中了解更多用例 →](https://onesignal.com/blog/new-live-activities-support-to-help-you-drive-loyalty-faster)
</Note>

***

## 为什么使用 OneSignal？

OneSignal 通过处理以下内容简化了 Live Activities：

* 临时推送令牌管理
* 通过单个 API 调用扩展到数百万设备
* 实时分析和性能洞察
* 与推送、邮件、SMS 和应用内消息的跨渠道编排

<Note>
  Live Activities 在除了拥有超过 10,000 名已选择加入订阅者的免费计划之外的所有计划中都可用。[查看定价](https://onesignal.com/pricing) 或联系 `support@onesignal.com` 获取帮助。
</Note>

***

## Live Activities 入门

### 要求

* iOS 16.1+ 或 iPadOS 17+
* 已集成 OneSignal [移动 SDK](./mobile-sdk-setup)
* 根据我们的 [Live Activities 开发者指南](./live-activities-developer-setup) 完成设置
* 点击跟踪和确认交付需要 iOS SDK 版本 **5.2.15 或更高**

### Live Activities 工作原理

* **可见持续时间**：活跃时间长达 8 小时（可使用 [更新 Live Activity API](/reference/update-live-activity-api) 中的 `dismissal_date` 参数移除）。
* **无需权限**：首个活动是临时的；后续活动取决于用户设置。
* **限制**：每个应用最多同时 5 个 Live Activities。
* **远程启动**：iOS 17.2+ 支持通过推送启动。
* **非促销用途**：必须为用户提供价值——不是为广告设计的。

### 创建和更新 Live Activity

<Steps>
  <Step title="启动 Live Activity">
    Live Activities 可以通过 2 种方式启动：

    1. 使用我们的 [启动 Live Activity API](/reference/start-live-activity)，即"推送启动"。
    2. 在应用内触发（[Live Activities 开发者设置](./live-activities-developer-setup)）。
  </Step>

  <Step title="更新 Live Activity">
    使用 [更新 Live Activity API](/reference/update-live-activity-api) 并传递 `activity_id` 以更新所有关联设备。
  </Step>

  <Step title="结束 Live Activity">
    Live Activities 可以通过以下方式结束：

    <Tabs>
      <Tab title="OneSignal SDK (`exitLiveActivity`)">
        * 向 OneSignal 服务器发送请求，停止为给定的 `activityId` 发送更新。
        * **不会** 从屏幕上移除 Live Activity。它将在 4 小时后或通过用户操作自动移除。
      </Tab>

      <Tab title="更新 Live Activity API">
        使用 `event: end` 字段停止进一步更新，并包含 `dismissal_date` 以从屏幕上移除 Live Activity：

        * Live Activity 将在 4 小时后或通过用户操作自动从屏幕上移除。
        * 设置接下来 4 小时内的 **未来** `dismissal_date` 时间以更早移除它。
        * 设置 **过去** 的 `dismissal_date` 时间以立即从用户屏幕上移除。用户必须为 Live Activity 点击了"允许"才能以编程方式移除。
      </Tab>

      <Tab title="用户操作">
        * 用户手动关闭 Live Activity，如将其滑走。
        * 用户在 iOS 设置中撤销 Live Activity 权限。
      </Tab>
    </Tabs>

    <Note>
      SDK 方法不会在视觉上关闭 Live Activity。

      * 开发者必须使用带有 `dismissal_date` 的 API 或原生 iOS 方法（例如，`activity.end(dismissalPolicy: .immediate)`）。
      * 用户必须为 Live Activity 点击了"允许"才能以编程方式移除。
    </Note>
  </Step>
</Steps>

***

## 分析和报告

OneSignal 提供全面的分析，帮助您测量和优化 Live Activities 的性能。跟踪关键指标，如交付率、点击、失败和订阅更改。

**可用的关键指标：**

* **已发送**：从 OneSignal 发送到 Apple 推送通知服务 (APNs) 的 Live Activities
* **确认交付**：确认交付到设备的 Live Activities（需要 iOS SDK 5.2.15+）
* **失败**：交付失败的 Live Activities
* **取消订阅**：当用户关闭或禁用 Live Activities 时标记为取消订阅的订阅
* **点击**：所有 Live Activities 的总点击次数

<Note>
  有关消息报告、受众活动、数据导出和性能分析的详细信息，请参阅我们的 [Live Activities 分析指南](./live-activities-analytics)。
</Note>

***

## 最佳实践和指南

### 功能性

* 将 Live Activities 用于事务性或上下文更新（例如，ETA、比分、计时器）。
  * 用户无需持续进入应用检查状态或更改，他们可以一眼看到手机上的更新。
  * 具有明确开始和结束的事件或任务。不要使用 Live Activity 显示广告或纯粹的促销目的。您提供的价值是什么？
* 避免过度更新以保护设备电池。
* 确保 Live Activity 用于不超过 8 小时的事件或任务，并且只在对用户有用时显示。

### UI/UX

* 支持所有 Live Activity 呈现：紧凑、最小、展开、锁屏。
* 正确使用品牌、间距和深色/浅色主题。
* 优先考虑清晰度和点击目标。不要试图吸引对 Dynamic Island 的注意。
* 避免在 Live Activity 中显示敏感信息。

<Note>
  有关 Live Activities 最佳实践的更多信息，请参阅 Apple 的 [Live Activities 人机界面指南](https://developer.apple.com/design/human-interface-guidelines/live-activities)。
</Note>

### 定位和大规模发送

确保 Live Activity 在预期时出现，通常是当用户执行操作（例如关注事件）或打开应用检查更新（例如更新的交付时间）时。

* 针对体育比赛、音乐会或其他现场活动等事件的用户群体。
* 针对个人或事务性事件的个别用户。

<Note>
  有关如何定位用户的详细信息可以在我们的 [使用 OneSignal API 发送消息文档](reference/create-message) 中找到。
</Note>

更新 Live Activities 时，您可以选择设置"优先级"，Apple 用它来确定更新的紧急程度。Apple 有内部阈值，会限制过于频繁使用高优先级标志的请求。由于此内部阈值，Apple 建议选择正常和高优先级的混合以防止限制。有关如何设置优先级的详细信息可以在我们的 [更新 Live Activity API 参考](/reference/update-live-activity-api) 中找到。

如果您的用例依赖于更频繁的高优先级更新，您可以将键 `NSSupportsLiveActivitiesFrequentUpdates` 作为布尔类型添加到您的 Info.plist 中并设置为 YES，如 [Apple 开发者文档](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications#Determine-the-update-frequency) 中所述。当 Live Activity 超过其推送预算时，将向用户显示对话框，如果他们允许 Live Activity 继续，预算将自动增加，以获得无缝的用户体验。

***

## 常见问题

### 我的计划中是否可以访问 Live Activities？

Live Activities 在除了拥有超过 10,000 名已选择加入订阅者的免费计划之外的所有计划中都可用。如果您在免费计划中拥有超过 10,000 名已选择加入的订阅者，您可以升级以使用 Live Activities。[查看定价](https://onesignal.com/pricing) 或联系 `support@onesignal.com` 获取帮助。

### 高优先级更新的预算是多少？

Apple 不为高优先级（`priority: 10`）更新提供固定限制，但它们确实执行动态系统级预算。在短时间内发送过多高优先级更新可能导致限制，更新可能被延迟或丢弃。

要降低限制风险：

* 使用优先级混合：Apple 建议使用 `priority: 5`（标准）和 `priority: 10`（高）以获得平衡。
* 仅为时效性或关键更新保留 `priority: 10`（例如，订单状态更改、游戏比分）。

如果您的用例需要频繁更新：

* 将键 `NSSupportsLiveActivitiesFrequentUpdates` 添加到应用的 `Info.plist` 文件中，设置为布尔值 `YES`。
* 当超过此预算时，iOS 可能会提示用户允许其他更新。如果用户同意，Apple 将自动扩展允许的更新限制以保持无缝体验。

更多详细信息，请参阅 [Apple 开发者文档](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications#Determine-the-update-frequency)。

### 我在哪里可以在 OneSignal 控制面板中看到 Live Activities？

Live Activities 只能通过我们的 Live Activities API 发送。但是，您可以在控制面板的已发送消息中查看历史发送的 Live Activities（最多 30 天），在过滤 Live Activities 后。在这里您将能够看到发送了哪些 Live Activities、发送了什么更新信息以及收到更新的受众规模。

### 哪些设备支持 Live Activities？

Apple 保持更新的兼容性指南，包含所有支持 [iOS 16+](https://support.apple.com/guide/iphone/supported-models-iphe3fa5df43/16.0/ios/16.0) 和 [iPadOS 17+](https://support.apple.com/guide/ipad/ipad-models-compatible-with-ipados-17-ipad213a25b2/ipados) 的设备。

***

<Check>
  您现在应该具备了关于 Live Activities 需要了解的一切。

  通过遵循我们的 [Live Activities 开发者文档](./live-activities-developer-setup) 开始设置您的 Live Activities。
</Check>

***