Web SDK 高级配置 - Flashduty Docs

本文档介绍 Web RUM SDK 的高级配置选项，帮助您根据业务需求定制数据收集行为。

RUM 提供多种高级配置选项：

保护敏感数据

屏蔽个人身份信息等敏感数据

关联用户会话

将用户会话与内部用户标识关联

减少数据量

通过采样降低 RUM 数据收集量

增强上下文

为数据添加丰富的上下文信息

覆盖默认 RUM 视图名称

RUM 会在用户访问新页面或 SPA 中 URL 更改时自动生成视图事件。视图名称默认从当前页面 URL 计算，并自动移除变量 ID（包含数字的路径段）。例如，/dashboard/1234 和 /dashboard/9a 会被归一化为 /dashboard/?。您可以通过设置 trackViewsManually 选项手动跟踪视图事件，并为视图指定自定义名称。

配置手动跟踪视图

启用手动跟踪

在初始化时设置 trackViewsManually 为 true：

rum-init.js

import { flashcatRum } from "@flashcatcloud/browser-rum";

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  trackViewsManually: true
});

调用 startView 方法

在每个新页面或路由更改时调用 startView 方法：

flashcatRum.startView({
  name: "checkout",
  service: "purchase",
  version: "1.2.3",
  context: {
    payment: "Done"
  }
});

string

视图名称，默认为页面 URL 路径

string

服务名称，默认为创建 RUM 应用时指定的服务

string

应用版本，默认为创建 RUM 应用时指定的版本

object

视图的附加上下文，应用于视图及其子事件

React Router 集成

React Router v6 示例

RumTracker.jsx

import { matchRoutes, useLocation } from "react-router-dom";
import { routes } from "path/to/routes";
import { flashcatRum } from "@flashcatcloud/browser-rum";
import { useEffect } from "react";

export default function App() {
  let location = useLocation();

  useEffect(() => {
    const routeMatches = matchRoutes(routes, location.pathname);
    const viewName = routeMatches && computeViewName(routeMatches);
    if (viewName) {
      flashcatRum.startView({ name: viewName });
    }
  }, [location.pathname]);

  // ...
}

function computeViewName(routeMatches) {
  let viewName = "";
  for (let index = 0; index < routeMatches.length; index++) {
    const routeMatch = routeMatches[index];
    const path = routeMatch.route.path;
    if (!path) continue;

    if (path.startsWith("/")) {
      viewName = path;
    } else {
      viewName += viewName.endsWith("/") ? path : `/${path}`;
    }
  }
  return viewName || "/";
}

设置视图名称

使用 setViewName 方法更新当前视图的名称，而无需启动新视图：

flashcatRum.setViewName("Checkout");

控制首屏 Web Vitals 采集

Web SDK 默认在初始加载视图中采集 Web Vitals 和首屏性能指标，包括 FCP、LCP、FID 和加载时间。这些指标会以页面导航开始时间为基准计算，适用于真实用户直接打开页面的场景。如果页面会在用户可见前提前加载，例如被浏览器预渲染、在后台标签页打开，或由宿主容器提前初始化，首屏指标可能会从不相关的导航开始时间计算，导致 FCP、LCP 或加载时间异常偏大。你可以在初始化时将 trackWebVitals 设置为 false，只关闭初始加载视图的 Web Vitals 和首屏性能指标采集。

rum-init.js

import { flashcatRum } from "@flashcatcloud/browser-rum";

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  trackWebVitals: false
});

参数	类型	默认值	说明
`trackWebVitals`	boolean	`true`	是否采集初始加载视图的 Web Vitals 和首屏性能指标。设置为 `false` 后，SDK 不再为初始加载视图采集 FCP、LCP、FID 和加载时间

trackWebVitals 只影响初始加载视图的 Web Vitals 和首屏性能指标。资源、长任务、用户行为、错误和后续视图事件仍按其他配置项继续采集。

丰富和控制 RUM 数据

通过 beforeSend 回调函数，您可以在事件发送到 Flashduty 之前对其进行拦截和修改：

丰富事件：添加额外的上下文属性
修改事件：更改事件内容或屏蔽敏感信息
丢弃事件：选择性地丢弃特定 RUM 事件

上下文类型

不同的事件类型对应不同的上下文：

事件类型	上下文
View	`Location` 对象
Action	触发事件的 `Event` 和处理堆栈
Resource (XHR)	`XMLHttpRequest`、`PerformanceResourceTiming` 和处理堆栈
Resource (Fetch)	`Request`、`Response`、`PerformanceResourceTiming` 和处理堆栈
Resource (Other)	`PerformanceResourceTiming`
Error	`Error` 对象
Long Task	`PerformanceLongTaskTiming`

丰富 RUM 事件

