642 lines
11 KiB
Markdown
642 lines
11 KiB
Markdown
# 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 只负责增强体验与任务执行。**
|