Voltra 服务端推送更新全链路:APNS、push-to-start 与 renderLiveActivityToString 服务端渲染手把手教程

原创2026-10-25 14:52:191,385 阅读

Voltra 服务端推送更新全链路:APNS、push-to-start 与 renderLiveActivityToString 服务端渲染手把手教程

Voltra 让 React Native 开发者把 iOS Live Activities(实时活动)与 Dynamic Island(灵动岛)布局写成普通 React 组件,无需手写 Swift。而它的服务端推送更新能力,正是让 Live Activity 在 App 后台甚至被杀进程后仍能持续刷新的关键:App 端收集 push token,服务端用 renderLiveActivityToString 渲染 UI,再通过 APNS 推送到锁屏。本文将手把手走通这条完整链路,覆盖 APNS 配置、update / push-to-start / end 三种事件,以及 iOS 18 广播推送。

想跑示例可以先克隆仓库:

git clone https://gitcode.com/gh_mirrors/vol/voltra

🎯 服务端推送解决什么问题

传统的实时活动(如航班动态、订单进度、外卖配送)只能靠 App 在前台时轮询接口更新。一旦用户切到桌面或杀掉 App,锁屏卡片就"冻住"了。

Voltra 的服务端推送全链路让更新主动权交给后端:

  1. App 内收集 token:addVoltraListener 监听 token 事件并上报服务端;
  2. 服务端渲染 UI:renderLiveActivityToString 把 React 组件渲染成压缩后的 JSON 字符串;
  3. APNS 下发:把 UI 放进 aps.content-state,按 update / start / end 三种事件推送;
  4. 系统级刷新:即使 App 完全没运行,iOS 也会自动更新锁屏与灵动岛 UI。

Voltra iOS Live Activity 服务端推送更新效果示例:航班状态实时刷新

如上图,航班状态(起飞时间、登机口、延误)正是典型的"服务端推送更新"场景:后端一更新,锁屏即时刷新,App 全程无需在前台。

第一步:在 Voltra 插件中启用 APNS 推送

服务端推送的前提是在 app.json(或 app.config.js)中开启 enablePushNotifications。Voltra 的 Expo config 插件会自动帮你完成大部分 Xcode 配置:

  • 添加 aps-environment entitlement(debug 构建自动设为 development)
  • 配置 Info.plist 推送相关开关
  • 如提供 groupIdentifier,还会配置 App Group
{
  "expo": {
    "plugins": [
      [
        "@use-voltra/ios-client",
        {
          "enablePushNotifications": true,
          "groupIdentifier": "group.your.app.voltraui"
        }
      ]
    ]
  }
}

💡 groupIdentifier 是可选的:只有当你需要把 Live Activity 里的按钮事件转发回 JS 层、或 App 与扩展之间共享图片时才需要。纯推送更新不带它也能正常工作。

仍需手动完成的三件事:

步骤 说明
Provisioning Profiles Xcode 中为 App 配置启用 Push Notifications 的签名描述文件
APNs 证书/密钥 在 Apple Developer 账号中创建 APNs 认证密钥,服务端推送时要用
Capabilities 确认 App target 已开启 Push Notifications 能力

完整配置说明见官方文档 server-side-updates.md,仓库示例工程的配置可参考 example/app.json。

第二步:在 App 内收集两种 push token

Voltra 提供的是专为 Live Activity 设计的专用 token,和普通的设备 token 不同,不能混用。全链路涉及两种:

Token 类型 监听事件 用途
Activity token activityTokenReceived 更新已存在的 Live Activity(绑定具体活动实例,生命周期内可能变化)
Push-to-start token activityPushToStartTokenReceived 远程启动新的 Live Activity(iOS 17.2+)

用 addVoltraListener 订阅后,把 token 上报到你的后端:

import { addVoltraListener } from '@use-voltra/ios-client'

// 更新 token:绑定到具体的 Live Activity
const s1 = addVoltraListener('activityTokenReceived', ({ activityName, pushToken }) => {
  sendTokenToServer({ activityName, token: pushToken, type: 'update' })
})

// push-to-start token:用于远程启动新活动
const s2 = addVoltraListener('activityPushToStartTokenReceived', ({ pushToStartToken }) => {
  sendTokenToServer({ token: pushToStartToken, type: 'start' })
})

仓库示例工程里已经写好了完整的事件监听样板,可以直接抄:useVoltraEvents.ts。更多事件(状态变化 stateChange、用户交互 interaction)的说明在 events.md。

第三步:renderLiveActivityToString 服务端渲染

这是 Voltra 服务端渲染的核心。@use-voltra/ios-server 包让你在 Node.js 后端直接用同一套 Voltra React 组件渲染 UI(注意:该包仅限服务端使用,不能打进 React Native bundle)。

import { Voltra, renderLiveActivityToString } from '@use-voltra/ios-server'

const uiJsonData = await renderLiveActivityToString({
  lockScreen: (
    <Voltra.VStack style={{ padding: 16, backgroundColor: '#101828' }}>
      <Voltra.Symbol name="airplane" tintColor="#38BDF8" />
      <Voltra.Text style={{ color: '#F8FAFC', fontSize: 18 }}>UA2645 登机中</Voltra.Text>
    </Voltra.VStack>
  ),
})

renderLiveActivityToString 接收 LiveActivityVariants(包含 lockScreen、island、supplementalActivityFamilies 等变体),内部先用 Voltra 渲染器把 JSX 转成紧凑的 UI JSON,再做 Brotli 压缩 + base64 编码,返回一个可以直接嵌进 APNS payload 的字符串。源码实现见 packages/ios-server/src/index.ts。

第四步:发送 APNS 推送(update / start / end)

必需的 APNS 头

