观测云会话重放：把玩家游戏中的那一秒卡顿完整回放给研发团队

观测云 Browser SDK 3.3.7 WebGL / WebGL2 Session Replay，让游戏画面、用户操作、错误和性能数据回到同一条时间轴。

“Boss 出场时黑了一下。”

“我明明躲开了，为什么还是被击中？”

“结算前突然卡住，刷新以后又正常了。”

这类反馈最消耗团队时间。玩家记不清步骤，客服只能反复追问，研发拿不到现场，最后往往只能回复一句：“暂时无法复现。”

真正重要的是当问题发生时，玩家眼前到底出现了什么。

我们直接录一场真正的 Cocos 游戏

为了验证 WebGL Session Replay 在真实游戏负载下的效果，我们用 Cocos Creator 3.8.8 制作并发布了一个 Web Desktop Release 游戏：NEBULA BREACH。

游戏里的动态星云、自动驾驶战机、敌机编队、三连弹、能量核心、陨石和连续特效，都由 Cocos 引擎在 WebGL2 Canvas 中实时渲染。

战斗开始后，玩家战机持续变轨，敌机会从不同位置组成编队进入战场。画面始终占满游戏区域，没有调试面板挡住主体。

当多组敌机、弹幕、能量核心和陨石同时出现时，回放仍然要能看清战机位置和战场变化——这才是游戏团队真正需要的验收标准。

最终播放效果：研发看到的是玩家操作的完整回放

接入完成后，在观测云平台打开「用户访问监测 → 会话重放」，Cocos 游戏画面会和页面状态一起进入播放器。

这是观测云平台中的真实验收效果。左侧菜单被保留，方便用户确认所在功能；截图避开了右上角账号信息和右侧无关区域，游戏战场也没有被浮层遮挡。

拖动时间轴，研发可以直接回到敌机编队进入、弹幕密集或特效出现的那一刻，而不是根据玩家的一句话猜测现场。

面对只持续几秒的黑屏、花屏、贴图异常或操作失灵，可以暂停在关键帧，再对照同一时刻的 Action、Error、Resource 和性能数据。

如果是无人操作的自动演示，首次播放时建议关闭播放器中的「跳过不活跃」。播放器会把连续 10 秒以上没有鼠标、触摸、滚动或输入的区间视为不活跃并自动快进；WebGL 画面持续变化并不等同于用户交互。真实玩家会话通常会自然产生操作事件；如果仍出现自动快进，关闭该开关即可按 1× 检查完整过程。本次验收截图也采用了关闭快进、1× 播放的方式。

一次问题反馈可以回答四个问题：

玩家当时看到了什么？
异常出现前，玩家做了什么？
画面变化和前端错误是否发生在同一时刻？
是偶发的单用户问题，还是某个版本、设备或页面的共同问题？

更适合排障的完整玩家行为回放

WebGL Replay 插件会在绘制发生时，按配置采集 Canvas 像素快照，并写入原有 Session Replay 事件流。它不会录制用户整块屏幕，也不需要逐条保存 WebGL 绘制命令。

这带来三个直接好处：

接入轻：不用改造 Cocos 场景，也不用给每个关卡单独编写录像逻辑。
画质和成本可调：采样频率、编码质量、最大画布尺寸和单帧大小都能按场景配置。
排障上下文完整：游戏画面可以和用户操作、错误、资源请求、设备及版本信息一起分析。

5 分钟接入：npm 项目

WebGL 回放能力是独立可选包。主包与插件建议使用同一版本。

npm install @cloudcare/browser-rum@3.3.7 @cloudcare/browser-rum-webgl@3.3.7

import { datafluxRum } from '@cloudcare/browser-rum'
import { webglReplayPlugin } from '@cloudcare/browser-rum-webgl'

