Web 应用接入¶

通过收集 Web 应用的指标数据，以可视化方式分析应用性能。

前置条件¶

注意

若已开通 RUM Headless 服务，前置条件已自动配置，可直接接入应用。

开始接入¶

进入用户访问监测 > 新建应用 > Web；
输入应用名称；
输入应用 ID；
选择应用接入方式：
公网 DataWay：直接接收 RUM 数据，无需安装 DataKit 采集器。
本地环境部署：满足前置条件后接收 RUM 数据。

接入方式¶

DataKit 接入公网 OpenWay

确保 DataKit 已安装并配置为公网可访问，并安装 IP 地理信息库；
在控制台获取 applicationId、env、version 等参数，开始接入应用；
集成 SDK 时，将 datakitOrigin 设置为 DataKit 的域名或 IP。

在控制台获取 applicationId、clientToken 和 site 等参数，开始接入应用；
集成 SDK 时无需配置 datakitOrigin，数据将默认发送到公网 DataWay。

SDK 配置¶

接入方式	说明
NPM	将 SDK 代码打包到前端项目中，确保前端性能不受影响。可能错过 SDK 初始化前的请求和错误收集。
CDN 异步加载	通过 CDN 异步引入 SDK 脚本，不影响页面加载性能。可能错过初始化前的请求和错误收集。
CDN 同步加载	通过 CDN 同步引入 SDK 脚本，能完整收集所有错误和性能指标。但可能影响页面加载性能。

NPM 接入¶

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

npm install @cloudcare/browser-rum

在项目中初始化 SDK：

import { datafluxRum } from '@cloudcare/browser-rum'
datafluxRum.init({
  applicationId: '<应用 ID>',
  site: 'http://172.16.212.186:9529',
  clientToken: 'a993f53a8ea04bc6b9350e5e670a3a3b',
  env: 'production',
  version: '1.0.0',
  service: 'browser',
  sessionSampleRate: 100,
  sessionReplaySampleRate: 70,
  compressIntakeRequests: true,
  trackInteractions: true,
  traceType: 'ddtrace', // 非必填，默认为ddtrace，目前支持 ddtrace、zipkin、skywalking_v3、jaeger、zipkin_single_header、w3c_traceparent 6种类型
  allowedTracingOrigins: ['https://api.example.com', /https:\/\/.*\.my-api-domain\.com/], // 非必填，允许注入trace采集器所需header头部的所有请求列表。可以是请求的origin，也可以是是正则
})
datafluxRum.startSessionReplayRecording()

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: '<应用 ID>',
      site: 'http://172.16.212.186:9529',
      clientToken: 'a993f53a8ea04bc6b9350e5e670a3a3b',
      env: 'production',
      version: '1.0.0',
      service: 'browser',
      sessionSampleRate: 100,
      sessionReplaySampleRate: 70,
      compressIntakeRequests: true,
      trackInteractions: true,
      traceType: 'ddtrace', // 非必填，默认为ddtrace，目前支持 ddtrace、zipkin、skywalking_v3、jaeger、zipkin_single_header、w3c_traceparent 6种类型
      allowedTracingOrigins: ['https://api.example.com', /https:\/\/.*\.my-api-domain\.com/], // 非必填，允许注入trace采集器所需header头部的所有请求列表。可以是请求的origin，也可以是是正则
    })
  window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()
</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: '<应用 ID>',
      site: 'http://172.16.212.186:9529',
      clientToken: 'a993f53a8ea04bc6b9350e5e670a3a3b',
      env: 'production',
      version: '1.0.0',
      service: 'browser',
      sessionSampleRate: 100,
      sessionReplaySampleRate: 70,
      compressIntakeRequests: true,
      trackInteractions: true,
      traceType: 'ddtrace', // 非必填，默认为ddtrace，目前支持 ddtrace、zipkin、skywalking_v3、jaeger、zipkin_single_header、w3c_traceparent 6种类型
      allowedTracingOrigins: ['https://api.example.com', /https:\/\/.*\.my-api-domain\.com/], // 非必填，允许注入trace采集器所需header头部的所有请求列表。可以是请求的origin，也可以是是正则
    })
    window.DATAFLUX_RUM && window.DATAFLUX_RUM.startSessionReplayRecording()
  })
</script>

参数配置¶

初始化参数¶