apns-push-type: liveactivity
apns-topic: com.example.myapp.push-type.liveactivity

apns-topic 用你的 bundle ID 加上 .push-type.liveactivity 后缀。

三种事件一表看懂

场景 aps.event 关键附加字段 目标 token
更新现有活动 update content-state、timestamp Activity token
远程启动活动(iOS 17.2+) start attributes-type、attributes、alert Push-to-start token
结束活动 end dismissal-date Activity token

update 事件示例(uiJsonData 即上一步的返回值):

{
  "aps": {
    "event": "update",
    "content-state": { "uiJsonData": "ixOAeyJ2IjoxLCJscyI6eyJ0IjowLCJjIjoiSGVsbG8hIn19fQM=" },
    "timestamp": 1764145755
  }
}

⚠️ 4 KB 硬限制:ActivityKit 对 payload 有约 4 KB 的大小上限。保持 UI 精简、避免深层嵌套组件树和过多样式修饰,renderLiveActivityToString 内部也会做预算校验,超限时直接报错提醒你。

🚀 push-to-start:不发一行代码,远程"凭空"启动 Live Activity

这是全链路最魔幻的一环:App 完全没打开,服务端一条推送就能在用户锁屏上"变出"一个 Live Activity(iOS 17.2+)。

start 事件比普通 update 多三个字段:

{
  "aps": {
    "event": "start",
    "content-state": { "uiJsonData": "ixOAeyJ2Ijox..." },
    "attributes-type": "VoltraAttributes",
    "attributes": {
      "name": "some-name",
      "deepLinkUrl": "app://some-deep-link-url"
    },
    "timestamp": 1764145755,
    "alert": {
      "title": "Driver arrived",
      "body": "Ready for pickup"
    }
  }
}
  • attributes-type:固定为 "VoltraAttributes"(使用 Dynamic Live Activities 时为插件生成的专属类型名)
  • attributes.name:你自己定义的活动名,任意字符串
  • alert:push-to-start 场景必填,用来告知用户"来了个新活动"
  • 用第二步收集的 push-to-start token 作为目标设备

Voltra Live Activity 服务端渲染启动效果:锁屏实时活动预览

如果项目使用的是 Dynamic Live Activities(渲染定义随 App 打包、只推 props 的实验特性),attributes-type 要用插件按定义 ID 生成的类型名(如 order_finished → VoltraOrderFinishedLiveActivityAttributes),且推送的 content-state.props 必须是完整的 JSON 对象。详见 dynamic-live-activities.md。

📡 iOS 18+ 广播推送:一次推送,万人更新

体育比分、航班状态这类"多人看同一事件"的场景,逐个设备发 token 太浪费。iOS 18 起支持广播推送(Broadcast Push):服务端向一个共享 channel 推一次,所有订阅该 channel 的 Live Activity 同时更新。

开启方式:

  1. 在 Apple Developer 账号的 App ID 上开启 Broadcast Capability(每个 App 最多 10,000 个 channel)
  2. 服务端通过 APNs 创建 channel 拿到 channel ID
  3. App 启动活动时传入 channelId 完成订阅:
const activityId = await startLiveActivity(variants, {
  activityName: 'flight-ua2645',
  channelId: 'CTrNsYq/Ee8AALLzHQaVlA==',
})

发送广播:POST 到 /4/broadcasts/apps/<bundle.id>,Header 带上 apns-channel-id: <Channel ID>,payload 结构与单设备 update 完全一致。低版本 iOS 上 Voltra 会自动回退到 token 推送,无需你处理兼容。

Voltra Live Activity 广播推送共享内容示例:正在播放的音乐卡片

对比维度 单设备 token 广播 channel
服务端发送量 每设备一条 每 channel 一条
适用场景 订单、打车等个性化内容 比分、航班等共享内容
iOS 版本要求 16.4+ 18+

⚠️ 三个新手最容易踩的坑

1. 后台 30 秒窗口期

iOS 可能为了刷新 token 把你的 App 在后台唤醒,但只有约 30 秒的处理时间。用 useIsHeadless() 判断是否处于 headless(后台无界面)模式——此时千万不要挂载主界面组件树,否则资源消耗过大可能被系统直接杀掉,token 反而没上报成功。

2. token 会在生命周期内变化

Activity token 是绑定具体活动实例的,且可能在中途更新。所以监听 activityTokenReceived 要尽早注册(App 入口或根组件),收到新 token 立即上报覆盖旧值。

3. 监听器要清理

所有 addVoltraListener 返回的 subscription 记得在 useEffect 的 cleanup 里调用 .remove(),防止内存泄漏。

📚 关键文件速查

内容 路径
服务端推送官方指南(本文主要依据) website/docs/v2/ios/development/server-side-updates.md
事件系统(token / 状态 / 交互) website/docs/v2/ios/development/events.md
renderLiveActivityToString 实现 packages/ios-server/src/index.ts
推送流程内部参考 skills/voltra/references/push-flow.md
iOS 服务端更新规则参考 skills/voltra/references/ios-server-updates.md
示例工程事件监听样板 example/hooks/useVoltraEvents.ts
Dynamic Live Activities(props 直推) website/docs/v2/ios/development/dynamic-live-activities.md

总结

至此你已经走通了 Voltra 服务端推送更新的全链路:插件开启 APNS → App 收集双 token → renderLiveActivityToString 服务端渲染 → APNS 三事件下发 → iOS 18 广播扩量。整个过程你写的全是 React 组件和 Node.js 代码,Swift 一行不用碰,Live Activity 的锁屏 UI、灵动岛布局和灵动岛展开态都由同一个 LiveActivityVariants 对象统一描述。先按本文四个步骤跑通最小可用链路,再根据业务在 push-to-start 与广播推送上做扩展即可。

登录后查看全文
voltra