docs: add h5 experience and tracking specs

2026-04-05 12:45:19 +08:00
parent 527b4c78a9
commit e17dc931ba
3 changed files with 1181 additions and 4 deletions
--- a/doc/experience/H5任务页埋点与结果回传规范.md
+++ b/doc/experience/H5任务页埋点与结果回传规范.md
@@ -0,0 +1,641 @@
+# 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`
+  任务标识；非任务页面可为空
+- `pageCode`
+  H5 页面编码
+- `pageType`
+  页面类型
+- `bridgeVersion`
+  Bridge 协议版本
+- `contentSource`
+  内容来源
+- `triggerSource`
+  触发来源
+- `timestamp`
+  事件时间
+
+建议补充字段：
+
+- `userId`
+- `tenantId`
+- `variantId`
+- `resultId`
+- `deviceType`
+- `networkType`
+
+字段说明：
+
+- `contentSource`
+  建议取值：`native-card` `h5-content` `h5-task` `h5-result`
+- `triggerSource`
+  建议取值：`auto-popup` `card-cta` `map-click` `result-action`
+
+---
+
+## 5. 页面类型建议
+
+建议统一定义以下 `pageType`：
+
+- `native-content-card`
+- `h5-content-page`
+- `h5-task-page`
+- `native-result-page`
+- `h5-result-page`
+
+这样可以保证：
+
+- 原生与 H5 事件可以统一分析
+- 同一任务可横跨内容卡和任务页追踪
+- 结果页增强链不会混进地图主链事件
+
+---
+
+## 6. 原生内容卡最小事件集
+
+结合当前待办中的口径，建议先正式收口以下事件：
+
+### 6.1 `content_card_enter`
+
+表示内容卡实际展示给用户。
+
+建议时机：
+
+- 卡片完成入场动画后
+- 卡片真实可见时
+
+### 6.2 `content_card_close`
+
+表示内容卡被关闭。
+
+建议补充原因字段：
+
+- `closeReason = auto-dismiss`
+- `closeReason = user-close`
+- `closeReason = replaced`
+- `closeReason = open-h5`
+
+### 6.3 `content_card_cta_click`
+
+表示用户点击内容卡主 CTA。
+
+建议补充字段：
+
+- `ctaKey`
+- `targetType`
+- `targetPageCode`
+
+### 6.4 `result_page_enter`
+
+表示原生结果页进入。
+
+该事件用于与 H5 增强结果页做漏斗对比。
+
+---
+
+## 7. H5 页面最小事件集
+
+### 7.1 `h5_page_enter`
+
+表示 H5 页面真实进入。
+
+建议在：
+
+- 页面初始化完成
+- 基础上下文已拿到
+- 主视图可见
+
+之后触发，而不是在 `web-view` 打开瞬间就记。
+
+### 7.2 `h5_page_exit`
+
+表示 H5 页面退出。
+
+建议补充：
+
+- `exitReason = close`
+- `exitReason = back`
+- `exitReason = bridge-close`
+- `exitReason = replaced`
+- `exitReason = error`
+
+### 7.3 `h5_cta_click`
+
+表示 H5 页内关键 CTA 被点击。
+
+建议至少带：
+
+- `ctaKey`
+- `ctaLabel`
+- `taskId`
+
+### 7.4 `h5_interaction`
+
+表示任务页关键互动动作。
+
+建议只用于关键动作，不记录所有噪声操作。
+
+推荐 `actionKey`：
+
+- `start-task`
+- `take-photo`
+- `record-audio`
+- `submit-form`
+- `share`
+- `retry`
+
+---
+
+## 8. 任务生命周期事件
+
+若页面属于互动任务页，建议增加一组任务态事件：
+
+### 8.1 `task_viewed`
+
+表示用户已看到任务主体。
+
+### 8.2 `task_started`
+
+表示用户开始任务，不再只是浏览。
+
+### 8.3 `task_progressed`
+
+表示阶段性推进。
+
+适用场景：
+
+- 多步表单
+- 连续拍照
+- 多题答题
+- 分阶段收集
+
+建议带：
+
+- `stepId`
+- `stepIndex`
+- `stepStatus`
+
+### 8.4 `task_completed`
+
+表示任务完成，但不代表业务一定已成功落库。
+
+### 8.5 `task_failed`
+
+表示任务失败。
+
+建议补充：
+
+- `errorCode`
+- `errorStage`
+
+### 8.6 `task_cancelled`
+
+表示用户主动放弃任务。
+
+---
+
+## 9. `submitResult` 推荐结构
+
+建议将 `submitResult` 视为“结果层回传”，而不是普通点击埋点。
+
+推荐最小结构：
+
+```json
+{
+  "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` 建议口径
+
+建议第一阶段只正式支持：
+
+- `completed`
+- `failed`
+- `cancelled`
+- `skipped`
+
+建议解释：
+
+- `completed`
+  用户已完成任务目标
+- `failed`
+  本次任务尝试失败
+- `cancelled`
+  用户主动退出或放弃
+- `skipped`
+  允许跳过的任务被明确跳过
+
+当前不建议第一阶段就把过多中间状态做成业务落库状态。
+
+例如：
+
+- `viewed`
+- `started`
+- `progressed`
+
+这些更适合作为埋点事件，而不是最终任务结果状态。
+
+---
+
+## 11. `result` 结果对象建议
+
+不同任务类型建议分别约定 `result`：
+
+### 11.1 拍照任务
+
+```json
+{
+  "assetId": "img-001",
+  "assetType": "image",
+  "count": 1
+}
+```
+
+### 11.2 录音任务
+
+```json
+{
+  "assetId": "audio-001",
+  "assetType": "audio",
+  "durationMs": 12000
+}
+```
+
+### 11.3 表单任务
+
+```json
+{
+  "formId": "form-001",
+  "submissionId": "sub-001"
+}
+```
+
+### 11.4 问答任务
+
+```json
+{
+  "questionSetId": "quiz-001",
+  "score": 3,
+  "total": 5
+}
+```
+
+原则：
+
+- `result` 保持结构化
+- 不直接塞整页原始页面状态
+- 不把分析事件数组混进 `result`
+
+---
+
+## 12. 内容面 API 落库建议
+
+建议内容面 API 承接：
+
+- H5 页面入口鉴权
+- H5 上下文初始化
+- `submitResult` 后的业务落库
+- 上传结果对象登记
+
+建议最小落库对象至少包含：
+
+- `eventId`
+- `sessionId`
+- `controlId`
+- `taskId`
+- `attemptId`
+- `pageCode`
+- `status`
+- `resultJson`
+- `submittedAt`
+
+建议能力边界：
+
+- 内容面 API 记录任务完成事实
+- 主系统继续负责比赛核心状态
+- 不通过内容面 API 直接判定打点成功或比赛结束
+
+---
+
+## 13. 去重与幂等建议
+
+为避免重复点击、网络重试或页面重进导致重复落库，建议：
+
+### 13.1 任务尝试幂等
+
+建议以：
+
+- `sessionId`
+- `taskId`
+- `attemptId`
+
+作为一次任务尝试的幂等键。
+
+### 13.2 埋点去重
+
+建议以下事件在单次页面进入内只记一次：
+
+- `h5_page_enter`
+- `task_viewed`
+- `task_started`
+- `task_completed`
+
+### 13.3 可重复事件
+
+以下事件允许多次：
+
+- `h5_cta_click`
+- `h5_interaction`
+- `task_progressed`
+
+但建议带：
+
+- `sequence`
+- `stepId`
+- `timestamp`
+
+---
+
+## 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_enter`
+- `content_card_close`
+- `content_card_cta_click`
+- `result_page_enter`
+- `h5_page_enter`
+- `h5_page_exit`
+- `h5_cta_click`
+- `task_viewed`
+- `task_started`
+- `task_completed`
+- `task_failed`
+- `task_cancelled`
+
+以及一个正式回传动作：
+
+- `submitResult`
+
+这样已经足够支撑：
+
+- 内容卡漏斗
+- H5 页面进入漏斗
+- 任务页完成率
+- 原生页与 H5 页联动链路
+
+---
+
+## 17. 当前阶段不建议做的事
+
+- 不建议把所有按钮点击都做成正式公共事件
+- 不建议把页面内局部滚动、每次切 tab 都纳入统一业务口径
+- 不建议让 `submitResult` 兼做曝光埋点
+- 不建议让 H5 页面自己定义完全不同的一套事件命名
+- 不建议直接把原始页面表单全文落到统一分析事件里
+
+---
+
+## 18. 与现有文档的关系
+
+本规范补充收口以下文档中的未定项：
+
+- `原生与 H5 Bridge 规范`
+- `H5 增强与内容扩展层方案`
+- `混合体验架构方案`
+- `API 与发布物边界约定`
+- `MyToDo` 中已出现的内容卡与结果页事件线索
+
+定位上：
+
+- `Bridge 规范` 负责通信动作
+- 本文负责埋点口径与任务结果口径
+- 内容面 API 文档后续再细化具体落库接口
+
+---
+
+## 19. 一句话结论
+
+最适合当前项目的做法不是让 H5 自己发明一套任务体系，而是：
+
+**由主系统定义统一上下文、统一事件口径、统一结果回传结构，让 H5 只负责增强体验与任务执行。**