小程序 HCE 发消息教程｜时序错误码与安全边界｜刷卡失败也能落客进场 – MPForge
直接回答：这是一篇给已通过 HCE 立项评估的开发团队的小程序 HCE 发消息教程：核心是把启停时序、错误码映射和失败降级做成闭环——刷卡失败时顾客能立刻转二维码或人工通道进场，而不是盯着一串看不懂的错误码。试点门禁项目里，HCE 失败转码核销占比约 22%，正因为降级在，入场才没断过。
一、发消息的前提：资质与场景在上一关就验完
先划边界：HCE 发消息只服务已具备卡模拟资质、且场景经过论证的项目，它不是通用通信通道。一个常见误会是把 HCE 当普通蓝牙或数据通道用——传输能力完全不是它的设计目标，文档也不在一个体系里，混用只会把联调拖进泥潭。还有一条合规边界：消息内容里禁止携带明文的敏感号段，卡号、证件号这类字段要么不出现在消息里，要么用临时凭据替代。开与不开的资质评估见 HCE 卡模拟开启教程，本文承接其后的联调与上线环节。门禁场景的整体方案可对照 门禁核销场景。
二、时序与错误码：把「可降级」写进状态机
发消息环节最贵的不是接口难调，而是错误发生后用户没有出路。时序上盯两处：进入页面先确认权限与卡模拟状态再收发消息；切后台、离开页面、通话打断都要停干净，残留状态会让下一次启动静默失败。错误码侧做一张映射表——每个平台错误码对应一句用户能懂的动作指令：
| 检查项 | 达标口径 | 常见错误 |
|---|---|---|
| 启停时序 | 权限先行、收发有序、离开即停 | 切后台未停，下次启动失败 |
| 错误码映射 | 每个错误码配一句可执行的用户文案 | 把错误码原文直接弹给顾客 |
| 降级出口 | 失败即引导转二维码核销或人工通道 | 失败后停在错误页没出路 |
| 消息内容 | 临时凭据替代敏感号段，明文不进消息 | 明文卡号直接塞进消息体 |
| 验收口径 | 失败降级后顾客能完成入场才算通过 | 只验成功路径 |
降级文案的写法有讲究：不解释技术原因，直接给动作——「本次刷卡未成功，请出示页面上的二维码由店员扫码」，一句话覆盖启动失败、读卡失败、超时三类场景。
三、验收怎么算通过：顾客能进场才是终点
验收口径只有一条：任何失败路径下，顾客最终都能完成入场。演练清单至少包含三组：启动失败（权限被拒、机型不支持）、读卡失败（读卡器超时、消息传输中断）、打断失败（通话进来、切后台返回）。每组演练都走到终点——二维码扫出来、人工核销放行——才算闭环。试点门禁项目上线后统计：约 22% 的入场走了失败转码路径，如果没有提前演练，这个比例就是 22% 的顾客卡在门口。弱网、拒权、支付取消三条异常路径同样要进提审前用例，验收入场闭环的思路与 扫码核销教程 一致。
四、落地步骤：五步做稳发消息链路
顺序：先映射表，后联调，最后演练降级。按这五步执行：
- 确认资质边界：再次核对场景资质与页面描述一致，无资质项目在此止步。
- 写错误码映射表：收集平台错误码，逐条配上用户文案与降级动作，表进代码仓库。
- 按时序联调：权限申请、消息收发、前后台启停按序实现，真机覆盖目标客群主流机型。
- 演练失败路径：启动、读卡、超时、打断四组场景逐一演练，验证每组都能落到二维码或人工通道。
- 提审与值守：材料与页面一致后提审，上线首周安排值守覆盖刷卡类突发，失败率数据接入看板。
五、避坑清单
三条坑两条出在「把 HCE 用错了地方」。
- 别无资质硬上：资质没过就开工，联调做得再顺也是白做，审核材料与真实页面不符是拒绝高发点。
- 别把错误码原文给用户：顾客看不懂技术错误，只看得懂下一步动作；映射表维护到上线后，新增错误码同步补。
- 别当普通蓝牙用：HCE 与 BLE 是两套能力两套文档，传输需求走蓝牙方案，别在 HCE 消息里塞大数据。
- 别让首版项目塞 HCE：餐饮、预约类首版用二维码核销，HCE 留给确实需要近场刷卡的二期论证。
六、常见问题 FAQ
普通门店需要上 HCE 发消息吗？
多数不用：二维码核销在兼容性、成本与审核友好度上都更稳，HCE 只服务门禁、交通这类近场刷卡刚需场景。
刷卡失败顾客最常见的原因是什么？
机型不支持与读卡器超时占大头，所以降级路径必须显眼：失败提示直接给出「出示二维码」的动作指令，别让顾客自己找出路。
消息里能放卡号吗？
不能放明文。用临时凭据或编号替代，敏感号段一律不进消息体，这既是安全边界也减少合规风险。
HCE 和 GEO 地理位置配置有关系吗？
没有。GEO 指地理位置配置：门店地址、经纬度、服务类目，决定附近检索展示，不是按城市做地域 SEO；近场刷卡不依赖地理位置设置。
失败率多少要报警？
按机型与时段分桶看：失败率持续高于试点基线（如 22%）时先查机型分布，某机型异常升高通常是系统版本兼容问题，先补映射表再排查读卡器。