为事件添加上下文属性，例如为资源事件添加响应头数据：

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  beforeSend: (event, context) => {
    if (event.type === "resource" && event.resource.type === "fetch") {
      event.context.responseHeaders = Object.fromEntries(
        context.response.headers
      );
    }
    return true;
  }
});

修改 RUM 事件内容

例如，从视图 URL 中屏蔽电子邮件地址：

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  beforeSend: (event) => {
    event.view.url = event.view.url.replace(/email=[^&]*/, "email=REDACTED");
  }
});

可修改的属性

属性	说明
`view.url`	当前页面的 URL
`view.referrer`	前一个页面的 URL
`view.name`	当前视图名称
`service`	应用的服务名称
`version`	应用版本
`action.target.name`	用户交互的元素（仅限自动收集的操作）
`error.message`	错误消息
`error.stack`	错误堆栈或补充信息
`error.resource.url`	触发错误的资源 URL
`resource.url`	资源 URL
`context`	通过上下文 API 或手动生成事件添加的属性

丢弃 RUM 事件

通过在 beforeSend 中返回 false，可以丢弃特定 RUM 事件：

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  beforeSend: (event) => {
    if (shouldDiscard(event)) {
      return false;
    }
  }
});

视图事件无法被丢弃。

用户会话

通过为 RUM 会话添加用户信息，您可以：

跟踪特定用户的浏览路径
了解哪些用户受错误影响最大
监控关键用户的性能

用户属性

以下为可选的用户属性，建议至少提供一个：

string

唯一用户标识符

string

用户友好名称，默认在 RUM UI 中显示

string

用户电子邮件，若无名称则显示邮件

用户会话 API

设置用户
获取用户
更新属性
删除属性
清除用户

flashcatRum.setUser({
  id: "1234",
  name: "John Doe",
  email: "john@doe.com",
  plan: "premium"
});

const user = flashcatRum.getUser();

flashcatRum.setUserProperty("name", "John Doe");

flashcatRum.removeUserProperty("name");

flashcatRum.clearUser();

用户会话信息更改后，之后的 RUM 事件将包含更新后的信息。注销（调用 clearUser）后，最后一个视图仍保留用户信息，但后续视图和会话级别数据不会。

采样

默认情况下，RUM 会收集所有会话的数据。您可以通过 sessionSampleRate 参数设置采样率来减少收集的会话数量：

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  sessionSampleRate: 90  // 采集 90% 的会话
});

未被普通采样抽中的会话默认不采集页面视图及其相关遥测数据；开启下方异常补采后，可在报错时补报。

异常会话补采

Web SDK 0.3.0 及以上支持在普通采样之外，补采发生错误的会话及其回放。两个参数均为布尔值，默认 false，只作用于对应采样率未抽中的会话，不改变已抽中会话的采集行为。

参数	作用范围	首次报错后的行为
`sessionOnError`	`sessionSampleRate` 未抽中的会话	补报内存中最多最近一分钟的 RUM 事件，并继续正常采集上报
`sessionReplayOnError`	已采集会话中，`sessionReplaySampleRate` 未抽中回放的会话	补报内存中最多最近一分钟的回放，并继续正常录制上报

例如，保留 20% 的普通会话，并补采其余会话中的异常会话及回放：

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  sessionSampleRate: 20,
  sessionReplaySampleRate: 0,
  sessionOnError: true,
  sessionReplayOnError: true
});

先缓存，报错后再上报：未抽中的会话从开始就采集到内存中，仅保留有限的历史；首次出现符合条件的错误时才补报。最多回溯一分钟，不保证完整保留一分钟，也无法恢复 SDK 初始化前或录制开始前的数据。
不报错就不落库、不计费：由 sessionOnError 保留的会话如果始终没有报错，事件和回放都不会上传，不产生会话费用。仅开启 sessionReplayOnError 时，无错误的候选回放不上传、不产生回放费用，但普通采样已抽中的 RUM 会话仍正常上报和计费。
补采只计自身一次：普通采样与异常补采不会重复计算同一会话；异常补采会话在统计中按实际会话计数，不按 1 / sessionSampleRate 放大推算全量，也不因多次报错重复计数。
触发条件是 RUM 错误事件：例如自动捕获的 JavaScript 错误或 addError() 上报的错误。被 beforeSend 丢弃或被限流的错误，以及 SDK 自身错误，不触发补采。失败请求或 HTTP 5xx 的资源事件本身不触发补采。

sessionSampleRate: 100 时，sessionOnError 没有额外作用；sessionReplaySampleRate: 100 时，sessionReplayOnError 没有额外作用。sessionSampleRate: 0 且未开启 sessionOnError 时，仅开启 sessionReplayOnError 也不会采集任何会话。若只想保留异常会话及回放，可将两个采样率都设为 0，同时开启两个补采开关。

