Web 应用接入¶

完成本页配置后，Browser RUM SDK 会自动采集页面 View、资源请求、前端错误和用户操作，并将数据上报到观测云。

选择接入路径¶

先根据应用形态选择入口，避免重复配置 View 或在服务端渲染阶段访问浏览器 API。

准备接入信息¶

1. 进入「用户访问监测 > 应用列表 > 新建应用 > Web」。
2. 创建应用并获取控制台生成的 applicationId、env、version 等配置。

3. 选择数据上报方式：

4. 公网 OpenWay：获取 site 和 clientToken，无需部署 DataKit。

5. DataKit 直连：准备 datakitOrigin；DataKit 需要启用 RUM 采集器，并配置为公网可访问且安装 IP 地理信息库。

上报方式¶

{
  applicationId: "<APPLICATION_ID>",
  datakitOrigin: "<DATAKIT_ORIGIN>"
}

{
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>"
}

集成 SDK¶

NPM 接入¶

在前端项目中安装并引入 SDK：

npm install @cloudcare/browser-rum @cloudcare/browser-core

在项目中初始化 SDK：

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

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  service: "web-app",
  env: "production",
  version: "1.0.0",
  sessionSampleRate: 100,
  trackUserInteractions: true
})

CDN 同步加载¶

在 HTML 文件中添加脚本：

<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: "<APPLICATION_ID>",
      site: "<PUBLIC_OPENWAY_URL>",
      clientToken: "<CLIENT_TOKEN>",
      service: "web-app",
      env: "production",
      version: "1.0.0",
      sessionSampleRate: 100,
      trackUserInteractions: true
    })
</script>

CDN 异步加载¶

在 HTML 文件中添加脚本：

<script>
  ;(function (h, o, u, n, d) {
    h = h[d] = h[d] || {
      q: [],
      onReady: function (c) {
        h.q.push(c)
      },
    }
    d = o.createElement(u)
    d.async = 1
    d.src = n
    n = o.getElementsByTagName(u)[0]
    n.parentNode.insertBefore(d, n)
  })(
    window,
    document,
    "script",
    "https://static.guance.com/browser-sdk/v3/dataflux-rum.js",
    "DATAFLUX_RUM"
  )
  DATAFLUX_RUM.onReady(function () {
    DATAFLUX_RUM.init({
      applicationId: "<APPLICATION_ID>",
      site: "<PUBLIC_OPENWAY_URL>",
      clientToken: "<CLIENT_TOKEN>",
      service: "web-app",
      env: "production",
      version: "1.0.0",
      sessionSampleRate: 100,
      trackUserInteractions: true
    })
  })
</script>

以上示例使用公网 OpenWay。使用 DataKit 直连时，请移除 site 和 clientToken，改为配置 datakitOrigin。

验证接入¶

1. 打开已接入 SDK 的页面，并完成一次页面跳转、按钮点击和 API 请求。
2. 在浏览器开发者工具的 Network 中过滤 /v1/write/rum，确认存在成功的上报请求。
3. 检查 Console，确认没有 Application ID is not configured、datakitOrigin or site is not configured 等初始化错误。
4. 进入「用户访问监测 > 应用列表」，打开对应 Web 应用，在查看器中按 service、env、version 筛选并确认存在 View、Resource 或 Action 数据。

常用可选配置¶

基础数据确认成功后，再按需要开启其他能力：

链路追踪配置（可选）¶

NPM + TypeScript 接入时，traceType 必须使用从对应品牌 browser-core 包导入的 TraceType 枚举：

import { TraceType } from "@cloudcare/browser-core"
import { datafluxRum } from "@cloudcare/browser-rum"

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  allowedTracingUrls: ["https://api.example.com"],
  traceType: TraceType.DDTRACE
})

TraceType.DDTRACE 的运行时值仍为 "ddtrace"。CDN 接入没有模块导入，显式配置时使用对应的运行时字符串。开启链路追踪后，还需要在 API 服务端允许对应的 Trace Header，详情参考 APM 如何关联 RUM。

如果常规 Session 未命中采样，但仍需要把 Trace Header 传给后端，可以显式开启 allowTraceHeaderWithoutSession：

datafluxRum.init({
  applicationId: "<APPLICATION_ID>",
  site: "<PUBLIC_OPENWAY_URL>",
  clientToken: "<CLIENT_TOKEN>",
  sessionSampleRate: 0,
  sessionOnErrorSampleRate: 0,
  allowedTracingUrls: ["https://api.example.com"],
  allowTraceHeaderWithoutSession: true
})

开启后，SDK 仍只为命中 allowedTracingUrls 的 XHR 和 Fetch 请求注入 Trace Header。 此配置不会创建或强制启用 RUM Session，也不会上报未采样 Session 的 View、Error、 Resource 或 Action 数据。API 服务仍需允许所选 traceType 对应的请求头；跨域请求还需 正确配置 CORS。

参数配置¶

初始化参数¶

