Live Activity

Live Activity 是一张实时更新的卡片，用户无需打开应用即可看到进度（航班状态、配送、行程等）。在 iOS 上，它是锁屏和灵动岛上的一张小卡片。在 Android 16 及更高版本上，它是同类卡片，以带进度条的常驻通知形式显示。

在 journey 中使用 Live Activity 元素，在 iOS、Android 或两者上启动、更新或结束该卡片。

每个元素执行一个操作：

• Start： 创建卡片。
• Update： 更改现有卡片。
• End： 关闭卡片。

要在之后更改或关闭同一张卡片，请再添加一个 Live Activity 元素，并通过 Card created by 指回创建该卡片的那个元素。

使用场景示例

当用户需要在不打开应用的情况下看到不断变化的状态时，使用此元素。

• 航班状态： 值机后显示卡片。在飞行过程中保持登机口、状态和时间的更新。降落后移除卡片。
• 外卖配送： 下单时显示卡片。在配送途中保持骑手姓名、预计到达时间和距离的更新。送达后移除卡片。
• 网约车： 请求行程时显示卡片。在司机接近时保持司机、预计到达时间和车牌号的更新。行程完成后移除卡片。
• 订单或预约： 订单或预约确认时显示卡片。随进度保持状态更新。完成或到访结束后移除卡片。
• 实时活动： 活动开始时显示卡片。活动进行期间保持比分、阶段或日程的更新。活动结束后移除卡片。

提示

完整的 journey 示例请参阅如何在锁屏上显示航班状态和如何在锁屏上显示配送进度。

前提条件

在设置此元素之前，请检查每个平台的要求。

iOS 卡片：

• iOS Live Activity 支持： 您的应用必须支持 Live Activities。请参阅 iOS SDK Live Activities 指南。
• 已发布的 widget schema： 请开发团队在 Applications → Configure → Live Activity schemas 下发布与应用中 Live Activity 类型匹配的 schema。他们也可以通过 API 发布。关于 schema 应包含的内容，请参阅编写 schema。
• 列表中的 widget： schema 发布后，在此元素的 Widget 下选择它。如果 Widget 列表为空，说明 schema 尚未发布。

Android 通知：

• Android Live Updates 支持： 您的应用需要 SDK 6.11+ 和 pushwoosh-liveupdates 模块。Android 不需要 schema。请让您的 Android 开发人员确认该模块已包含在构建中。

设置元素

1. 将 Live Activity 元素拖到画布上。

   

2. 双击该元素以打开其设置。

3. 在 Step name 中输入名称。

4. 在 Action 中，选择以下之一：

   • Start： 创建 Live Activity 卡片。
   • Update： 更改现有卡片的内容。
   • End： 关闭卡片。

5. 在 Platforms 下，打开 iOS Live Activity、Android Live Updates 或两者。至少必须保留一个平台处于开启状态，因此无法关闭最后一个。在 Update 和 End 上，Platforms 显示来自关联 Start 元素的平台，且为只读。

   

6. 仅在 Start 上设置卡片键，以便之后的 Update 和 End 步骤能找到此卡片：

   • 在 Card key: event 中，选择标识该卡片的事件（例如 journey 入口事件）。
   • 在 Card key: attribute 中，选择使该键对每位旅客唯一的属性。一旦设置了 Card key: event，此项即为必填。若不设置，则事件选择不起作用，效果与两个字段都留空相同：每位旅客一张卡片，按默认用户 ID 寻址。

   

将 Update 和 End 关联到正确的卡片

当 Action 为 Update 或 End 时，使用 Card created by 指向创建此卡片的确切 Start 元素。否则 Update 或 End 将无法到达该卡片。

1. 在 Card created by 中，选择该 Start 元素的 Step name（例如 Order card start）。

选择 Card created by 后，Card key (from the start element) 会显示来自该 Start 的 Card key: event 和 Card key: attribute 值。它是只读的，用于确认此元素指向哪张卡片。

注意

示例：Start 命名为 Order card start。在 Update 和 End 中，在 Card created by 里选择 Order card start。这两个步骤随后会更改或关闭同一张订单卡片。

选择卡片语言

Card language 同时适用于 iOS 卡片和 Android 通知。

将 Card language 设置为 default 或特定语言代码。default 下的内容是您未单独填写的任何语言的后备内容。

设置 iOS 卡片

如果只打开了 Android Live Updates，请跳过本节。

选择 widget 和 schema 版本

1. 在 Widget 中，为此卡片选择已发布的 Live Activity 类型。下方的内容字段来自此选择。在 Update 或 End 中，Widget 为只读，继承自 Card created by 元素。