已知限制

单页应用的回放不跨视图补齐：回放只能回溯到报错所在视图的起点，且最多一分钟；RUM 事件可以跨视图回溯最多一分钟。
报错后立即离开可能丢失部分历史：首次报错后几秒内关闭或跳转页面，较大的补报数据（约超过 64 KiB）可能因浏览器页面退出时的发送上限而丢失，启用压缩也不能保证完整送达。SDK 优先发送视图和错误，可能丢失较早的其他事件及最后一次视图更新。
缓存回放仍有性能开销：复杂且频繁变化的 DOM 可能使缓冲区溢出并反复生成完整快照，增加主线程负担，缩短可回溯的回放。此类页面建议只开启 sessionOnError。
手动录制前没有回放历史：若通过 startSessionReplayRecording() 控制录制时机，请显式设置 startSessionReplayRecordingManually: true。尤其在开启远程配置后，即使初始化的回放采样率为 0，录制器也可能自动启动；不要依赖采样率为 0 来等待用户同意。手动开始录制前的操作无法补采。
撤回同意不撤销已触发的补报：会话已报错后再撤回跟踪同意，仍会上传此前在同意期间收集、等待补报的数据。

两个开关也可以通过远程配置调整。

用户跟踪同意

为遵守 GDPR、CCPA 等隐私法规，RUM 允许在初始化时设置用户跟踪同意状态：

状态	行为
`"granted"`	开始收集数据并发送到 Flashduty
`"not-granted"`	不收集任何数据

示例：处理用户同意

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  trackingConsent: "not-granted"
});

acceptCookieBannerButton.addEventListener("click", function () {
  flashcatRum.setTrackingConsent("granted");
});

同意状态不会在标签页间同步或持久化，您需要在初始化或通过 setTrackingConsent 提供用户决定。

视图上下文

您可以通过以下 API 为当前视图及其子事件添加或修改上下文：

启动视图时指定
添加/修改属性
替换上下文

flashcatRum.startView({
  name: "checkout",
  context: {
    hasPaid: true,
    amount: 23.42
  }
});

flashcatRum.setViewContextProperty("activity", {
  hasPaid: true,
  amount: 23.42
});

flashcatRum.setViewContext({
  originalUrl: "shopist.io/department/chairs"
});

错误上下文

在捕获错误时，您可以通过 dd_context 属性为错误对象附加本地上下文：

const error = new Error("Something went wrong");
error.dd_context = { component: "Menu", param: 123 };
throw error;

全局上下文

全局上下文会附加到所有 RUM 事件上：

// 添加属性
flashcatRum.setGlobalContextProperty("activity", {
  hasPaid: true,
  amount: 23.42
});

// 删除属性
flashcatRum.removeGlobalContextProperty("codeVersion");

// 替换全局上下文
flashcatRum.setGlobalContext({
  codeVersion: 34
});

// 清除全局上下文
flashcatRum.clearGlobalContext();

// 读取全局上下文
const context = flashcatRum.getGlobalContext();

上下文生命周期

默认情况下，全局上下文和用户上下文存储在当前页面内存中：

页面完全刷新后不会保留
不同标签页或窗口间不共享

启用 storeContextsAcrossPages 选项可以将上下文存储到 localStorage：

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  storeContextsAcrossPages: true
});

不建议在上下文中存储个人身份信息，因为 localStorage 数据会超出用户会话生命周期
与 trackSessionAcrossSubdomains 选项不兼容
localStorage 容量限制为 5 MiB

微前端支持

RUM 支持微前端架构，通过堆栈跟踪机制识别事件来源。在 beforeSend 中根据堆栈信息覆盖 service 和 version 属性：

const SERVICE_REGEX = /some-pathname\/(?<service>\w+)\/(?<version>\w+)\//;

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  beforeSend: (event, context) => {
    const stack = context?.handlingStack || event?.error?.stack;
    const { service, version } = stack?.match(SERVICE_REGEX)?.groups || {};

    if (service && version) {
      event.service = service;
      event.version = version;
    }

    return true;
  }
});

以下事件无法归因于特定来源：自动收集的操作事件、非 XHR/Fetch 的资源事件、视图事件、CORS 和 CSP 违规事件。

集成 RUM 与分布式追踪

集成 RUM 与分布式追踪，可让您将 Web 应用程序的请求与其对应的后端跟踪关联起来，实现完整的前后端链路追踪。

使用方法

使用 allowedTracingUrls 参数配置当前应用的 API 服务域名：

NPM
CDN 同步
CDN 异步