未使用 low、medium、high 字符串预设时，Canvas 自动调度基线是：sampling 2、每个 Canvas 的目标 interval 250 ms、cooldown 250 ms、unchanged backoff 3000 ms、 failure backoff 5000 ms、每轮最多 2 个 Canvas。字符串预设会同时替换这些 预算和编码质量；多 Canvas 还会受公平轮转和全局采集预算限制。显式单项配置会 覆盖预设里的对应值。完整 preset 矩阵见 Canvas 录制使用手册。

以上高频调度基线用于 Canvas 2D。WebGL 插件未显式配置 interval/cooldown 时 继续采用更保守的 GPU 读回节奏；显式单项配置才会分别覆盖。

site 参数处理¶

运行时 Session 控制¶

RUM SDK 3.3.6 新增 startSession()。调用后会立即结束当前 Session，并按照当前 采样配置重新开始 Session，不需要等待下一次用户交互：

datafluxRum.startSession()

也可以同时覆盖运行时 sessionSampleRate：

datafluxRum.startSession({
  sessionSampleRate: 100,
})

采样率必须在 0 到 100 之间。该覆盖值会用于本次和后续自动续建的 Session。 完整 RUM 包与精简 RUM 包都支持此 API。详细语义和使用场景参见 运行时重新开始 Session。

按需开启高级能力¶

仅采集错误会话事件¶

当页面触发错误时，SDK 将自动执行：

• 持续记录：从错误触发起，完整记录会话全生命周期数据。
• 精准补偿：通过独立采样通道，确保错误场景无遗漏。

配置方案¶

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    applicationId: "<APPLICATION_ID>",
    site: "<PUBLIC_OPENWAY_URL>",
    clientToken: "<CLIENT_TOKEN>",
    sessionSampleRate: 0,
    sessionOnErrorSampleRate: 100
  })

以上示例使用公网 OpenWay。DataKit 直连时，按基础接入示例替换上报地址字段。

数据压缩¶

在采集大量静态资源（如 JS、CSS、图片等）并开启全量采集时，SDK 在初始化后可能会产生较多数据，造成请求积压，甚至对应用线程状态产生影响。

设置 compressIntakeRequests: true 后，SDK 会在 Web Worker 中使用 deflate 压缩上报数据，以减少请求体积和请求数量。

配置示例¶

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    applicationId: "<APPLICATION_ID>",
    site: "<PUBLIC_OPENWAY_URL>",
    clientToken: "<CLIENT_TOKEN>",
    compressIntakeRequests: true
  })

注意事项¶

1. 数据压缩逻辑在 Web Worker 中执行，若启用了 CSP 安全策略，需要在 worker-src 中允许 blob:。更多信息可参考 CSP 安全策略说明。
2. SDK 支持通过 workerUrl 配置项指定自托管的 Worker 地址。
3. 使用该功能的 SDK 版本需 >= 3.2。

自定义数据与事件¶

基础接入页不再重复展开所有公共 API。按业务目标进入对应页面，可获得 CDN、NPM 和完整参数示例：

• 跟踪用户操作：自动采集点击、定义 Action 名称、添加自定义 Action。
• 自定义用户标识：登录后设置用户，退出或切换账号时清理用户。
• 全局上下文：为所有后续 RUM 事件添加稳定业务维度。
• 添加自定义 Action：记录无法通过页面点击表达的业务操作。
• 上报自定义 Error：上报已经捕获或由业务主动识别的异常。

Web 会话重放¶

开启录制¶

在 SDK 初始化后，调用 startSessionReplayRecording() 方法来开启会话重放的录制。您可以选择在特定条件下开启，如用户登录后 开启会话录制。

仅采集错误相关的会话重放数据¶

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

• 回溯采集：记录错误前 1 分钟的完整页面快照；
• 持续录制：从错误发生时起持续记录，直至会话结束；
• 智能补偿：通过独立采样通道确保错误场景无遗漏。

配置示例¶

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    applicationId: "<APPLICATION_ID>",
    site: "<PUBLIC_OPENWAY_URL>",
    clientToken: "<CLIENT_TOKEN>",
    sessionSampleRate: 100,
    sessionReplaySampleRate: 0,
    sessionReplayOnErrorSampleRate: 100
  })

window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()

注意事项¶

• 会话重放不记录 iframe、视频和音频的播放内容；Canvas 默认不采集，需要单独配置 replayCanvasEnabled。WebGL/WebGL2 从 SDK 3.3.7 起提供，要求 RUM 主包版本 >= 3.3.7，还需额外安装并注册兼容的 browser-rum-webgl 插件；建议插件与主包使用同一 SDK 发布版本，详情见Canvas 录制使用手册；
• 为确保重放时能正常访问静态资源（如字体、图片），可能需要配置 CORS 策略；
• 确保通过 CSSStyleSheet 接口可访问 CSS 规则，以支持 CSS 样式和鼠标悬停事件。

验证录制状态¶

调用 window.DATAFLUX_RUM.isRecording() 检查当前页面是否正在录制，并在会话重放查看器中确认对应 Session 已产生重放数据。生产环境再根据业务需求调整 sessionReplaySampleRate。