docs: add h5 experience and tracking specs
This commit is contained in:
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 承接高变化体验。**
|
||||
Reference in New Issue
Block a user