如何接入会话重放（Session Replay）¶

配置¶

表中的 interval/cooldown 默认值用于 Canvas 2D。WebGL 插件未显式配置这两个 单项时会保留更保守的 GPU 读回节奏，避免默认放大 readPixels 成本。

表中的默认值适用于未使用 low、medium、high 字符串预设的情况。字符串 预设会同时替换质量、sampling、interval、cooldown、unchanged/failure backoff 和 max-per-run；显式单项配置会覆盖预设里的对应值。只想改变图片质量时，应给 replayCanvasQuality 传 0 到 1 之间的数字。完整矩阵见 Canvas 录制使用手册。

Canvas 2D 录制配置从 SDK 3.3.0 起可用。WebGL Replay 从 SDK 3.3.7 起 提供，要求 RUM 主包版本 >= 3.3.7，并建议 WebGL 插件与主包使用同一 SDK 发布版本。

开启 Session Replay¶

通过您之前的 SDK 引入方式，替换 NPM 包为 > 3.0.0 版本、或者替换原来的 CDN 链接为 https://static.guance.com/browser-sdk/v3/dataflux-rum.js。SDK 初始化 init() 之后并不会自动采集 Session Replay Record 数据，需要执行 startSessionReplayRecording 开启数据的采集，这对于一些只采集特定情况 Session Replay Record 数据很有用，比如：

// 只采集用户登录之后的操作数据
if (user.isLogin()) {
  DATAFLUX_RUM.startSessionReplayRecording()
}

如果需要停止 Session Replay 数据采集，可以调用 stopSessionReplayRecording() 关闭。

NPM¶

引入 @cloudcare/browser-rum 包，并且保证 @cloudcare/browser-rum 的版本 > 3.0.0，如果要开始录制，在初始化后，请执行 datafluxRum.startSessionReplayRecording()。

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

datafluxRum.init({
  applicationId: '<DATAFLUX_APPLICATION_ID>',
  datakitOrigin: '<DATAKIT ORIGIN>',
  service: 'browser',
  env: 'production',
  version: '1.0.0',
  sessionSampleRate: 100,
  sessionReplaySampleRate: 70,
  trackInteractions: true,
})

datafluxRum.startSessionReplayRecording()

CDN¶

替换原来的 CDN 地址 https://static.guance.com/browser-sdk/v2/dataflux-rum.js 为 https://static.guance.com/browser-sdk/v3/dataflux-rum.js, 并在执行 DATAFLUX_RUM.init() 之后，执行 DATAFLUX_RUM.startSessionReplayRecording()。

<script
src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
type="text/javascript"
></script>
<script>
window.DATAFLUX_RUM &&
window.DATAFLUX_RUM.init({
    applicationId: '<DATAFLUX_APPLICATION_ID>',
    datakitOrigin: '<DATAKIT ORIGIN>',
    service: 'browser',
    env: 'production',
    version: '1.0.0',
    sessionSampleRate: 100,
    sessionReplaySampleRate: 100,
    trackInteractions: true,
})

window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()
</script>