参数	类型	是否必须	默认值	描述
`applicationId`	String	是		从观测云创建的应用 ID。
`datakitOrigin`	String	是		DataKit 数据上报 Origin 注释: `协议（包括：//），域名（或IP地址）[和端口号]` 例如： https://www.datakit.com； http://100.20.34.3:8088。
`clientToken`	String	是		以 openway 方式上报数据令牌，从观测云控制台获取，必填（公共 openway 方式接入）。
`site`	String	是		以公共 openway 方式上报数据地址，从观测云控制台获取，必填（公共 openway 方式接入）。
`env`	String	否		Web 应用当前环境，如 prod：线上环境；gray：灰度环境；pre：预发布环境；common：日常环境；local：本地环境。
`version`	String	否		Web 应用的版本号。
`service`	String	否		当前应用的服务名称，默认为 `browser`，支持自定义配置。
`sessionSampleRate`	Number	否	`100`	指标数据收集百分比： `100` 表示全收集；`0` 表示不收集。
`sessionOnErrorSampleRate`	Number	否	`0`	错误会话补偿采样率：当会话未被 `sessionSampleRate` 采样时，若会话期间发生错误，则按此比例采集。此类会话将在错误发生时开始记录事件，并持续记录直到会话结束。SDK 版本要求`>= 3.2.19`
`sessionReplaySampleRate`	Number	否	`100`	Session Replay 数据采集百分比: `100` 表示全收集；`0` 表示不收集。
`sessionReplayOnErrorSampleRate`	Number	否	`0`	Session Replay 错误会话重放补偿采样率：当会话未被 `sessionReplaySampleRate` 采样时，若会话期间发生错误，则按此比例采集。此类回放将记录错误发生前最多一分钟的事件，并持续记录直到会话结束。SDK 版本要求`>= 3.2.19`
`trackSessionAcrossSubdomains`	Boolean	否	`false`	同一个域名下面的子域名共享缓存。
`usePartitionedCrossSiteSessionCookie`	Boolean	否	`false`	是否开启分区安全跨站点会话 cookie 详情
`useSecureSessionCookie`	Boolean	否	`false`	使用安全会话 cookie。这将禁用在不安全（非 HTTPS）连接上发送的 RUM 事件
`traceType`	Enum	否	`ddtrace`	配置链路追踪工具类型，如果不配置默认为 `ddtrace`。目前支持 `ddtrace`、`zipkin`、`skywalking_v3`、`jaeger`、`zipkin_single_header`、`w3c_traceparent` 6 种数据类型。 1. `opentelemetry` 支持 `zipkin_single_header`、`w3c_traceparent`、`zipkin`、`jaeger` 4 种类型。 2. 该配置的生效需依赖 `allowedTracingOrigins` 配置项。 3. 配置相应类型的 traceType 需要对相应的 API 服务。关于设置不同的 `Access-Control-Allow-Headers`，可参考 APM 如何关联 RUM 。
`traceId128Bit`	Boolean	否	`false`	是否以 128 字节的方式生成 `traceID`，与 `traceType` 对应，目前支持类型 `zipkin`、`jaeger`。
`allowedTracingOrigins`	Array	否	`[]`	允许注入 `trace` 采集器所需 header 头部的所有请求列表。可以是请求的 origin，也可以是正则，origin: `协议（包括：//），域名（或IP地址）[和端口号]`。_例如： `["https://api.example.com", /https:\\/\\/._\\.my-api-domain\\.com/]`。*
`allowedTracingUrls`	Array	否	`[]`	与 Apm 关联请求的 Url 匹配列表。可以是请求的 url，也可以是正则，或者是 match function 例如：`["https://api.example.com/xxx", /https:\/\/.*\.my-api-domain\.com\/xxx/, function(url) {if (url === 'xxx') { return false} else { return true }}]` 该参数是 `allowedTracingOrigins` 配置的扩展，两者配置其一即可。
`trackUserInteractions`	Boolean	否	`false`	是否开启用户行为采集。
`actionNameAttribute`	String	否		版本要求:`>3.1.2`。为元素添加自定义属性来指定操作的名称。具体使用方式，详情参考
`beforeSend`	Function(event, context):Boolean	否		版本要求:`>3.1.2`。数据拦截以及数据修改，详情参考
`storeContextsToLocal`	Boolean	否		版本要求:`>3.1.2`。是否把用户自定义数据缓存到本地 localstorage，例如： `setUser`, `addGlobalContext` api 添加的自定义数据。
`storeContextsKey`	String	否		版本要求:`>3.1.18`。定义存储到 localstorage 的 key ，默认不填，自动生成, 该参数主要是为了区分在同一个域名下，不同子路径共用 store 的问题
`compressIntakeRequests`	Boolean	否		压缩 RUM 数据请求内容，以减少发送大量数据时的带宽使用量，同时能够减少发送数据的请求数量。压缩在 WebWorker 线程中完成。关于 csp 安全策略可参考 csp 安全。SDK 版本要求`>= 3.2.0`。 datakit 版本要求 `>=1.60`。部署版要求 `>= 1.96.178`
`workerUrl`	Sring	否		sessionReplay 和 compressIntakeRequests 数据压缩都是在 webwork 线程中完成，所以默认情况下，在开启 csp 安全访问的情况下，需要允许 worker-src blob:; 该配置允许添加自行托管 worker 地址。关于 csp 安全策略可参考 csp 安全。SDK 版本要求`>= 3.2.0`。
`remoteConfiguration`	Boolean	否		是否开启数据采集的远程配置功能，默认不开启。远程配置功能可以在不发布新版本的情况下，动态修改数据采集的配置项。例如：可以在远程配置中修改采样率、是否开启用户行为采集等。远程配置功能需要在观测云控制台中开启环境变量设置。SDK 版本要求`>= 3.2.20`。datakit 版本要求 `>=1.60`。观测云控制台如何开启环境变量功能

