zhangyan/cmr-mini

Fork 0

Files

Rockz-Home e17dc931ba docs: add h5 experience and tracking specs

2026-04-05 12:45:19 +08:00

10 KiB

Raw Permalink Blame History

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. 推荐运行链路

对于“打点后增强体验”，建议统一为：

完成打点
-> 原生判定成功
-> 原生内容卡 / 原生短反馈
-> 用户点击 CTA
-> 打开整页 H5 详情页 / 任务页
-> H5 获取上下文并完成互动
-> H5 submitResult 回传结果
-> 原生决定后续反馈 / 结果展示

对于“活动浏览链路”，建议统一为：

活动列表
-> 活动详情页
-> 准备页
-> 地图主链
-> 原生结果页
-> 可选进入 H5 增强结果页

关键点：

H5 总是在主系统之后进入，而不是反向驱动主系统
打点成功必须先由原生确认
结果页必须始终有原生版本兜底

6. 推荐配置挂接方式

当前项目建议继续沿用现有配置口径：

playfield.controlOverrides.<key>.autoPopup
playfield.controlOverrides.<key>.contentExperience
playfield.controlOverrides.<key>.clickExperience

推荐理解：

autoPopup 控制打点完成后是否先弹原生内容卡
contentExperience 控制打点成功后的扩展体验入口
clickExperience 控制点击点位时的补充内容入口

建议最小配置示例：

{
  "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

示例：

{
  "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 与活动对象的关系

建议活动只绑定“已发布的体验对象摘要”，而不直接持有散装页面地址。

推荐关系：

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 承接高变化体验。

10 KiB Raw Permalink Blame History Unescape Escape