如何实现仅采集错误相关的 Session Replay 数据（SDK 版本要求 ≥3.2.19）{#sessionReplayOnErrorSampleRate}¶

功能说明¶

当页面发生错误时，SDK 将自动执行以下操作：

1. 回溯采集：记录错误发生前 1 分钟 的完整页面快照
2. 持续录制：从错误发生时刻起持续记录直至会话结束
3. 智能补偿：通过独立采样通道确保错误场景的全覆盖

配置示例¶

<script
  src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
  type="text/javascript"
></script>
<script>
// 初始化 SDK 核心配置
window.DATAFLUX_RUM && window.DATAFLUX_RUM.init({
   // 必填参数
   applicationId: '<DATAFLUX_APPLICATION_ID>',
   datakitOrigin: '<DATAKIT_ORIGIN>',

   // 环境标识
   service: 'browser',
   env: 'production',
   version: '1.0.0',

   // 采样策略配置
   sessionSampleRate: 100,          // 全量基础会话采集 (100%)
   sessionReplaySampleRate: 0,       // 关闭常规录屏采样
   sessionReplayOnErrorSampleRate: 100, // 错误场景 100% 采样

   // 辅助功能
   trackInteractions: true          // 启用用户行为追踪
});

// 强制开启录屏引擎（必须调用）
window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording();
</script>

Canvas 录制说明¶

canvas 录制默认不会自动生效。要让它真正工作，至少需要同时满足：

• Session Replay 已被采样到
• 也就是 sessionReplaySampleRate > 0，或者命中 sessionReplayOnErrorSampleRate
• 已调用 startSessionReplayRecording()
• 已配置 replayCanvasEnabled: true
• 目标元素是 Canvas 2D；WebGL/WebGL2 还需要额外注册 WebGL Replay 插件

如果使用 manual 模式，还必须由业务代码主动调用：

datafluxRum.snapshotCanvas(canvas)

Canvas 相关参数中哪些应视为必填¶

实际接入时，建议把下面这些项视为必填：

• sessionReplaySampleRate
• replayCanvasEnabled: true
• replayCanvasMode

如果 replayCanvasMode === 'auto'，再显式配置：

• replayCanvasSampling
• 正数：选择自动 snapshot 路径，建议从 2 开始
• 'all'：更高还原度的自动录制，适合更看重绘制过程还原的页面
• replayCanvasAutoInterval
• 控制自动 snapshot 的调度间隔；数值 sampling 本身不控制 Canvas 2D 频率

三套推荐最小配置¶

手动录制¶

datafluxRum.init({
  applicationId: 'Your Application ID',
  datakitOrigin: '<DataKit Domain Name or IP>',
  sessionReplaySampleRate: 100,

  replayCanvasEnabled: true,
  replayCanvasMode: 'manual',
  replayCanvasQuality: 'medium'
})

datafluxRum.startSessionReplayRecording()

自动 snapshot¶

datafluxRum.init({
  applicationId: 'Your Application ID',
  datakitOrigin: '<DataKit Domain Name or IP>',
  sessionReplaySampleRate: 100,

  replayCanvasEnabled: true,
  replayCanvasMode: 'auto',
  replayCanvasSampling: 2,
  replayCanvasAutoInterval: 250,
  replayCanvasQuality: 'medium'
})

datafluxRum.startSessionReplayRecording()

自动高还原度录制¶

datafluxRum.init({
  applicationId: 'Your Application ID',
  datakitOrigin: '<DataKit Domain Name or IP>',
  sessionReplaySampleRate: 100,

  replayCanvasEnabled: true,
  replayCanvasMode: 'auto',
  replayCanvasSampling: 'all',
  replayCanvasQuality: 'medium'
})

datafluxRum.startSessionReplayRecording()

CSP 场景¶

如果站点 CSP 不允许 worker-src blob:，可以配置：

datafluxRum.init({
  // ...
  replayCanvasWorkerUrl: '/canvas-worker.js'
})

需要注意：

• replayCanvasWorkerUrl 只影响 canvas snapshot 编码
• 它不替代 workerUrl
• 并不是所有 canvas 帧都会用到 canvas worker

更多说明见 CSP 安全策略。

Canvas 2D、WebGL/WebGL2 的完整能力边界、可选插件接入和性能建议见 Canvas 录制使用手册。WebGL 插件必须与 RUM 主包使用同一 SDK 版本，并在 WebGL 引擎创建 context 或缓存绘制方法之前完成 RUM init()。

注意事项¶

某些 HTML 元素在播放时候不可见¶

会话重放不支持以下 HTML 元素：iframe、视频、音频。Session Replay 不支持 Web Components 和 Shadow DOM。

FONT 或 IMG 无法正确呈现¶

Session Replay 不是视频，而是基于 DOM 快照重建的 iframe。因此，重放取决于页面的各种静态资源：font 和 image。

由于以下原因，重放时静态资源可能不可用：

• 该静态资源已经不存在。例如，它是以前部署的一部分。
• 该静态资源不可访问。例如，可能需要身份验证，或者资源可能只能从内部网络访问。

• 由于 CORS（通常是网络字体），静态资源被浏览器阻止。

• 由于重放时，是基于 iframe 对应的 guance.com 沙箱环境，如果某些静态资源未获得特定域名授权，您的浏览器将阻止该请求；

• 通过 Access-Control-Allow-Origin Header 头允许 guance.com 访问您的网站所依赖的任何 font 或 image 静态资源，以确保可以访问这些资源以进行重放。

有关详细信息，可参考 跨源资源共享。

CSS style 未正确应用或者鼠标悬停事件未重放¶

与 font 和 image 不同，Session Replay Record 尝试利用 CSSStyleSheet 接口，将应用的各种 CSS 规则捆绑为记录数据的一部分。如果不能被执行，它会回退到记录 CSS 文件的链接。

要获得正确的鼠标悬停支持，必须可以通过 CSSStyleSheet 接口访问 CSS 规则。

如果样式文件托管在与网页不同的域上，则对 CSS 规则的访问将受到浏览器的跨源安全检查，并且必须指定浏览器使用 crossorigin 属性加载利用 CORS 的样式文件。

例如，如果您的应用程序位于 example.com 域上并通过 link 元素依赖于 assets.example.com 上的 CSS 文件，则 crossorigin 属性应设置为 anonymous。

<link rel="stylesheet" crossorigin="anonymous"
      href="https://assets.example.com/style.css”>

此外，在 assets.example.com 中授权 example.com 域。这允许资源文件通过设置 Access-Control-Allow-Origin Header 头来正确加载资源。

更多阅读¶