Web SDK 接入指南

RUM SDK 支持多种接入方式，您可以根据项目需求选择最适合的方案。

接入方式

我们提供三种接入方式：

接入方式	推荐场景	特点
NPM	现代 Web 应用	与前端代码打包，对页面加载无影响
CDN 异步	有性能目标的应用	异步加载，不影响页面性能
CDN 同步	需要完整数据采集	同步加载，可捕获所有事件

NPM 和 CDN 异步方式可能会错过在 SDK 初始化之前触发的错误、资源和用户操作。如需完整采集，请使用 CDN 同步方式。

获取应用凭证

在 Flashduty 控制台的 RUM 应用管理页面：

创建或选择一个 Web 应用
获取以下凭证信息：
- Application ID - 应用唯一标识符
- Client Token - 客户端访问令牌

RUM 应用管理页面展示 Application ID 和 Client Token 的位置

接入代码

NPM 包
CDN 异步
CDN 同步

将 @flashcatcloud/browser-rum 添加到您的 package.json 文件中：

npm install @flashcatcloud/browser-rum

然后在应用入口文件中初始化：

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
});

将以下代码片段添加到每个需要监控的 HTML 页面的 <head> 标签中：

<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/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
    });
  });
</script>

将以下代码片段添加到 HTML 页面的 <head> 标签最前面（在任何其他 <script> 标签之前）：

<script
  src="https://static.flashcat.cloud/browser-sdk/v0/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
    });
</script>

您可以使用 window.FC_RUM 检查 SDK 是否加载成功，以便处理加载失败的情况。

初始化参数

必填参数

string

必填

应用 ID，在应用管理页面获取

string

必填

客户端 Token，在应用管理页面获取

string

必填

服务名称，用于区分不同的服务

可选参数

string

环境标识，如 production、staging 等

string

应用版本号

number

默认值:"100"

要跟踪的会话百分比：100 为全部，0 为不采集

number

默认值:"0"

启用会话重放功能的会话百分比

初始用户跟踪同意状态，详见用户跟踪同意

boolean

默认值:"false"

是否手动控制视图创建，详见覆盖默认视图名称

boolean

默认值:"true"

是否自动收集用户操作

boolean

默认值:"true"

是否启用资源事件收集

boolean

默认值:"true"

是否启用长任务事件收集

boolean

默认值:"true"

是否启用跨会话的匿名用户 ID 收集

'allow' | 'mask-user-input' | 'mask-all'

默认值:"mask-user-input"

会话重放隐私策略：allow 采集除密码外所有数据，mask-user-input 隐藏用户输入框内容，mask-all 隐藏所有文本

array

用于注入跟踪 Headers 的请求 URL 列表，详见集成分布式追踪

number

默认值:"100"

要跟踪的请求百分比

string

可选代理 URL，例如：https://www.proxy.com/path

boolean

默认值:"false"

是否压缩发送到 Flashduty 的请求，在 Worker 线程中完成

boolean

默认值:"false"

是否将上下文存储在 localStorage 中以跨页面保留

应用场景

自定义用户标识

使用 flashcatRum.setUser() 为当前用户添加标识属性：

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

添加自定义 TAG

初始化 RUM 后，使用 setGlobalContextProperty API 为所有 RUM 事件添加额外的 TAG：

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

flashcatRum.setGlobalContextProperty('activity', {
  hasPaid: true,
  amount: 23.42
});

发送自定义操作

使用 addAction API 创建 RUM 操作并附加上下文属性：

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

function onCheckoutButtonClick(cart) {
  flashcatRum.addAction("checkout", {
    value: cart.value,
    items: cart.items
  });
}

自定义添加 Error

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

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

验证接入

检查网络请求

打开浏览器开发者工具，查看 Network 面板中是否有 https://browser.flashcat.cloud/api/v2/rum 的数据上报请求。

查看控制台数据

访问 Flashduty 控制台，查看 RUM 应用数据是否正常显示。

触发用户交互

在页面上触发一些用户交互（点击、滚动等），验证数据采集是否正常。

数据通常在 2-5 分钟内显示在控制台中。

下一步

高级配置

了解 SDK 的高级配置功能

数据收集

了解 SDK 收集的数据类型

分析看板

查看和分析 RUM 数据

快速开始

分析看板

SDK 接入

性能监控

异常追踪

查看器

会话重放

最佳实践

其他

接入方式

获取应用凭证

接入代码

初始化参数

必填参数

可选参数

应用场景

自定义用户标识

添加自定义 TAG

发送自定义操作

自定义添加 Error

验证接入

下一步

高级配置

数据收集

分析看板

​接入方式

​获取应用凭证

​接入代码

​初始化参数

​必填参数

​可选参数

​应用场景

​自定义用户标识

​添加自定义 TAG

​发送自定义操作

​自定义添加 Error

​验证接入

​下一步

高级配置

数据收集

分析看板

接入方式

获取应用凭证

接入代码

初始化参数

必填参数

可选参数

应用场景

自定义用户标识

添加自定义 TAG

发送自定义操作

自定义添加 Error

验证接入

下一步