datafluxRum.init({
  applicationId: '<YOUR_APPLICATION_ID>',
  datakitOrigin: '<YOUR_DATAKIT_ORIGIN>',

  // 测试环境先设为 100，生产环境再按流量灰度
  sessionReplaySampleRate: 100,

  replayCanvasEnabled: true,
  replayCanvasMode: 'auto',
  replayCanvasSampling: 2,
  replayCanvasMimeType: 'image/webp',
  replayCanvasQuality: 0.6,
  replayCanvasMaxCanvasSize: 1280,
  replayCanvasMaxEncodedBytes: 120000,
  replayCanvasAutoInterval: 250,
  replayCanvasAutoCooldown: 125,

  plugins: [webglReplayPlugin()]
})

datafluxRum.startSessionReplayRecording()

// 完成插件初始化后，再启动会创建 WebGL 上下文的游戏
import('./game-main.js')

这组参数适合先做小流量验证。画面复杂、需要观察弹幕或细小 UI 时，可以提高画质和最大尺寸；更关注成本时，则降低采样与单帧预算。

支持 Cocos Creator 导出的 H5 游戏接入

Cocos Creator 导出的 H5 游戏同样可以接入。最重要的一条规则是：先加载并初始化 RUM 与 WebGL Replay 插件，再加载 Cocos 引擎和游戏入口。

以 Cocos Creator 3.8 Web Desktop 构建产物为例：

<!-- 1. 先加载观测云 RUM 与 WebGL Replay 插件 -->
<script src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"></script>
<script src="https://static.guance.com/browser-sdk/v3/dataflux-rum-webgl.js"></script>

<script>
  DATAFLUX_RUM.init({
    applicationId: '<YOUR_APPLICATION_ID>',
    datakitOrigin: '<YOUR_DATAKIT_ORIGIN>',
    sessionReplaySampleRate: 100,
    replayCanvasEnabled: true,
    replayCanvasMode: 'auto',
    replayCanvasSampling: 2,
    replayCanvasQuality: 0.6,
    replayCanvasMaxCanvasSize: 1280,
    plugins: [DATAFLUX_RUM_WEBGL.webglReplayPlugin()]
  })

  DATAFLUX_RUM.startSessionReplayRecording()
</script>

<!-- 2. 再加载 Cocos Creator 导出的运行时与游戏入口 -->
<script src="src/polyfills.bundle.js"></script>
<script src="src/system.bundle.js"></script>
<script src="src/import-map.json" type="systemjs-importmap"></script>
<script>
  System.import('./index.js').catch(console.error)
</script>

不同 Cocos Creator 版本的构建文件名可能变化，但原则不变：插件必须在 Cocos 创建 WebGL Context、缓存绘制方法之前完成初始化。

对清晰度要求高的游戏，如何配置？

本次验收使用了更高画质档位，让弹幕和小型敌机在大屏播放器中依然可辨认：

replayCanvasSampling: 4,
replayCanvasMimeType: 'image/webp',
replayCanvasQuality: 0.9,
replayCanvasMaxCanvasSize: 1920,
replayCanvasMaxEncodedBytes: 300000,
replayCanvasAutoInterval: 125,
replayCanvasAutoCooldown: 75

这是一组用于高清验收的参数，不建议未经评估直接全量用于生产。生产环境应该根据 Canvas 分辨率、画面变化频率、平均会话时长和实际数据量逐步调整。

上线前，记住这四条边界

当前 WebGL / WebGL2 插件在 replayCanvasMode: 'auto' 下工作。
记录的是预算内的像素快照，不是连续视频，也不是 WebGL 命令级回放。
当前不覆盖 OffscreenCanvas；使用 Worker 渲染的项目需要先确认实际 Canvas 路径。
生产环境建议先选择高价值页面小流量接入，再根据画质、数据量和排障收益扩大范围。

别再让“无法复现”成为游戏问题的终点

如果你的产品里有 H5 游戏、3D 编辑器、在线展厅、地图、工业大屏或数字孪生，最值得先接入的不是访问量最大的页面，而是一旦出问题就最难复现、最影响体验和转化的页面。

选一个真实场景，录制十几次会话，让研发在 Session Replay 里成功定位一次问题。你会很快看到变化：过去需要客服追问、用户录屏、研发猜测的问题，现在可以沿着同一条时间轴直接找到答案。

让每一次“刚才好像有问题”，都变成能看见、找到、修掉的证据。