HarmonyOS 7 Push Kit 穿戴实况窗推式下发实践

鸿蒙专家

HarmonyOS 7.0（API 26）在 Push Kit 中补齐了 Wearable 设备实况窗的推式下发能力。业务服务器可以绕过手机侧后台保活，直接通过华为 Push 服务器把状态变更 payload 点对点下发到穿戴设备。这对网约车、外卖配送、航班登机等长链路状态追踪场景，意味着跨端实况窗同步从依赖手机转发，转向云端直推。

跨端状态同步的工程难点在于：如果手机端通过蓝牙向手表同步数据，会面临手机后台被挂起、蓝牙连接不稳定、状态延迟更新等问题；Wearable 设备电量小，频繁蓝牙唤醒和本地渲染会快速耗电。Push Kit 云端直推的设计，正是针对这些约束的破局点。

一、工程分层与职责隔离
原文示例把实况窗本地调度、Push Kit 信使、跨端状态解析严格分层：PushTokenManager 负责申请维护跨端 Push Token，处理 Token 漂移与失效；LiveViewContextManager 管理实况窗创建、更新、销毁，对接 SystemUI；WearableSyncManager 处理手表端 UI 结构适配和大屏到小屏数据降维；QualityOfServiceManager 根据电量和网络状态调整推送策略。models 定义行程、外卖、航班状态协议，workers 处理 Push Kit 静默透传与状态更新，utils 封装 hilog 日志和设备硬件规格读取。这种结构把 UI 渲染层与网络推式解耦，后续 API 升级只需修改对应 Manager。

二、Token 双轨制与多设备鉴权
Push Kit 在 API 26 中允许通过指定 deviceType 获取目标设备专属 Token。主设备 Token 申请不传 deviceType，系统自动识别手机；Wearable Token 申请显式传入 pushService.DeviceType.WEARABLE。系统底层通过低功耗蓝牙或局域网向手表发起能力查询，开发者不用手动建立蓝牙 Socket 交换标识，也不用关注分包、解包与重传。

2. const reqInfo: pushService.TokenReqInfo = {
3.   senderId: PushConstants.SENDER_ID,
4.   deviceType: pushService.DeviceType.WEARABLE
5. };
6. const token = await pushService.getToken(reqInfo);

复制代码

Wearable Token 获取失败可能来自手表未开蓝牙、省电模式不可达、系统版本不支持。原文建议对 Wearable Token 失败采用降级策略，不阻断主流程；Token 获取成功后应持久化，并触发与业务服务器绑定。日志中不能直接打印完整 Token，可只打印长度验证。

三、Payload 协议：wearable_config 与视图解耦
服务端组装 Push Payload 时，不能把手机实况窗模板直接推给手表。Push Kit 服务端 REST API 为实况窗事件增加 wearable_config 结构体，定义穿戴设备上的专属展现形态。其中 template_id 是重点，系统会在穿戴设备上寻找预置 UI 模板进行数据绑定；如果填入设备不支持或手机端独有模板，渲染引擎会报错并丢弃事件。capsule_state 控制手表顶部状态栏胶囊的精简展示，决定抬腕第一秒能否看到核心状态。vibration_pattern 允许后台无感刷新时不振动，关键节点用 SUCCESS_SHORT 振动补足视觉遗漏。fallback_strategy 定义极端省电或复杂实况窗无法拉起时的降级策略，DISMISS 表示无法展示则丢弃不打扰，也可设为 CONVERT_TO_NOTIFICATION 转为普通文本通知。
通过分离 live_view_data 业务语义与 wearable_config UI 表现语义，不同系统版本的手表也能按业务数据降级渲染，保证核心状态可见。

四、后台处理：LiveViewUpdateExtensionAbility 与 QoS
当 Push 消息触达设备，若不涉及复杂业务逻辑，系统可直接根据 Payload 刷新实况窗；若涉及自定义参数计算，可通过 ExtensionAbility 拦截 Push 消息并在后台无感处理。API 26 中，实况窗动态更新通常由 LiveViewUpdateExtensionAbility 处理，这是为高频短时效任务设计的轻量级组件。
在 onReceiveMessage 中解析 status、progress、estimated_time、order_id 等字段，缺关键字段直接丢弃并上报。构建 liveViewManager.LiveViewData 后调用 liveViewManager.updateLiveView。这里执行时间受系统严格管控，通常几秒内必须返回，禁止发起网络请求或长耗时磁盘读写。onDestroyView 触发时，要清理定时器、位置监听器或状态缓存，避免隐形内存溢出。

2. const updatePayload: liveViewManager.LiveViewData = {
3.   id: `trip_live_view_${orderId}`,
4.   event: 'UPDATE',
5.   content: {
6.     title: tripStatus === 'ARRIVED' ? '司机已到达指定地点' : '司机正在全力赶来',
7.     text: `系统预计还有 ${estimatedTime || '未知时间'}`,
8.     progress: progressVal ?? 0
9.   }
10. };
11. liveViewManager.updateLiveView(updatePayload);

复制代码

外卖配送场景中，45 分钟内骑手端可能每 10 秒上报一次位置。如果几百次更新全部通过 Push 下发到手表实况窗，会触发系统反滥用风控，拉黑推送通道。正确做法是阶段性稀疏加关键节点密集的合并下发，既保证送达瞬间强提醒，又降低等待期无效功耗。

航班登机场景网络往往糟糕。Push Kit 底层有保底机制：如果手表独立网络（eSIM）不可用，但手机网络可用且两设备蓝牙相连，云端网关会把 Payload 路由到手机，由手机底层分布式软总线代为投递。业务端要正确设置 fallback_strategy，保证渲染失败时信息仍能通过系统通知栏触达。

五、防翻车：Token 漂移与胶囊文案截断
穿戴设备重置、解绑后重新配对、恢复出厂设置，都会导致 Wearable Token 漂移或永久失效。服务端继续向旧 Token 下发，会收到 404 Not Found 或 Unregistered Device，最终触发推送服务端熔断降级。防御策略：在 EntryAbility 的 onWindowStageCreate 中，或定期用 WorkScheduler 检查手机与手表连接状态；监听设备解绑或重新配对的系统底层广播，主动调用 pushService.getToken 刷新并上报新 Wearable Token。服务端建立失效剔除机制，某 Token 连续返回不可达错误超过 3 次，先标记隔离失效，停止下发，等客户端心跳重连后用新 Token 覆盖。
另一个隐蔽问题是胶囊文案截断。测试圆形表盘 Wearable 设备时，wearable_config.capsule_state.text 下发超过 8 个中文字符，受圆形屏幕边缘曲率弧度物理限制，文字会被生硬截断。因此胶囊文案应控制在极短句内，优先保留最关键状态，把补充信息放到 title、body 或 live_view_data 中。

总结：HarmonyOS 7.0 API 26 的 Push Kit Wearable 实况窗推式下发，把跨端状态同步从手机转发改为云端直推，降低后台保活和蓝牙唤醒依赖。落地时要抓住三点：Token 双轨制与失效刷新、wearable_config 模板与降级策略、ExtensionAbility 短时后台处理与 QoS 合并推送。对于外卖、网约车、航班等长链路业务，这套机制能显著改善穿戴设备上的实况窗时效与续航表现。