1. 从一次消息漏推事故说起H5离线推送到底难在哪去年年底一个做电商导购的朋友半夜给我打电话说他们H5活动页的推送出了问题。用户明明已经订阅了促销提醒App也集成了厂商推送通道但活动开始后后台显示推送任务全部成功实际到达率却不到三成。更诡异的是App在前台时消息秒到一切到后台或者进程被杀消息就像石沉大海。这个场景我太熟悉了。H5页面本身是跑在浏览器或者WebView里的它没有原生的长连接能力页面一关JavaScript的执行环境就销毁了。所以H5的“离线消息推送”本质上不是H5自己在推而是H5把推送任务委托给原生App由原生App通过厂商通道个推、厂商系统通道等去完成投递。这里面涉及三层链路H5业务层、原生桥接层、厂商推送服务层。任何一层理解不到位就会出现“后台显示成功、用户收不到”的经典问题。这篇文章就是围绕“H5 个推 厂商消息 离线推送”这条链路展开的。我会把整个方案的设计思路、核心参数、实操步骤、以及我踩过的坑全部摊开讲。适合正在做混合开发、需要给H5页面补上离线触达能力的移动端开发者和后端同学。不管你是刚接触推送的新手还是已经集成过但到达率上不去的老手应该都能从里面找到能直接抄作业的东西。2. 整体方案设计为什么H5离线推送必须走原生代理2.1 H5为什么不能自己完成离线推送先把一个根本问题说清楚H5页面能不能自己实现离线推送答案是在绝大多数App内嵌场景下不能。H5运行在WebView里它的生命周期完全依附于宿主页面。用户把App切到后台系统可能冻结WebView用户杀掉进程WebView直接销毁。这时候H5里注册的任何定时器、WebSocket、轮询逻辑全部失效。有人会说那用Service Worker加Web Push协议行不行在纯浏览器PWA场景下可以但在App内嵌WebView里Service Worker的支持程度参差不齐而且它依赖浏览器的推送服务跟App自己的厂商通道是两套体系根本没法统一管理。所以结论很明确H5负责业务逻辑和触发时机真正的离线投递必须交给原生层由原生层通过厂商通道完成。这就是“H5 个推 厂商消息”这个组合的由来。2.2 三层链路的分工与数据流我把整条链路拆成三层这样后面讲细节的时候不容易乱。层级承担角色核心职责关键产出H5业务层WebView内的页面收集用户订阅意图、触发推送请求、展示推送结果推送任务参数原生桥接层App原生代码接收H5调用、调用个推SDK、管理设备标识设备CID、推送指令厂商服务层个推服务端 厂商通道消息路由、离线存储、厂商通道投递消息到达回执数据流是这样的用户在H5页面点击“开启提醒”H5通过JSBridge调用原生方法原生层拿到当前设备的推送标识个推叫CID厂商通道叫RegId把订阅关系上报给业务后端。业务后端在需要推送时调用个推服务端API指定目标CID和消息内容。个推服务端判断设备在线状态在线走个推自有通道离线则转投厂商通道比如各手机厂商的系统级推送。厂商通道在系统层面唤醒App或者直接展示通知栏消息完成投递。这里有个关键认知离线消息的“离线”指的是App进程不在前台甚至被杀但设备本身是联网的。厂商通道之所以能投递是因为它走的是系统级长连接不依赖App进程存活。这也是为什么必须用厂商通道而不是个推自有通道——自有通道在App被杀后基本就断了。2.3 方案选型的几个关键取舍在实际落地时有几个选择需要提前想清楚不然做到一半会返工。第一个取舍是透传消息还是通知栏消息。透传消息个推叫透传厂商叫数据消息不会自动展示需要App被唤醒后自己处理适合需要自定义展示逻辑的场景。通知栏消息厂商叫通知消息由系统直接展示点击后打开App指定页面到达率更高但自定义程度低。对于H5离线推送我一般建议用通知栏消息打底保证到达透传消息作为补充做精细化运营。第二个取舍是是否统一走个推服务端。有的团队想直接对接各家厂商的服务端省掉个推这一层。理论上可行但你要自己维护多套厂商SDK、处理各家不同的鉴权和消息格式、做设备标识映射工作量巨大。个推的价值就在于把这些差异屏蔽掉你只需要对接一套API。除非你有非常特殊的定制需求否则没必要自己造这个轮子。第三个取舍是H5触发还是原生触发。H5触发灵活运营活动页可以随时改逻辑原生触发稳定不受WebView生命周期影响。我的做法是订阅关系的建立由H5触发因为入口在H5但真正的推送任务由后端统一调度不依赖H5页面当时的状态。3. 核心细节拆解设备标识、消息体与厂商通道参数3.1 设备标识体系CID、RegId与别名怎么配合推送能不能精准触达全看设备标识对不对。这套体系里有几个概念容易混我一个个说。CID是个推给每个设备分配的唯一标识App首次集成个推SDK并成功注册后SDK会回调返回CID。这个CID是设备级的卸载重装可能会变。RegId是厂商通道的设备标识比如某厂商推送服务给设备分配的ID它跟CID是两套体系个推服务端内部做了映射。别名Alias是业务层的标识比如你可以把用户ID设为别名这样推送时不用关心CID直接按别名推。但别名有个坑一个别名只能绑定一个CID如果用户换设备旧设备的绑定需要解绑否则可能推错。实操中我的建议是这样组织的H5页面在用户登录后拿到业务用户ID通过JSBridge把用户ID传给原生层原生层调用个推SDK的bindAlias方法把用户ID绑定为别名同时把CID上报给业务后端建立“用户ID - CID - 设备信息”的映射表这样后端推送时有两种选择按别名推简单但要注意解绑或者按CID推精准但需要自己维护映射。我一般用CID推因为可控性更强。注意别名绑定是异步的绑定成功有回调。不要在绑定后立刻推送否则可能因为绑定还没生效导致推送失败。稳妥做法是绑定成功后上报后端后端确认收到再允许推送。3.2 消息体结构H5需要的字段怎么塞进去H5离线推送的消息体除了标准的标题、内容还需要携带H5页面需要的参数比如跳转的URL、活动ID、埋点信息。这些参数怎么传是个技术活。个推的通知栏消息支持自定义字段一般放在payload或者extra里。我的做法是定义一个统一的消息结构{ title: 您关注的商品降价了, content: 点击查看详情, payload: { jump_type: h5, jump_url: https://example.com/activity?id123, activity_id: 123, track_id: push_20240101_001 } }原生层收到推送后解析payload如果是h5类型就打开一个WebView加载jump_url同时把activity_id和track_id作为参数拼在URL后面方便H5页面做埋点和业务处理。这里有个细节payload有大小限制。不同厂商通道对消息体大小限制不同普遍在2KB到4KB之间。如果你的H5参数很多建议只传关键ID具体数据让H5页面自己去后端拉。我见过有人把整个商品列表塞进payload结果消息被厂商通道截断排查了半天。3.3 厂商通道的关键参数配置厂商通道的配置是离线推送能否成功的关键。不同厂商的参数名称不一样但核心逻辑相通。我整理了一个对照表方便你配置时参考。配置项作用常见取值/说明通道开关控制是否启用该厂商通道在个推控制台和App代码里都要开应用标识厂商平台分配的应用ID在厂商开发者平台申请应用密钥用于服务端鉴权保密不要硬编码在客户端消息分类区分通知消息和透传消息通知消息到达率高优先用离线保留时长设备离线时消息保留多久一般最长7天按需设置推送时段限制推送时间避免夜间打扰提升用户体验配置时最容易出错的是应用签名和包名。厂商通道会校验App的签名如果签名不匹配消息会被丢弃。我在测试阶段遇到过签名用debug、正式包用release导致测试环境能推、正式环境推不了的情况。所以一定要确保测试包和正式包的签名配置一致或者在厂商平台同时配置两个签名。提示厂商通道的配置修改后有的需要重新安装App才能生效有的需要等待几分钟。改完配置不要立刻下结论说“没用”先等一等或者重装一次。4. 实操过程从H5触发到消息到达的完整实现4.1 H5侧订阅触发与JSBridge调用H5侧的核心任务是两件事收集用户订阅意图以及通过JSBridge把意图传给原生层。先看订阅触发。用户点击“开启提醒”按钮时H5需要判断当前环境是否支持推送。判断逻辑可以这样写function checkPushSupport() { // 判断是否在App内嵌环境 const isInApp /myapp/i.test(navigator.userAgent); if (!isInApp) { return { supported: false, reason: not_in_app }; } // 判断JSBridge是否注入成功 if (!window.MyAppBridge || !window.MyAppBridge.requestPushPermission) { return { supported: false, reason: bridge_not_ready }; } return { supported: true }; }判断通过后调用原生方法请求推送权限并绑定订阅关系function subscribePush(userId, activityId) { const params { userId: userId, activityId: activityId, subscribeTime: Date.now() }; window.MyAppBridge.requestPushPermission( JSON.stringify(params), function(result) { // 原生层回调result包含success和cid if (result.success) { console.log(订阅成功CID:, result.cid); // 可以在这里上报后端确认订阅关系 } else { console.log(订阅失败:, result.message); } } ); }这里的关键是回调处理。原生层的权限请求是异步的用户可能同意也可能拒绝H5必须等回调才能知道结果。我见过有的实现直接假设用户会同意结果用户拒绝后H5还显示“订阅成功”体验很差。4.2 原生侧个推SDK初始化与权限处理原生侧的工作分三块SDK初始化、权限请求、消息接收处理。SDK初始化一般在App启动时做以Android为例iOS逻辑类似API名称不同// 在Application的onCreate中初始化 PushManager.getInstance().initialize(this.getApplicationContext(), new PushService());初始化后个推SDK会异步返回CID通过回调拿到Override public void onReceiveClientId(Context context, String clientId) { // clientId就是CID上报给业务后端 reportCidToServer(clientId); }权限请求这块Android 13以后通知权限需要动态申请iOS也需要用户授权。原生层收到H5的请求后先检查权限状态没有就申请申请结果通过回调返回给H5。public void requestPushPermission(String paramsJson, Callback callback) { // 解析H5传来的参数 JSONObject params new JSONObject(paramsJson); String userId params.optString(userId); // 检查通知权限 if (!hasNotificationPermission()) { requestNotificationPermission(new PermissionCallback() { Override public void onResult(boolean granted) { if (granted) { bindAliasAndCallback(userId, callback); } else { callback.invoke(buildResult(false, permission_denied, null)); } } }); } else { bindAliasAndCallback(userId, callback); } }绑定别名并回调private void bindAliasAndCallback(String userId, Callback callback) { PushManager.getInstance().bindAlias(context, userId); String cid PushManager.getInstance().getClientid(context); callback.invoke(buildResult(true, success, cid)); }4.3 服务端消息下发与厂商通道路由服务端的工作是接收业务推送请求调用个推API下发消息。个推的服务端API支持指定推送目标、消息内容、厂商通道策略等。一个典型的推送请求参数结构{ audience: { cid: [目标设备CID] }, push_message: { notification: { title: 您关注的商品降价了, body: 点击查看详情, click_type: intent, intent: intent:#Intent;actionandroid.intent.action.VIEW;S.urlhttps://example.com/activity?id123;end } }, push_channel: { android: { ups: { notification: { title: 您关注的商品降价了, body: 点击查看详情, click_type: url, url: https://example.com/activity?id123 } } }, ios: { aps: { alert: { title: 您关注的商品降价了, body: 点击查看详情 }, payload: { jump_url: https://example.com/activity?id123 } } } } }这里有几个关键点。audience指定推送目标可以用CID、别名、标签等。push_message是个推自有通道的消息体push_channel是厂商通道的消息体。个推服务端会根据设备状态自动选择走哪个通道。厂商通道的click_type要特别注意。Android厂商通道一般支持intent、url、startapp等类型。如果H5页面需要打开WebView用url类型最方便系统会直接用浏览器或者App内WebView打开。但如果你想控制打开方式比如必须在App内打开就需要用intent类型自己构造Intent。注意不同厂商对click_type的支持程度不同有的厂商不支持url类型只能startapp然后App自己处理。所以稳妥做法是统一用startapp把跳转信息放在payload里App启动后自己解析并打开对应H5页面。4.4 消息到达后的H5页面处理消息点击后App被唤醒原生层拿到payload打开H5页面。H5页面需要从URL参数里解析出业务信息完成页面渲染和埋点。// H5页面加载时解析参数 function parsePushParams() { const urlParams new URLSearchParams(window.location.search); const activityId urlParams.get(activity_id); const trackId urlParams.get(track_id); if (activityId) { // 加载活动数据 loadActivity(activityId); } if (trackId) { // 上报推送点击埋点 reportTrack(trackId, click); } }埋点这块很重要它是评估推送效果的依据。我一般会埋三个点推送下发、消息到达、用户点击。下发由服务端记录到达由厂商通道回执提供点击由H5上报。三个数据一对比就能算出到达率和点击率知道问题出在哪一环。5. 常见问题与排查技巧实录5.1 到达率低的排查思路到达率低是最常见的问题排查要按链路逐段来。先确认消息是否成功下发。看个推服务端的推送记录如果显示“下发成功”说明服务端没问题。如果显示失败看错误码常见的有目标CID无效、消息体格式错误、频率超限等。再确认厂商通道是否配置正确。在个推控制台看厂商通道的状态如果显示“未配置”或者“配置异常”消息就只能走个推自有通道App离线时自然收不到。配置检查项包括应用标识、应用密钥、包名、签名。然后确认设备是否真的离线。有的测试设备虽然App在后台但个推自有通道还活着消息走了自有通道看起来“到达”了但实际不是厂商通道的功劳。要测试厂商通道必须确保App进程被杀或者设备处于厂商通道才能触达的状态。最后确认用户是否关闭了通知权限。这个最容易被忽略。用户关了通知权限消息到了系统层也不会展示。可以在App里提供一个检测入口引导用户开启。5.2 消息点击后跳转异常的排查跳转异常一般有几个原因。一是payload解析失败原生层拿到的payload格式跟预期不一致导致跳转参数丢失。排查方法是把原始payload打日志看看实际收到的是什么。二是URL编码问题H5的URL里带了特殊字符没有正确编码导致参数截断。三是WebView配置问题比如没有开启JavaScript或者拦截了URL加载。我遇到过一次跳转白屏排查了半天发现是H5页面的URL里带了一个#号原生层拼接参数时把#后面的内容当成了锚点导致参数丢失。后来改成用?拼接并且对参数做了encodeURIComponent问题解决。5.3 常见问题速查表问题现象可能原因排查方法解决方案后台显示成功用户收不到厂商通道未配置或配置错误检查个推控制台通道状态补全厂商配置核对签名包名App前台能收后台收不到未启用厂商通道只走了自有通道查看推送记录走的哪个通道启用厂商通道测试离线场景点击消息无反应click_type配置错误或payload丢失打印原始payload和Intent统一用startapppayload传跳转信息到达率突然下降厂商通道被限流或用户关权限查看厂商回执和权限状态调整推送频率引导开启权限别名推送推错人别名未解绑或绑定冲突检查别名绑定记录换设备时先解绑再绑定消息内容被截断payload超过大小限制检查消息体大小只传关键ID数据由H5拉取5.4 几个我踩过的坑第一个坑是测试环境用debug签名。厂商通道校验签名debug签名和release签名不一致导致测试环境能推、正式环境推不了。后来我们在厂商平台同时配置了两个签名测试和正式分开问题解决。第二个坑是CID变化后没更新。用户卸载重装AppCID会变但后端还存着旧CID推送自然失败。解决办法是在App启动时检查CID是否变化变化了就上报更新。个推SDK有CID变化的回调可以监听。第三个坑是推送频率过高被厂商限流。有的厂商通道对推送频率有限制短时间内推太多会被限流甚至封禁。我们的做法是控制推送频率同一用户一天不超过3条营销推送重要通知单独走白名单。第四个坑是H5页面在WebView里收不到JSBridge回调。原因是JSBridge注入时机问题H5页面加载太快桥还没注入就调用了。解决办法是在H5侧做重试或者原生层在页面加载完成后再注入桥并通知H5。6. 一些实操心得与后续扩展方向这套方案跑通之后我最大的体会是离线推送的难点不在技术实现而在链路的可观测性。消息从下发到到达中间经过服务端、个推、厂商通道、系统、App、H5任何一环出问题都可能导致失败。如果没有完善的日志和埋点排查起来就是盲人摸象。所以我在项目里强制要求每个环节都打点服务端记录下发日志厂商通道回执入库App记录接收日志H5记录展示和点击日志。这样一旦到达率异常能快速定位是哪一环的问题。另一个心得是不要过度依赖单一通道。个推自有通道和厂商通道各有优劣自有通道在线时快厂商通道离线时稳。实际使用中要根据设备状态动态选择而不是一刀切。个推服务端已经做了这个路由但你需要确保两边都配置正确不然路由到没配置的通道就失败了。后续如果要扩展我觉得有几个方向值得做。一是推送内容的个性化根据用户画像动态生成标题和内容提升点击率。二是推送时机的智能选择分析用户活跃时段在用户最可能看手机的时候推送。三是A/B测试能力同一批用户分两组推不同内容对比效果。这些都需要在现有链路上叠加数据分析和策略层但基础的消息通道已经打通扩展起来不会太难。最后分享一个小技巧调试厂商通道时可以用厂商开发者平台提供的测试工具先验证通道是否通再集成到App里。这样能把问题范围缩小避免在App代码里反复折腾。我在项目初期就是先用厂商的测试工具确认通道没问题再排查App侧的集成省了很多时间。