docs: add h5 experience and tracking specs
This commit is contained in:
641
doc/experience/H5任务页埋点与结果回传规范.md
Normal file
641
doc/experience/H5任务页埋点与结果回传规范.md
Normal file
@@ -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 只负责增强体验与任务执行。**
|
||||||
536
doc/experience/H5增强与内容扩展层方案.md
Normal file
536
doc/experience/H5增强与内容扩展层方案.md
Normal file
@@ -0,0 +1,536 @@
|
|||||||
|
# H5 增强与内容扩展层方案
|
||||||
|
> 文档版本:v1.0
|
||||||
|
> 最后更新:2026-04-05 12:33:59
|
||||||
|
|
||||||
|
本文档用于明确当前项目中,如何通过 **H5 增强层** 承接高变化、高定制的内容与互动需求,同时保证主系统继续保持本地闭环、可降级、可独立管理。
|
||||||
|
|
||||||
|
核心结论:
|
||||||
|
|
||||||
|
**H5 可以做增强体验,但应作为独立内容扩展层存在;主系统继续持有打点、状态机、结果兜底与核心游戏闭环。**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 目标
|
||||||
|
|
||||||
|
本文档重点解决以下问题:
|
||||||
|
|
||||||
|
- 如何让 H5 承接详情页、互动任务页、品牌页、增强结果页
|
||||||
|
- 如何让 H5 与主系统解耦,而不是深度嵌入主流程
|
||||||
|
- 如何让 H5 页面能够独立开发、独立发布、独立回滚、独立管理
|
||||||
|
- 如何保证 H5 不可用时,比赛主流程仍然稳定可用
|
||||||
|
|
||||||
|
适用场景:
|
||||||
|
|
||||||
|
- 打点后的详情说明页
|
||||||
|
- 打点后的互动任务页
|
||||||
|
- 拍照、录音、留言、作品提交等扩展页
|
||||||
|
- 品牌化结果页与活动包装页
|
||||||
|
|
||||||
|
不适用场景:
|
||||||
|
|
||||||
|
- 地图主界面
|
||||||
|
- 打点判定
|
||||||
|
- 比赛开始 / 进行中 / 结束状态推进
|
||||||
|
- 高频实时 telemetry 主链路
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 设计原则
|
||||||
|
|
||||||
|
### 2.1 主系统本地闭环
|
||||||
|
|
||||||
|
必须继续由小程序 / 原生层负责:
|
||||||
|
|
||||||
|
- 地图与定位
|
||||||
|
- 打点判定
|
||||||
|
- 核心状态机
|
||||||
|
- 最小内容卡
|
||||||
|
- 最小结果页
|
||||||
|
- 本地缓存与断网兜底
|
||||||
|
|
||||||
|
### 2.2 H5 只做增强,不做状态拥有者
|
||||||
|
|
||||||
|
H5 适合负责:
|
||||||
|
|
||||||
|
- 富图文详情
|
||||||
|
- 互动任务
|
||||||
|
- 品牌包装
|
||||||
|
- 表单与作品提交
|
||||||
|
- 增强结果页
|
||||||
|
|
||||||
|
H5 不直接决定:
|
||||||
|
|
||||||
|
- 是否打点成功
|
||||||
|
- 是否比赛结束
|
||||||
|
- 是否跳点成功
|
||||||
|
- 是否修改核心规则状态
|
||||||
|
|
||||||
|
### 2.3 H5 必须独立存在
|
||||||
|
|
||||||
|
H5 页面不应作为“主系统页面的一部分代码”长期散落在业务仓里,而应逐步具备以下能力:
|
||||||
|
|
||||||
|
- 独立页面目录与版本
|
||||||
|
- 独立静态资源发布
|
||||||
|
- 独立主题与资源管理
|
||||||
|
- 独立入口配置
|
||||||
|
- 独立回滚
|
||||||
|
|
||||||
|
### 2.4 契约优先于页面实现
|
||||||
|
|
||||||
|
主系统与 H5 之间优先约定:
|
||||||
|
|
||||||
|
- 页面入口模型
|
||||||
|
- Bridge 协议版本
|
||||||
|
- 页面能力白名单
|
||||||
|
- 结果回传结构
|
||||||
|
- fallback 行为
|
||||||
|
|
||||||
|
而不是先做大量页面,再反向补协议。
|
||||||
|
|
||||||
|
### 2.5 所有增强能力都必须可降级
|
||||||
|
|
||||||
|
若 H5 打不开、Bridge 不可用、内容面 API 失败,系统应自动降级为:
|
||||||
|
|
||||||
|
- 仍显示原生内容卡
|
||||||
|
- 仍可继续比赛
|
||||||
|
- 仍可查看原生结果页
|
||||||
|
- 不阻断地图主流程
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 推荐分层
|
||||||
|
|
||||||
|
建议当前项目的体验承载层按四层理解:
|
||||||
|
|
||||||
|
### 3.1 核心游戏层
|
||||||
|
|
||||||
|
负责:
|
||||||
|
|
||||||
|
- 打点
|
||||||
|
- 地图
|
||||||
|
- GPS
|
||||||
|
- HUD
|
||||||
|
- 规则引擎
|
||||||
|
- 结果结算
|
||||||
|
|
||||||
|
这一层不依赖 H5 才能成立。
|
||||||
|
|
||||||
|
### 3.2 原生兜底体验层
|
||||||
|
|
||||||
|
负责:
|
||||||
|
|
||||||
|
- 最小内容卡
|
||||||
|
- 最小结果页
|
||||||
|
- 必要 CTA
|
||||||
|
- H5 失败时的替代展示
|
||||||
|
|
||||||
|
### 3.3 H5 内容扩展层
|
||||||
|
|
||||||
|
负责:
|
||||||
|
|
||||||
|
- 详情页
|
||||||
|
- 互动任务页
|
||||||
|
- 品牌活动页
|
||||||
|
- 增强结果页
|
||||||
|
|
||||||
|
这一层通过原生 CTA 进入,不再承担局部弹窗职责。
|
||||||
|
|
||||||
|
### 3.4 内容管理与发布层
|
||||||
|
|
||||||
|
负责:
|
||||||
|
|
||||||
|
- H5 页面入口管理
|
||||||
|
- 页面版本管理
|
||||||
|
- Bridge 白名单管理
|
||||||
|
- 主题与资源管理
|
||||||
|
- fallback 策略
|
||||||
|
- 页面发布与回滚
|
||||||
|
|
||||||
|
这一层建议长期从玩法主配置中拆出来,形成独立内容体验管理能力。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 推荐页面类型
|
||||||
|
|
||||||
|
建议第一阶段只正式支持以下几类 H5 页面:
|
||||||
|
|
||||||
|
### 4.1 内容详情页
|
||||||
|
|
||||||
|
用于:
|
||||||
|
|
||||||
|
- 打点后的补充说明
|
||||||
|
- 景点 / 点位图文介绍
|
||||||
|
- 活动详情说明
|
||||||
|
|
||||||
|
特点:
|
||||||
|
|
||||||
|
- 展示为主
|
||||||
|
- 交互较轻
|
||||||
|
- 可由原生内容卡 CTA 进入
|
||||||
|
|
||||||
|
### 4.2 互动任务页
|
||||||
|
|
||||||
|
用于:
|
||||||
|
|
||||||
|
- 拍照打卡
|
||||||
|
- 语音留言
|
||||||
|
- 问答互动
|
||||||
|
- 收集式任务
|
||||||
|
- 轻量小游戏互动
|
||||||
|
|
||||||
|
特点:
|
||||||
|
|
||||||
|
- 需要 Bridge 能力
|
||||||
|
- 需要任务结果回传
|
||||||
|
- 需要原生 fallback
|
||||||
|
|
||||||
|
### 4.3 增强结果页
|
||||||
|
|
||||||
|
用于:
|
||||||
|
|
||||||
|
- 品牌化成绩包装
|
||||||
|
- 徽章 / 分享 / 排名增强
|
||||||
|
- 作品提交后展示
|
||||||
|
|
||||||
|
特点:
|
||||||
|
|
||||||
|
- 原生结果页始终保底
|
||||||
|
- H5 只做增强版入口
|
||||||
|
|
||||||
|
### 4.4 活动包装页
|
||||||
|
|
||||||
|
用于:
|
||||||
|
|
||||||
|
- 活动专题
|
||||||
|
- 客户品牌包装
|
||||||
|
- 招募 / 说明 / 规则展示
|
||||||
|
|
||||||
|
特点:
|
||||||
|
|
||||||
|
- 可独立于局内主链存在
|
||||||
|
- 更接近内容页,而非玩法页
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 推荐运行链路
|
||||||
|
|
||||||
|
对于“打点后增强体验”,建议统一为:
|
||||||
|
|
||||||
|
```text
|
||||||
|
完成打点
|
||||||
|
-> 原生判定成功
|
||||||
|
-> 原生内容卡 / 原生短反馈
|
||||||
|
-> 用户点击 CTA
|
||||||
|
-> 打开整页 H5 详情页 / 任务页
|
||||||
|
-> H5 获取上下文并完成互动
|
||||||
|
-> H5 submitResult 回传结果
|
||||||
|
-> 原生决定后续反馈 / 结果展示
|
||||||
|
```
|
||||||
|
|
||||||
|
对于“活动浏览链路”,建议统一为:
|
||||||
|
|
||||||
|
```text
|
||||||
|
活动列表
|
||||||
|
-> 活动详情页
|
||||||
|
-> 准备页
|
||||||
|
-> 地图主链
|
||||||
|
-> 原生结果页
|
||||||
|
-> 可选进入 H5 增强结果页
|
||||||
|
```
|
||||||
|
|
||||||
|
关键点:
|
||||||
|
|
||||||
|
- H5 总是在主系统之后进入,而不是反向驱动主系统
|
||||||
|
- 打点成功必须先由原生确认
|
||||||
|
- 结果页必须始终有原生版本兜底
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 推荐配置挂接方式
|
||||||
|
|
||||||
|
当前项目建议继续沿用现有配置口径:
|
||||||
|
|
||||||
|
- `playfield.controlOverrides.<key>.autoPopup`
|
||||||
|
- `playfield.controlOverrides.<key>.contentExperience`
|
||||||
|
- `playfield.controlOverrides.<key>.clickExperience`
|
||||||
|
|
||||||
|
推荐理解:
|
||||||
|
|
||||||
|
- `autoPopup`
|
||||||
|
控制打点完成后是否先弹原生内容卡
|
||||||
|
- `contentExperience`
|
||||||
|
控制打点成功后的扩展体验入口
|
||||||
|
- `clickExperience`
|
||||||
|
控制点击点位时的补充内容入口
|
||||||
|
|
||||||
|
建议最小配置示例:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"playfield": {
|
||||||
|
"controlOverrides": {
|
||||||
|
"control-3": {
|
||||||
|
"autoPopup": true,
|
||||||
|
"contentExperience": {
|
||||||
|
"type": "h5",
|
||||||
|
"url": "https://example.com/h5/tasks/control-3",
|
||||||
|
"bridge": "content-v1",
|
||||||
|
"presentation": "fullscreen"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
建议继续坚持:
|
||||||
|
|
||||||
|
- 不让 H5 直接顶替原生即时内容弹窗
|
||||||
|
- H5 默认按整页 / 全屏容器打开
|
||||||
|
- 配置只声明入口,不让页面内部细节反向污染玩法主配置
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 推荐 Bridge 最小契约
|
||||||
|
|
||||||
|
H5 与主系统之间建议继续保持最小协议:
|
||||||
|
|
||||||
|
### 7.1 原生注入上下文
|
||||||
|
|
||||||
|
最少应包含:
|
||||||
|
|
||||||
|
- `eventId`
|
||||||
|
- `sessionId`
|
||||||
|
- `sessionStatus`
|
||||||
|
- `controlId`
|
||||||
|
- `bridgeVersion`
|
||||||
|
- `mode`
|
||||||
|
- `title`
|
||||||
|
- `theme`
|
||||||
|
|
||||||
|
### 7.2 H5 可请求的最小能力
|
||||||
|
|
||||||
|
第一阶段建议只开放:
|
||||||
|
|
||||||
|
- `getGameContext`
|
||||||
|
- `close`
|
||||||
|
- `takePhoto`
|
||||||
|
- `recordAudio`
|
||||||
|
- `submitResult`
|
||||||
|
|
||||||
|
### 7.3 H5 回传结果的最小结构
|
||||||
|
|
||||||
|
建议最少包含:
|
||||||
|
|
||||||
|
- `taskId`
|
||||||
|
- `status`
|
||||||
|
- `payload`
|
||||||
|
|
||||||
|
示例:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "req-002",
|
||||||
|
"channel": "request",
|
||||||
|
"type": "submitResult",
|
||||||
|
"payload": {
|
||||||
|
"taskId": "task-photo-control-3",
|
||||||
|
"status": "completed",
|
||||||
|
"payload": {
|
||||||
|
"assetId": "img-001"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7.4 协议边界
|
||||||
|
|
||||||
|
Bridge 只做:
|
||||||
|
|
||||||
|
- 上下文读取
|
||||||
|
- 能力请求
|
||||||
|
- 结果回传
|
||||||
|
|
||||||
|
Bridge 不做:
|
||||||
|
|
||||||
|
- 比赛核心状态修改
|
||||||
|
- 打点成功与否判定
|
||||||
|
- 比赛结束判定
|
||||||
|
- 地图主循环控制
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. 推荐独立管理方式
|
||||||
|
|
||||||
|
若希望 H5 真正可扩展、可维护,建议长期形成独立内容体验管理能力。
|
||||||
|
|
||||||
|
### 8.1 管理对象
|
||||||
|
|
||||||
|
建议至少管理以下对象:
|
||||||
|
|
||||||
|
- 页面入口对象
|
||||||
|
- 页面版本对象
|
||||||
|
- 页面主题对象
|
||||||
|
- 页面资源对象
|
||||||
|
- Bridge 能力白名单
|
||||||
|
- fallback 策略
|
||||||
|
|
||||||
|
### 8.2 与活动对象的关系
|
||||||
|
|
||||||
|
建议活动只绑定“已发布的体验对象摘要”,而不直接持有散装页面地址。
|
||||||
|
|
||||||
|
推荐关系:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Event
|
||||||
|
-> EventRelease
|
||||||
|
-> currentPresentation
|
||||||
|
-> currentContentBundle
|
||||||
|
-> runtime
|
||||||
|
-> H5 页面入口摘要 / 任务入口摘要
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8.3 与后台的分工
|
||||||
|
|
||||||
|
建议在后台中单列“内容体验中心”,负责:
|
||||||
|
|
||||||
|
- 原生模板
|
||||||
|
- 原生 DSL
|
||||||
|
- H5 页面入口
|
||||||
|
- Bridge 能力
|
||||||
|
- 主题配置
|
||||||
|
- 资源配置
|
||||||
|
- fallback 策略
|
||||||
|
|
||||||
|
而不是让玩法后台直接承接所有 H5 页面细节。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. 推荐发布与部署方式
|
||||||
|
|
||||||
|
H5 增强层建议按“独立静态发布物”管理。
|
||||||
|
|
||||||
|
### 9.1 页面交付形态
|
||||||
|
|
||||||
|
建议:
|
||||||
|
|
||||||
|
- H5 页面资源走静态发布物
|
||||||
|
- 上传 OSS / CDN
|
||||||
|
- 由主系统根据已发布入口打开
|
||||||
|
|
||||||
|
### 9.2 版本策略
|
||||||
|
|
||||||
|
建议每个 H5 页面具备:
|
||||||
|
|
||||||
|
- 页面编码 `pageCode`
|
||||||
|
- 页面版本 `version`
|
||||||
|
- 协议版本 `bridgeVersion`
|
||||||
|
- 状态 `draft / published / archived`
|
||||||
|
|
||||||
|
### 9.3 回滚策略
|
||||||
|
|
||||||
|
建议 H5 页面支持:
|
||||||
|
|
||||||
|
- 单页回滚
|
||||||
|
- 活动级解绑
|
||||||
|
- fallback 到原生页
|
||||||
|
|
||||||
|
这样可以做到:
|
||||||
|
|
||||||
|
- 内容改版不必改主系统发版
|
||||||
|
- 某个 H5 页出问题时可快速下线
|
||||||
|
- 玩法主链不受拖累
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. 推荐 fallback 策略
|
||||||
|
|
||||||
|
建议从一开始就明确这几类降级行为:
|
||||||
|
|
||||||
|
### 10.1 H5 页面打不开
|
||||||
|
|
||||||
|
- 回退到原生内容卡
|
||||||
|
- 允许继续比赛
|
||||||
|
|
||||||
|
### 10.2 Bridge 不可用
|
||||||
|
|
||||||
|
- 禁用扩展能力按钮
|
||||||
|
- 保留基础图文展示
|
||||||
|
|
||||||
|
### 10.3 内容面 API 异常
|
||||||
|
|
||||||
|
- 允许 H5 本地完成基础展示
|
||||||
|
- 结果回传失败时提示稍后重试或改走原生兜底
|
||||||
|
|
||||||
|
### 10.4 增强结果页不可用
|
||||||
|
|
||||||
|
- 保底显示原生结果页
|
||||||
|
- 不影响本局成绩结算与查看
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. 对当前项目的建议落地顺序
|
||||||
|
|
||||||
|
建议按以下顺序推进,而不是一开始就大规模铺 H5 页:
|
||||||
|
|
||||||
|
### 第一阶段:定住边界
|
||||||
|
|
||||||
|
- 固定“原生内容卡 + H5 整页任务页”口径
|
||||||
|
- 固定 `content-v1` / `result-v1`
|
||||||
|
- 固定 fallback 规则
|
||||||
|
|
||||||
|
### 第二阶段:跑通最小闭环
|
||||||
|
|
||||||
|
- 先跑通一个内容详情页
|
||||||
|
- 再跑通一个互动任务页
|
||||||
|
- 再跑通一个增强结果页入口
|
||||||
|
|
||||||
|
### 第三阶段:独立化管理
|
||||||
|
|
||||||
|
- 抽出 H5 页面入口管理
|
||||||
|
- 抽出 Bridge 白名单管理
|
||||||
|
- 抽出页面版本与发布记录
|
||||||
|
|
||||||
|
### 第四阶段:产品化扩展
|
||||||
|
|
||||||
|
- 再接拍照任务
|
||||||
|
- 再接留言任务
|
||||||
|
- 再接作品提交
|
||||||
|
- 再接品牌专题与增强结果页
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 12. 当前阶段不建议做的事
|
||||||
|
|
||||||
|
- 不建议继续尝试局部 H5 弹窗
|
||||||
|
- 不建议让 H5 直接参与打点判定
|
||||||
|
- 不建议让 H5 持有比赛主状态
|
||||||
|
- 不建议把 H5 页面地址直接散落在多个业务字段里长期维护
|
||||||
|
- 不建议把页面内部所有细节都硬塞进玩法主配置
|
||||||
|
- 不建议在没有 fallback 的前提下把结果页完全交给 H5
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 13. 与现有文档的关系
|
||||||
|
|
||||||
|
本方案是对以下文档的补充收口:
|
||||||
|
|
||||||
|
- `混合体验架构方案`
|
||||||
|
- `原生与 H5 Bridge 规范`
|
||||||
|
- `主流程与增强能力边界说明`
|
||||||
|
- `API 与发布物边界约定`
|
||||||
|
- `后台管理系统建设建议`
|
||||||
|
|
||||||
|
定位上:
|
||||||
|
|
||||||
|
- `混合体验架构方案` 负责总体分层
|
||||||
|
- `Bridge 规范` 负责通信契约
|
||||||
|
- 本文负责回答“H5 如何作为独立增强层长期存在并管理”
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 14. 一句话结论
|
||||||
|
|
||||||
|
最适合当前项目的 H5 方案,不是把 H5 做成主系统的一部分,而是:
|
||||||
|
|
||||||
|
**主系统持有核心闭环,H5 作为独立内容扩展层存在,通过稳定入口、稳定 Bridge、独立发布和明确 fallback 承接高变化体验。**
|
||||||
@@ -1,6 +1,6 @@
|
|||||||
# 文档索引
|
# 文档索引
|
||||||
> 文档版本:v1.6
|
> 文档版本:v1.8
|
||||||
> 最后更新:2026-04-03 22:05:00
|
> 最后更新:2026-04-05 12:36:25
|
||||||
|
|
||||||
维护约定:
|
维护约定:
|
||||||
|
|
||||||
@@ -63,6 +63,8 @@
|
|||||||
|
|
||||||
- [混合体验架构](/D:/dev/cmr-mini/doc/experience/混合体验架构方案.md)
|
- [混合体验架构](/D:/dev/cmr-mini/doc/experience/混合体验架构方案.md)
|
||||||
- [原生与 H5 Bridge 规范](/D:/dev/cmr-mini/doc/experience/原生与H5桥接规范.md)
|
- [原生与 H5 Bridge 规范](/D:/dev/cmr-mini/doc/experience/原生与H5桥接规范.md)
|
||||||
|
- [H5 增强与内容扩展层方案](/D:/dev/mini-prog/doc/experience/H5增强与内容扩展层方案.md)
|
||||||
|
- [H5 任务页埋点与结果回传规范](/D:/dev/mini-prog/doc/experience/H5任务页埋点与结果回传规范.md)
|
||||||
|
|
||||||
## 渲染
|
## 渲染
|
||||||
|
|
||||||
@@ -89,5 +91,3 @@
|
|||||||
|
|
||||||
- 长期保留的少量工作便签见 [notes](/D:/dev/cmr-mini/doc/notes)。
|
- 长期保留的少量工作便签见 [notes](/D:/dev/cmr-mini/doc/notes)。
|
||||||
- 历史方案稿和阶段性讨论稿已移到 [archive](/D:/dev/cmr-mini/doc/archive/归档索引.md)。
|
- 历史方案稿和阶段性讨论稿已移到 [archive](/D:/dev/cmr-mini/doc/archive/归档索引.md)。
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user