H5任务页埋点与结果回传规范.md 11 KB
H5 任务页埋点与结果回传规范
文档版本：v1.0 最后更新：2026-04-05 12:36:25
本文档用于定义当前项目中，原生内容卡、H5 详情页、H5 互动任务页、增强结果页 的最小埋点口径与结果回传结构，避免后续出现“曝光、点击、任务完成、业务落库”混为一谈的情况。
核心结论：
展示埋点、交互埋点、任务结果回传必须分层定义；H5 可以上报行为与任务结果，但不能直接决定打点成功或比赛状态。
1. 目标
本文档重点解决以下问题：
- 如何统一原生内容卡与 H5 页的埋点事件口径
- 如何区分“浏览行为”与“任务完成结果”
- 如何通过
submitResult回传 H5 任务页结果 - 如何让内容面 API 稳定承接任务结果落库
- 如何保证埋点失败或回传失败时不阻断主流程
适用范围：
- 打点后原生内容卡
- 原生内容卡 CTA 进入的 H5 详情页
- H5 互动任务页
- H5 增强结果页
不适用范围：
- 打点判定本身
- 地图主链状态流转
- 高频 telemetry 主链
- 实时网关事件流替代方案
2. 边界原则
2.1 任务结果不等于比赛结果
H5 回传的任务结果只表示：
- 某个互动任务是否完成
- 某个表单是否提交
- 某个作品是否生成
- 某个增强页是否完成关键动作
它不直接表示：
- 打点是否成功
- 本局是否完赛
- 成绩是否生效
2.2 埋点事件不等于业务落库
埋点事件主要用于：
- 行为分析
- 页面漏斗观察
- 体验优化
- 运营数据统计
业务落库主要用于：
- 记录任务完成事实
- 记录作品或表单提交结果
- 记录奖励发放依据
这两者可以共用部分字段，但不能视为同一条链路。
2.3 埋点失败不阻断体验
若埋点上报失败：
- 页面仍可继续浏览
- 任务仍可继续操作
- 比赛主流程不应被中断
2.4 结果回传失败不反向控制主流程
若 submitResult 或内容面 API 落库失败：
- 不应改写打点成功状态
- 不应强制比赛中断
- 允许重试、缓存或降级提示
3. 推荐分层模型
建议将相关事件分为三层：
3.1 展示层事件
用于记录页面或卡片是否被看到。
例如：
- 内容卡进入
- H5 页面曝光
- 结果页进入
3.2 交互层事件
用于记录用户在页面中的关键操作。
例如：
- CTA 点击
- 页面关闭
- 按钮点击
- 表单提交点击
- 分享点击
3.3 结果层事件
用于记录任务是否完成，以及完成后产出的结果对象。
例如：
- 拍照任务完成
- 留言任务完成
- 答题任务完成
- 作品提交成功
4. 统一标识字段
无论是原生内容卡还是 H5 页面，建议统一携带以下字段：
eventId活动标识sessionId对局标识controlId点位标识；非点位页面可为空taskId任务标识；非任务页面可为空pageCodeH5 页面编码pageType页面类型bridgeVersionBridge 协议版本contentSource内容来源triggerSource触发来源timestamp事件时间
建议补充字段：
userIdtenantIdvariantIdresultIddeviceTypenetworkType
字段说明：
contentSource建议取值：native-cardh5-contenth5-taskh5-resulttriggerSource建议取值：auto-popupcard-ctamap-clickresult-action
5. 页面类型建议
建议统一定义以下 pageType：
native-content-cardh5-content-pageh5-task-pagenative-result-pageh5-result-page
这样可以保证：
- 原生与 H5 事件可以统一分析
- 同一任务可横跨内容卡和任务页追踪
- 结果页增强链不会混进地图主链事件
6. 原生内容卡最小事件集
结合当前待办中的口径，建议先正式收口以下事件：
6.1 content_card_enter
表示内容卡实际展示给用户。
建议时机：
- 卡片完成入场动画后
- 卡片真实可见时
6.2 content_card_close
表示内容卡被关闭。
建议补充原因字段：
closeReason = auto-dismisscloseReason = user-closecloseReason = replacedcloseReason = open-h5
6.3 content_card_cta_click
表示用户点击内容卡主 CTA。
建议补充字段：
ctaKeytargetTypetargetPageCode
6.4 result_page_enter
表示原生结果页进入。
该事件用于与 H5 增强结果页做漏斗对比。
7. H5 页面最小事件集
7.1 h5_page_enter
表示 H5 页面真实进入。
建议在：
- 页面初始化完成
- 基础上下文已拿到
- 主视图可见
之后触发，而不是在 web-view 打开瞬间就记。
7.2 h5_page_exit
表示 H5 页面退出。
建议补充：
exitReason = closeexitReason = backexitReason = bridge-closeexitReason = replacedexitReason = error
7.3 h5_cta_click
表示 H5 页内关键 CTA 被点击。
建议至少带：
ctaKeyctaLabeltaskId
7.4 h5_interaction
表示任务页关键互动动作。
建议只用于关键动作，不记录所有噪声操作。
推荐 actionKey：
start-tasktake-photorecord-audiosubmit-formshareretry
8. 任务生命周期事件
若页面属于互动任务页，建议增加一组任务态事件：
8.1 task_viewed
表示用户已看到任务主体。
8.2 task_started
表示用户开始任务，不再只是浏览。
8.3 task_progressed
表示阶段性推进。
适用场景：
- 多步表单
- 连续拍照
- 多题答题
- 分阶段收集
建议带：
stepIdstepIndexstepStatus
8.4 task_completed
表示任务完成，但不代表业务一定已成功落库。
8.5 task_failed
表示任务失败。
建议补充：
errorCodeerrorStage
8.6 task_cancelled
表示用户主动放弃任务。
9. submitResult 推荐结构
建议将 submitResult 视为“结果层回传”，而不是普通点击埋点。
推荐最小结构：
{
"id": "req-002",
"channel": "request",
"type": "submitResult",
"payload": {
"taskId": "task-photo-control-3",
"taskType": "photo-checkin",
"attemptId": "attempt-001",
"status": "completed",
"pageCode": "task-control-3-photo",
"controlId": "control-3",
"result": {
"assetId": "img-001"
}
}
}
字段建议：
taskId任务标识taskType任务类型attemptId一次任务尝试标识status任务结果状态pageCode页面编码controlId关联点位result结构化结果对象
10. submitResult.status 建议口径
建议第一阶段只正式支持：
completedfailedcancelledskipped
建议解释：
completed用户已完成任务目标failed本次任务尝试失败cancelled用户主动退出或放弃skipped允许跳过的任务被明确跳过
当前不建议第一阶段就把过多中间状态做成业务落库状态。
例如：
viewedstartedprogressed
这些更适合作为埋点事件，而不是最终任务结果状态。
11. result 结果对象建议
不同任务类型建议分别约定 result：
11.1 拍照任务
{
"assetId": "img-001",
"assetType": "image",
"count": 1
}
11.2 录音任务
{
"assetId": "audio-001",
"assetType": "audio",
"durationMs": 12000
}
11.3 表单任务
{
"formId": "form-001",
"submissionId": "sub-001"
}
11.4 问答任务
{
"questionSetId": "quiz-001",
"score": 3,
"total": 5
}
原则：
result保持结构化- 不直接塞整页原始页面状态
- 不把分析事件数组混进
result
12. 内容面 API 落库建议
建议内容面 API 承接：
- H5 页面入口鉴权
- H5 上下文初始化
submitResult后的业务落库- 上传结果对象登记
建议最小落库对象至少包含：
eventIdsessionIdcontrolIdtaskIdattemptIdpageCodestatusresultJsonsubmittedAt
建议能力边界：
- 内容面 API 记录任务完成事实
- 主系统继续负责比赛核心状态
- 不通过内容面 API 直接判定打点成功或比赛结束
13. 去重与幂等建议
为避免重复点击、网络重试或页面重进导致重复落库，建议：
13.1 任务尝试幂等
建议以：
sessionIdtaskIdattemptId
作为一次任务尝试的幂等键。
13.2 埋点去重
建议以下事件在单次页面进入内只记一次：
h5_page_entertask_viewedtask_startedtask_completed
13.3 可重复事件
以下事件允许多次：
h5_cta_clickh5_interactiontask_progressed
但建议带：
sequencestepIdtimestamp
14. 推荐上报时机
建议的最小时机如下：
14.1 原生内容卡
- 卡片入场完成后：
content_card_enter - 用户关闭时：
content_card_close - CTA 点击时：
content_card_cta_click
14.2 H5 内容页 / 任务页
- 页面首屏稳定后：
h5_page_enter - 任务主体真正可见后：
task_viewed - 用户开始实际互动后：
task_started - 关键阶段完成后：
task_progressed - 调用
submitResult(completed)前：task_completed
14.3 结果页
- 原生结果页进入：
result_page_enter - H5 增强结果页进入：
h5_page_enter
15. fallback 规则
15.1 H5 打不开
- 记一条
h5_open_failed - 回退到原生内容卡或原生结果页
15.2 埋点接口失败
- 允许静默失败或批量补报
- 不阻断用户当前操作
15.3 submitResult 失败
- 页面应拿到明确失败回执
- 允许用户重试
- 原生可决定是否保留最小完成提示
15.4 Bridge 未就绪
- 禁用依赖原生能力的操作
- 仅保留静态浏览能力
16. 第一阶段建议收口的正式事件
建议第一阶段只先正式收口以下事件，不一开始扩太大：
content_card_entercontent_card_closecontent_card_cta_clickresult_page_enterh5_page_enterh5_page_exith5_cta_clicktask_viewedtask_startedtask_completedtask_failedtask_cancelled
以及一个正式回传动作：
submitResult
这样已经足够支撑：
- 内容卡漏斗
- H5 页面进入漏斗
- 任务页完成率
- 原生页与 H5 页联动链路
17. 当前阶段不建议做的事
- 不建议把所有按钮点击都做成正式公共事件
- 不建议把页面内局部滚动、每次切 tab 都纳入统一业务口径
- 不建议让
submitResult兼做曝光埋点 - 不建议让 H5 页面自己定义完全不同的一套事件命名
- 不建议直接把原始页面表单全文落到统一分析事件里
18. 与现有文档的关系
本规范补充收口以下文档中的未定项：
原生与 H5 Bridge 规范H5 增强与内容扩展层方案混合体验架构方案API 与发布物边界约定MyToDo中已出现的内容卡与结果页事件线索
定位上：
Bridge 规范负责通信动作- 本文负责埋点口径与任务结果口径
- 内容面 API 文档后续再细化具体落库接口
19. 一句话结论
最适合当前项目的做法不是让 H5 自己发明一套任务体系，而是：
由主系统定义统一上下文、统一事件口径、统一结果回传结构，让 H5 只负责增强体验与任务执行。