> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser RUM SDK

> 安装和配置 MoleSignal Browser RUM SDK，识别用户、添加自定义事件并验证数据接入。

MoleSignal Browser RUM SDK 会采集浏览器会话、页面访问、用户交互、前端错误、Web Vitals、
网络资源以及用于关联链路的上下文。

## 准备工作

接入前提：

* MoleSignal 部署地址；
* 稳定的应用标识，例如 `checkout-web`；
* 可向目标工作区写入 RUM 数据的专用 Token。

<Warning>
  `clientToken` 会包含在浏览器代码中，所有用户都能看到。不要使用所有者、管理员或个人 Token。
  请使用数据源接入向导生成的应用绑定 `msrum_` Client Token。
</Warning>

## 安装与初始化

<Steps>
  <Step title="安装依赖">
    ```bash theme={null}
    npm install @molesignal/browser-rum
    ```
  </Step>

  <Step title="只初始化一次 SDK">
    ```ts theme={null}
    import { initRum } from '@molesignal/browser-rum';

    const rum = initRum({
      applicationId: 'checkout-web',
      clientToken: 'msrum_your_client_token',
      site: 'https://molesignal.example.com',
      service: 'web-frontend',
      env: 'production',
      version: 'v1.4.0',
      sessionSampleRate: 100,
      trackUserInteractions: true,
    });
    ```

    如果需要采集首次页面访问，请在应用路由器挂载前初始化 SDK。服务端渲染期间可以安全地导入并初始化；
    只有浏览器 API 可用时，浏览器监测才会启动。
  </Step>

  <Step title="验证第一个会话">
    打开 **RUM → 概览**，选择包含当前时间的时间范围，确认应用已经出现，然后进入 **会话** 检查第一个会话。
  </Step>
</Steps>

`site` 可以是 MoleSignal Origin、`/api` 基础地址或 `/api/v1` 基础地址。SDK 会自动规范化地址，
并将数据发送到 `/api/v1/rum` 下的 RUM 接口。

## 识别用户并添加上下文

尽量在初始化时提供用户信息，让第一个会话就带有正确身份。

```ts theme={null}
const rum = initRum({
  applicationId: 'checkout-web',
  clientToken: 'msrum_your_client_token',
  site: 'https://molesignal.example.com',
  user: { id: currentUser.id, plan: currentUser.plan },
  globalContext: { region: 'eu-west-1' },
});

rum.setUser({ id: 'user-42', plan: 'enterprise' });
rum.setGlobalContextProperty('feature_flags', ['new-checkout']);
```

如果未提供用户，SDK 会在 `localStorage` 中创建稳定的匿名标识。如果隐私政策不允许持久化匿名身份，
请设置 `trackAnonymousUser: false`。

## 添加自定义操作、错误和页面访问

```ts theme={null}
rum.addAction('Checkout submitted', {
  cart_size: 3,
  payment_method: 'card',
});

try {
  await submitOrder();
} catch (error) {
  rum.addError(error, { component: 'CheckoutForm' });
}

// trackViewsManually 为 true 时使用。
rum.startView('Order confirmation');
```

在受控跳转或关闭前，如果需要等待队列中的事件发送完成，请调用 `rum.flush()`。
调用 `rum.stop()` 会移除监测并刷新客户端队列。

## 自动采集默认值

| 数据              | 配置项                       | 默认值                       |
| --------------- | ------------------------- | ------------------------- |
| 页面访问            | `trackViewsManually`      | 自动跟踪 History API（`false`） |
| Fetch、XHR 和资源耗时 | `trackResources`          | `true`                    |
| Long Task       | `trackLongTasks`          | `true`                    |
| Web Vitals      | `trackWebVitals`          | `true`                    |
| 点击和表单提交         | `trackUserInteractions`   | `false`                   |
| 愤怒点击和无效点击       | `trackFrustrations`       | 与交互跟踪保持一致                 |
| 运行时错误           | 内置                        | 已启用                       |
| `console.error` | `trackConsoleErrors`      | `false`                   |
| DOM 会话回放        | `sessionReplaySampleRate` | `0`                       |

## 将浏览器请求关联到链路

Fetch 和 XMLHttpRequest 集成会从传出请求、响应或名为 `traceparent` 的 `Server-Timing` 条目中读取
W3C `traceparent`。对于跨域 API，请显式放行来源并暴露响应头：

```http theme={null}
Access-Control-Expose-Headers: traceparent, server-timing
```

```ts theme={null}
allowedTracingUrls: [
  'https://api.example.com',
  /^https:\/\/edge-\w+\.example\.com\//,
]
```

## 后续步骤

<CardGroup cols={2}>
  <Card title="数据采样" icon="sliders" href="/zh-Hans/rum/sampling">
    分别控制会话和回放数据量。
  </Card>

  <Card title="隐私" icon="shield" href="/zh-Hans/rum/privacy">
    在用户设备上拦截敏感数据。
  </Card>

  <Card title="会话回放" icon="video" href="/zh-Hans/rum/session-replay">
    安全地记录和回放 DOM 变化。
  </Card>

  <Card title="Source Maps 与 Symbols" icon="file-code" href="/zh-Hans/rum/source-maps">
    还原压缩后的 Browser 堆栈，并查看统一调试产物流程。
  </Card>
</CardGroup>