import { flashcatRum } from "@flashcatcloud/browser-rum";

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  service: "<SERVICE_NAME>",
  env: "<ENV_NAME>",
  version: "1.0.0",
  sessionSampleRate: 100,
  allowedTracingUrls: [
    "https://api.example.com",
    /https:\/\/.*\.my-api-domain\.com/,
    (url) => url.startsWith("https://api.example.com")
  ],
  traceSampleRate: 20
});

<script
  src="https://static.flashcat.cloud/browser-sdk/v0.3.0/flashcat-rum.js"
  type="text/javascript">
</script>
<script>
  window.FC_RUM && window.FC_RUM.init({
    applicationId: "<YOUR_APPLICATION_ID>",
    clientToken: "<YOUR_CLIENT_TOKEN>",
    service: "<SERVICE_NAME>",
    env: "<ENV_NAME>",
    version: "1.0.0",
    sessionSampleRate: 100,
    allowedTracingUrls: [
      "https://api.example.com",
      /https:\/\/.*\.my-api-domain\.com/
    ]
  });
</script>

<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.flashcat.cloud/browser-sdk/v0.3.0/flashcat-rum.js','FC_RUM')
  window.FC_RUM.onReady(function() {
    window.FC_RUM.init({
      applicationId: "<YOUR_APPLICATION_ID>",
      clientToken: "<YOUR_CLIENT_TOKEN>",
      service: "<SERVICE_NAME>",
      env: "<ENV_NAME>",
      version: "1.0.0",
      sessionSampleRate: 100,
      allowedTracingUrls: [
        "https://api.example.com",
        /https:\/\/.*\.my-api-domain\.com/
      ]
    })
  })
</script>

allowedTracingUrls 匹配完整 URL，接受以下类型：

类型	说明
String	匹配任何以该值开头的 URL
RegExp	使用正则表达式的 `test()` 方法检查匹配
Function	接收 URL 作为参数，返回 `true` 表示匹配

追踪协议

分布式追踪通过在 Header 上添加对应的头部字段实现：

traceparent: [version]-[trace id]-[parent id]-[trace flags]

version: 当前为 00
trace id: 128 bits 的 trace ID，16 进制处理后为 32 个字符
parent id: 64 bits 的 span ID，16 进制处理后为 16 个字符
trace flags: 代表是否有降采样，01 代表命中采样，00 代表非采样

tracestate: dd=s:[sampling priority];o:[origin]

sampling priority: 1 代表 trace 被采样
origin: 始终为 RUM，代表通过 RUM SDK 采集

示例：

traceparent: 00-00000000000000008448eb211c80319c-b7ad6b7169203331-01
tracestate: dd=s:1;o:rum

如何验证

添加配置后，查看从应用中发送的请求，如能正确携带对应的 header 则说明配置无误。

如您的 HTTP 请求涉及到跨域问题，需要确保请求可通过跨域检测。请确保对应的 server 有跨域相关配置，支持预检请求访问。

注意事项

确保正确配置 applicationId 和 clientToken，以避免数据上传失败
根据应用需求调整采样率和隐私设置，平衡数据量与合规性
对于微前端或复杂前端框架，建议在框架路由级别实现 startView 逻辑

SDK 接入指南

了解如何快速接入 RUM SDK

数据收集

了解 SDK 收集的数据类型和属性

问题排查

解决常见问题和调试技巧

有关 RUM SDK 的更多详细信息，请访问 Flashduty SDK GitHub 仓库。

保护敏感数据

关联用户会话

减少数据量

增强上下文

​覆盖默认 RUM 视图名称

​配置手动跟踪视图

​React Router 集成

​设置视图名称

​控制首屏 Web Vitals 采集

​丰富和控制 RUM 数据

​上下文类型

​丰富 RUM 事件

​修改 RUM 事件内容

​可修改的属性

​丢弃 RUM 事件

​用户会话

​用户属性

​用户会话 API

​采样

​异常会话补采

​已知限制

​用户跟踪同意

​示例：处理用户同意

​视图上下文

​错误上下文

​全局上下文

​上下文生命周期

​微前端支持

​集成 RUM 与分布式追踪

​使用方法

​追踪协议

​如何验证

​注意事项

​相关文档

SDK 接入指南

数据收集

问题排查

覆盖默认 RUM 视图名称

配置手动跟踪视图

React Router 集成

设置视图名称

控制首屏 Web Vitals 采集

丰富和控制 RUM 数据

上下文类型

丰富 RUM 事件

修改 RUM 事件内容

可修改的属性

丢弃 RUM 事件

用户会话

用户属性

用户会话 API

采样

异常会话补采

已知限制

用户跟踪同意

示例：处理用户同意

视图上下文

错误上下文

全局上下文

上下文生命周期

微前端支持

集成 RUM 与分布式追踪

使用方法

追踪协议

如何验证

注意事项

相关文档