`site` 参数处理¶

节点名	地址
中国区 1（杭州）	https://rum-openway.guance.com
中国区 2（宁夏）	https://aws-openway.guance.com
中国区 4（广州）	https://cn4-openway.guance.com
中国区 6（香港）	https://cn6-openway.guance.one
海外区 1（俄勒冈）	https://us1-openway.guance.com
欧洲区 1（法兰克福）	https://eu1-openway.guance.one
亚太区 1（新加坡）	https://ap1-openway.guance.one
非洲区 1（南非）	https://za1-openway.guance.com
印尼区 1（雅加达）	https://id1-openway.guance.com

应用场景¶

仅采集错误会话事件¶

前提

SDK 版本要求：3.2.19 以上。

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

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

配置方案¶

<script
  src="https://static.guance.com/browser-sdk/v3/dataflux-rum.js"
  type="text/javascript"
></script>
<script>
// 核心配置初始化
window.DATAFLUX_RUM && window.DATAFLUX_RUM.init({

   ...
   // 精准采集策略
   sessionSampleRate: 0,             // 关闭常规会话采集
   sessionOnErrorSampleRate: 100, // 全量采集错误会话

});

</script>

自定义添加数据 TAG¶

使用 setGlobalContextProperty 或 setGlobalContext API 为所有 RUM 事件添加自定义 tag。

// 使用setGlobalContextProperty添加单个TAG
window.DATAFLUX_RUM && window.DATAFLUX_RUM.setGlobalContextProperty('userName', '张三')

// 使用setGlobalContext添加多个TAG
window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.setGlobalContext({
    userAge: 28,
    userGender: '男',
  })

跟踪用户操作¶

控制是否开启采集 Action¶

通过 trackUserInteractions 初始化参数控制是否采集用户点击行为。

自定义 Action 名称¶

通过为可点击元素添加data-guance-action-name属性或data-custom-name（取决于actionNameAttribute配置）来自定义 Action 名称。

使用 `addAction` API 自定义 Action¶

// CDN 同步加载
window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.addAction('cart', {
    amount: 42,
    nb_items: 2,
    items: ['socks', 't-shirt'],
  })

// CDN 异步加载
window.DATAFLUX_RUM.onReady(function () {
  window.DATAFLUX_RUM.addAction('cart', {
    amount: 42,
    nb_items: 2,
    items: ['socks', 't-shirt'],
  })
})

// NPM
import { datafluxRum } from '@cloudcare/browser-rum'
datafluxRum &&
  datafluxRum.addAction('cart', {
    amount: 42,
    nb_items: 2,
    items: ['socks', 't-shirt'],
  })

自定义添加 Error¶

使用 addError API 自定义添加 Error 指标数据添加自定义 Error。

// CDN 同步加载
const error = new Error('Something wrong occurred.')
window.DATAFLUX_RUM && DATAFLUX_RUM.addError(error, { pageStatus: 'beta' })

// CDN 异步加载
window.DATAFLUX_RUM.onReady(function () {
  const error = new Error('Something wrong occurred.')
  window.DATAFLUX_RUM.addError(error, { pageStatus: 'beta' })
})

// NPM
import { datafluxRum } from '@cloudcare/browser-rum'
const error = new Error('Something wrong occurred.')
datafluxRum.addError(error, { pageStatus: 'beta' })

自定义用户标识¶

使用 setUser API 为当前用户添加标识属性（如 ID、name、email）添加自定义用户信息。

// CDN 同步加载
window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.setUser({
    id: '1234',
    name: 'John Doe',
    email: 'john@doe.com',
  })

// CDN 异步加载
window.DATAFLUX_RUM.onReady(function () {
  window.DATAFLUX_RUM.setUser({ id: '1234', name: 'John Doe', email: 'john@doe.com' })
})

// NPM
import { datafluxRum } from '@cloudcare/browser-rum'
datafluxRum.setUser({ id: '1234', name: 'John Doe', email: 'john@doe.com' })

Web 会话重放¶

前提

确保您使用的 SDK 版本支持会话重放功能（通常是 > 3.0.0 版本）。

开启录制¶

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

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

前提

SDK 版本要求在 3.2.19 以上。

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

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

配置示例¶

<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({
   ....

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

});

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

注意事项¶

会话重放功能不涵盖 iframe、视频、音频和画布元素的播放；
为确保重放时能正常访问静态资源（如字体、图片），可能需要配置 CORS 策略；
确保通过 CSSStyleSheet 接口可访问 CSS 规则，以支持 CSS 样式和鼠标悬停事件。

调试优化¶

利用 SDK 提供的日志和监控工具进行调试，提升应用性能；
根据业务需求调整 sessionSampleRate 和 sessionReplaySampleRate 参数。