2. 在 Schema version 中，选择要使用该 widget schema 的哪个已发布版本。Card content 字段来自此版本。在 Update 和 End 中，Schema version 仍可选择：您可以为同一个继承的 widget 选择与关联的 Start 所用版本不同的已发布版本。

   

设置卡片的固定属性（仅 Start）

在 Start 上，于 Card attributes 下，添加在卡片整个生命周期内保持固定、只设置一次且不再更改的字段，例如航班号或订单 ID。这些字段与下方的 Card content 字段是分开的。那些值可以在 Update 时更改。

向您的 iOS 开发人员询问确切的 Field name 列表。这些名称在卡片的整个生命周期内保持固定（应用的 ActivityAttributes）。不要使用会变化的 Card content 名称（应用的 ContentState）。

1. 点击 Add attribute。
2. 为每个所需属性设置 Field name 和 Value。

Update 和 End 不设置属性。Start 为此卡片设置的内容将保持不变。

警告

卡片属性会按照您应用的 ActivityAttributes 类型的预期逐字段发送。名称写错，或留空，设备的解码器就会拒绝整个负载。在一次实际测试中，带有 flightNumber 的 Start 打开了卡片，而没有任何属性的 Start 只传递了信封，锁屏上没有任何可显示的内容。

填写卡片内容

在 Card content 下，在每个字段中输入字面值或个性化占位符。所选 schema 版本中的每个属性对应一个字段。

Update 和 End 时的预填充

在 Update 或 End 时，如果当前 Card language 的 Card content 为空（包括您刚添加的语言），Pushwoosh 会在您打开设置时从关联的 Start 元素预填字段：

• 与 Start 相同的语言，如果该语言有内容。
• 否则使用 Start 的 default 内容。
• 如果 Start 两者都没有，请将字段留空并自行填写。

预填的值仍可编辑。仅在您想保留这些编辑时点击 Apply。仅打开该元素不会更改正在运行的 journey。

您在 Update 或 End 中留空的字段不会被发送。此时卡片在这些字段中显示什么取决于您的应用：它可能保留之前的值、清空它，或做其他处理。请询问您的开发人员，您的应用如何处理这种情况。

在 End 中，Card content 是可选的。您填写的字段将成为卡片关闭前显示的最终值。

设置投递优先级和时间

1. 在 Delivery priority 中，选择 iOS 何时应投递此更新：

   • Immediate： iOS 立即投递，并可以唤醒手机（如果您设置了声音，还会播放声音）。
   • Quiet： iOS 可能会与其他更新一起延后投递，不会立即唤醒手机。
   • Default (batched)： iOS 使用其自身默认的批量投递方式，不会立即唤醒手机。

2. 在 Sound 中，从列表中选择一个声音。您的开发团队会将声音文件添加到 iOS 应用包中。请参阅自定义推送声音。声音仅在与 Alert title 或 Alert text 一起时才会播放，与横幅相同。

3. 根据您为此元素设置的 Action（Start、Update 或 End），填写以下之一：

   • Start 或 Update： 将 Stale after, min 设置为卡片上的数据应保持看起来新鲜的分钟数。该时间结束后，iOS 会将数字显示为已过时的暗色。卡片仍留在锁屏上。要让数字继续看起来是最新的，请在该时间结束前发送另一个 Update。
   • End： 将 Dismiss after, min 设置为已关闭的卡片在 iOS 移除它之前，在锁屏上保留的时长。保留为 0，卡片将持续显示其最终的 Card content，直到 iOS 在最多 4 小时内自行将其淘汰。

4. 您可以选择将 Relevance score 设置为 1 到 100 之间的数字。当某人同时有多个来自您应用的活跃 Live Activity 时，iOS 会优先显示分数更高的那个。保留为 0 表示不设置偏好。Pushwoosh 根本不会向 Apple 发送 0 分。完整说明请参阅每台设备的多个活动。

填写 Android 通知

填写 Android 通知的标题、文本、进度条和标题栏时间。仅当 Android Live Updates 打开时才会显示本节。它使用与 iOS 卡片相同的 Card language。

1. 为您为 Android 填写的每种语言设置 Notification title。在 Start 和 Update 上，只有这些语言都设置了标题，journey 才能运行。缺少标题的语言会在表单中显示提醒。

2. 设置 Notification text。

   

3. 设置进度条：

   • Progress： 输入一个数字，或 {name} 形式的占位符（也可以是 {name|format} 或 {name|format|default}），表示进度条应处于的位置，单位与分段长度相同。
   • Segments： 为进度条的每个彩色部分点击 Add segment，并为每个分段设置十六进制 Color（#RRGGBB 或 #AARRGGBB）和 Length。各分段长度相加即为整个进度条。
   • Animate the bar without a known end： 打开后显示移动的进度条，而不是 Progress 值。
   • Hide the progress bar： 打开后显示不带进度条的卡片。

   

