zhangyan/cmr-mini
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add h5 experience and tracking specs

Browse Source
This commit is contained in:
Rockz-Home
2026-04-05 12:45:19 +08:00
parent 527b4c78a9
commit e17dc931ba
3 changed files with 1181 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

641
doc/experience/H5任务页埋点与结果回传规范.md Normal file
View 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
View 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 承接高变化体验。**