Voltra 服务端推送更新全链路:APNS、push-to-start 与 renderLiveActivityToString 服务端渲染手把手教程
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 的服务端推送全链路让更新主动权交给后端:
- App 内收集 token:
addVoltraListener监听 token 事件并上报服务端; - 服务端渲染 UI:
renderLiveActivityToString把 React 组件渲染成压缩后的 JSON 字符串; - APNS 下发:把 UI 放进
aps.content-state,按update/start/end三种事件推送; - 系统级刷新:即使 App 完全没运行,iOS 也会自动更新锁屏与灵动岛 UI。
如上图,航班状态(起飞时间、登机口、延误)正是典型的"服务端推送更新"场景:后端一更新,锁屏即时刷新,App 全程无需在前台。
第一步:在 Voltra 插件中启用 APNS 推送
服务端推送的前提是在 app.json(或 app.config.js)中开启 enablePushNotifications。Voltra 的 Expo config 插件会自动帮你完成大部分 Xcode 配置:
- 添加
aps-environmententitlement(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 作为目标设备
如果项目使用的是 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 同时更新。
开启方式:
- 在 Apple Developer 账号的 App ID 上开启 Broadcast Capability(每个 App 最多 10,000 个 channel)
- 服务端通过 APNs 创建 channel 拿到 channel ID
- 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 推送,无需你处理兼容。
| 对比维度 | 单设备 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 与广播推送上做扩展即可。