4. 设置标题栏时间：

   • Header time： 输入以秒（而非毫秒）为单位的 Unix 时间戳或占位符，表示卡片标题栏时钟应显示的时刻。例如，1735689600 表示 2025-01-01 00:00 UTC。如果同时设置了此项和 Header time after, min，则使用 Header time。
   • Header time after, min： 设置发送后多少分钟作为标题栏显示的时间。
   • Run the header time as a timer： 打开后，Header time 将显示为运行中的时钟，而不是固定值。打开后会显示 Count down to the header time。
   • Count down to the header time： 打开后，将向 Header time 倒计时，而不是从发送时开始正计时。
   • Hide the header time： 打开后显示不带标题栏时间的卡片。

   

上述任何字段都可以包含占位符，其解析方式与 iOS 的 Card content 字段相同：来自 journey 事件，或使用事件属性进行个性化。

部分 Android 设备不会显示该通知

• Android 15 或更早版本，或未包含 pushwoosh-liveupdates 模块的应用： Pushwoosh 仍会发送更新，但设备上不会显示任何内容，也不会改为显示普通推送。
• 华为和百度设备： 这些设备无法接收 Android Live Updates。更新仅发送到通过 Firebase Cloud Messaging (FCM) 注册的设备。

点击该通知会打开应用，与普通推送相同。

设置提醒横幅

本节仅在 iOS Live Activity 打开时适用。如果只打开了 Android Live Updates，这些字段将被隐藏，也不会发送任何内容。

对于所有三种操作（Start、Update 和 End）：

1. 在 Alert title 中，设置锁屏上显示的横幅标题。
2. 在 Alert text 中，设置横幅文本。

警告

如果 Alert title 和 Alert text 都为空，卡片仍会启动、更新或结束，但锁屏不会显示横幅，也不会播放声音。当此操作应在锁屏上显现时，请至少填写两者之一。

选择哪台设备接收卡片

寻址方式仅在 Start 上设置一次。将两个开关都保持关闭，即可将卡片发送到旅客进入该 journey 时所用的设备。打开其中一个开关会关闭另一个：

• Send to all devices of this user： 发送到该旅客的 User ID 下注册的每一台设备，而不仅仅是他们进入时所用的那台。
• Send to the last active device only： 发送到该 User ID 最近使用的单一设备，而不是所有设备或入口设备。

提示

当同一个人可能在与进入 journey 时不同的 iPhone 上查看时，打开 Send to the last active device only。

在 Update 和 End 中，查看 Delivery (from the start element)。它标明了来自关联 Start 的寻址模式。更新只能到达同一张卡片，因此它会以相同的方式发出。

注意

一旦 journey 开始运行，两个开关都会锁定，Start 也是如此。要在之后更改寻址方式，请先暂停 journey。

个性化内容

当 Alert title、Alert text、Card content 或 Android 的 Notification title、Notification text、Progress、Header time 中的占位符应从 journey 事件或基于 API 的入口获取值，而不是从设备标签获取时，使用此功能。

1. 在 Overwrite personalization 下，打开 Personalise message with event attributes。
2. 勾选您想重新映射的每个占位符旁边的 Overwrite placeholder 复选框。
3. 将该占位符映射到一个事件属性。

保存元素

点击 Apply 以保存元素设置。Apply 会将此元素保存在 journey 中。它并不确认卡片已出现在设备上。journey 运行后，请检查此步骤的 Total entries 和流失情况，并根据您打开的平台，在测试用的 iPhone、Android 16 及更高版本的测试设备或两者上验证卡片。

限制

• 元素统计： 在此步骤上，检查 Total entries、Delivery 行（寻址模式）以及流失情况（No recipient for the card、Live Activity send failed）。No recipient for the card 表示消息在该模式下未找到已启用平台的设备，而不是设备缺少 Live Activity 令牌。此步骤不会报告设备是否显示了卡片，或用户是否打开了它。
• 声音不保证在每次更新时播放： iOS 会自行对 Live Activity 提醒进行限速。同一次更新可能这次播放声音，下次却悄无声息地送达。
• 测试期间连续多次 Start 操作： 如果您在短时间内为同一个人发送约十次 Start 操作（例如在测试 journey 时），Apple 可能会停止显示新卡片，且不返回错误。在 journey 中，该人看起来仍可能显示为已投递。测试运行之间应留出间隔。