@arms/rum-browser

阿里云 ARMS 用户体验监控 Web & H5 SDK。覆盖页面 PV、性能（含 Web Vitals）、JS 异常、白屏、API（XHR/Fetch/SSE）、用户交互、视图停留与滚动深度、会话回放、Profiling CPU 采集等监控数据，支持分布式链路追踪，并提供产品分析能力（用户身份识别与业务行为 / 元素曝光采集）。

核心特性

• 零配置即用：一次 init() 后默认启用 PV / 性能 / Web Vitals / 异常 / API / 静态资源 / 点击 / 视图统计 / 白屏等采集器，无需逐项开关
• 统一上报通道：批量缓冲 + 失败重试，页面隐藏或卸载时自动完成最终上报，BFCache 与移动端切后台不丢数据
• API 监控全覆盖：
  • XHR / Fetch 全局 patch，自动产出 type='api' 资源事件
  • SSE 流式接口（text/event-stream）独立子采集器，输出 time_to_first_token / inter_token_latency_avg / inter_token_latency_max / message_count 等指标
  • evaluateApi 回调把请求/响应内容写入 snapshots，SDK 自动裁剪至 5KB
• 视图维度增强：view-stats 采集器输出页面停留时长（time_spent）、最大滚动深度、离开页面时的窗口尺寸
• 产品分析（Product Analytics）：登录后 setUser() 把业务账号关联到 SDK 匿名用户 ID，并自动回填登录前的匿名行为区间；通过 data-rum-action / data-rum-expose 声明式采集点击与曝光，或调用 sendAction() 手动上报业务行为；身份事件不受会话采样影响。详见 docs/Product-Analytics开发指南.md
• 会话回放：集成 rrweb 录制全量 DOM 与用户交互，支持 mask / user-input / allowlisted 隐私级别，长会话上报体积通过 deflate 压缩 60%~80%
• Profiling CPU 采集：基于 W3C JS Self-Profiling API（仅 Chrome 系），支持后台自动采样与 armsRum.startProfiling() 手动采集；自动采集默认限会话开启后前 1 小时（maxRecordingDuration 可调），详见 docs/SDK配置参考.md。⚠️ 目前为测试阶段能力，请谨慎开启
• 分布式链路追踪：内置 tracing 配置，支持 W3C tracecontext / B3 / B3 multi / Jaeger / SkyWalking sw8 协议，按 allowedUrls 白名单注入 traceparent 等头
• 远程配置：支持 ARMS 控制台下发配置，动态调整采样率、采集器开关、过滤规则

安装

提供 CDN 异步 / CDN 同步 / NPM 三种接入方式，详见 docs/接入Web&H5应用.md。

另提供精简版：CDN 产物 https://sdk.rum.aliyuncs.com/v2/browser-sdk-slim.js（约 124KB，比完整版小约 63%），NPM 方式可通过子路径 @arms/rum-browser/slim 引入。不需要会话回放、白屏检测与 Profiling 采集时可选用，用法与完整版一致，详见 docs/接入Web&H5应用.md。

npm install @arms/rum-browser

接入流程

第一步：在应用入口尽早 import SDK

init() 务必在业务发起任何 XHR / Fetch 请求之前调用——SDK 通过代理 window.fetch / XMLHttpRequest 实现 API 采集，初始化之前发出的请求采不到。

// src/main.ts
import armsRum from '@arms/rum-browser';

armsRum.init({
  endpoint: '<your-endpoint>',
  env: 'prod',
  version: '1.0.0',
});

第二步：CDN 接入（首屏敏感场景推荐）

将以下片段放在 <head> 中尽可能靠前的位置，SDK 异步加载完成后会自动从 window.__rum.config 读取配置启动：

<script>
  !(function (c, b, d, a) {
    c[a] || (c[a] = {});
    c[a].config = {
      endpoint: '<your-endpoint>',
      env: 'prod',
      version: '1.0.0',
    };
    with (b)
      with (body)
        with (insertBefore(createElement('script'), firstChild))
          setAttribute('crossorigin', '', (src = d));
  })(
    window,
    document,
    'https://sdk.rum.aliyuncs.com/v2/browser-sdk.js',
    '__rum',
  );
</script>

第三步：（可选）验证数据上报

armsRum.init({
  endpoint: '<your-endpoint>',
  beforeReport(bundle) {
    console.log('[RUM]', bundle);
    return bundle; // 返回 undefined 不会丢弃；如需丢弃需在回调里显式处理
  },
});

第四步：（可选）启用 SPA 路由追踪

单页应用必须显式声明 spaMode，否则路由切换不会被视作新页面：

armsRum.init({
  endpoint: '<your-endpoint>',
  spaMode: 'history', // 'hash' | 'history' | 'auto' | true | false
});

第五步：（可选）启用会话回放

armsRum.init({
  endpoint: '<your-endpoint>',
  replay: {
    enable: true,
    sampling: 20, // 20% 会话录制（百分比，0~100）
    privacy: { level: 'mask' }, // 默认遮蔽所有文本与输入框
  },
});

第六步：（可选）启用产品分析（用户身份 + 业务行为）

armsRum.init({
  endpoint: '<your-endpoint>',
  collectors: { expose: true }, // 曝光采集默认关闭，按需开启
});

// 登录成功后关联业务账号（身份状态持久化，刷新后保持登录态）
armsRum.setUser({ name: 'u_10086', properties: { plan: 'pro' } });

<!-- 声明式点击 / 曝光：元素上加 data-rum-action / data-rum-expose -->
<button data-rum-action="加入购物车" data-rum-prop-sku="A1">加入购物车</button>
<div data-rum-expose data-rum-action="商品卡片">…</div>

详见 docs/Product-Analytics开发指南.md。

配置项

init() 接收 IBrowserConfig 配置对象。下表只列出常用字段，完整版见 docs/SDK配置参考.md。

基础配置

说明 用户 ID（user.id）由 SDK 内部自动生成并持久化，不可通过配置传入或修改，上报数据中可直接按 user.id 做用户维度排查。业务账号可通过 user.name / user.properties 配置项或 armsRum.setUser() 等 API 关联（产品分析能力，详见 docs/Product-Analytics开发指南.md）。

Web 专属配置

采集器开关（collectors）

armsRum.init({
  endpoint: '<your-endpoint>',
  collectors: {
    consoleError: false, // 关闭 console.error 拦截
    longTask: true, // 默认关闭，按需启用
    profiling: false, // Profiling CPU 采集（测试阶段能力，谨慎开启）
    expose: { enable: true, threshold: 0.5, minDuration: 500 }, // 曝光采集（默认关闭）
    api: {
      // API 采集器细化配置
      enable: true,
      filters: [/\.internal\.example\.com/], // 命中则不上报
      xhr: true,
      fetch: true,
      sse: { timeout: 30000 }, // SSE 流 30s 无消息判超时
    },
  },
});

evaluateApi：自定义 payload 写入 snapshots

evaluateApi 用于把请求/响应内容写入事件，SDK 不自动采集 payload——业务侧按需在回调里提取并返回 { snapshots: string }，SDK 自动裁剪至 5KB：

armsRum.init({
  endpoint: '<your-endpoint>',
  async evaluateApi(request, response, error, xhr) {
    const snapshot: Record<string, unknown> = {};
    // Fetch：response.clone().text() 读取
    if (response && typeof (response as Response).text === 'function') {
      try {
        const text = await (response as Response).clone().text();
        snapshot.response = text.slice(0, 1024);
      } catch {}
    }
    // XHR：直接读 xhr.responseText
    if (xhr) snapshot.response = xhr.responseText?.slice(0, 1024);

    return {
      success: error || (response as Response)?.status >= 400 ? 0 : 1,
      snapshots: JSON.stringify(snapshot),
    };
  },
});

字段约定：snapshots 留给 SDK / evaluateApi 写采集元数据，properties 保留给用户业务标签。

链路追踪（tracing）

armsRum.init({
  endpoint: '<your-endpoint>',
  tracing: {
    enable: true,
    sample: 10, // 10% 采样（百分比）
    propagatorTypes: ['tracecontext', 'b3'],
    allowedUrls: [/^https:\/\/api\.example\.com/], // 仅向白名单注入追踪头
  },
});

XHR / Fetch / SSE 共用同一份 tracing 决策。allowedUrls 未配置时不会向任何 URL 注入追踪头——避免向第三方域名泄漏内部 traceId。

会话回放（replay）

录制时长上限 单会话录制最长 1 小时，超时自动停止录制。生产环境务必配合 sampling 控制采样率。

运行时 API

import armsRum, { sendEvent } from '@arms/rum-browser';

// 修改单个字段
armsRum.setConfig('enable', false);

// 批量修改
armsRum.setConfig({ env: 'staging', version: '1.1.0' });

// 读取当前完整配置
const config = armsRum.getConfig();

// 获取某个采集器实例（扩展 / 调试用）
const replay = armsRum.getCollector('replay-collector');

// 用户身份（产品分析）：登录 / 属性 / 退出
armsRum.setUser({ name: 'u_10086', properties: { plan: 'pro' } });
armsRum.setUserProperties({ vip: true });
armsRum.unsetUserProperties(['level', 'vip']);
armsRum.reset();

// 业务行为上报（如需表单提交成功、播放完成等非点击场景）
armsRum.sendAction({
  name: '提交订单',
  group: '结算',
  properties: { amount: 747 },
});

// 业务侧自定义事件上报（所有 SDK 实例都会收到）
sendEvent({
  event_type: 'custom',
  type: 'business-event',
  name: 'order-submit',
});

CDN 加载方式下，sendEvent 也可通过全局对象访问：window.RumSDK.sendEvent(event)。

产品分析完整 API（身份状态机、属性规则、匿名区间回填、曝光结算规则等）见 docs/Product-Analytics开发指南.md。

注意事项

1. init() 务必尽早执行：SDK 通过代理 window.fetch / XMLHttpRequest 实现 API 采集，初始化之前发出的请求采不到。
2. CDN 异步加载 vs 同步加载：异步加载不阻塞渲染，但 SDK 启动前的早期错误可能漏采；如对早期错误敏感，可在 <head> 顶部加临时 window.onerror / unhandledrejection 缓冲，SDK 启动后通过 RumSDK.sendEvent() 补报。
3. spaMode 必须与路由实现一致：错配会导致 view 事件采到错误的 path（如把 React BrowserRouter 当成 hash）。
4. evaluateApi 内禁止同步阻塞：回调如抛错会被静默捕获回退到原始事件；读取大 body 请用流式或限制大小，否则会拖慢上报队列。
5. replay 会显著增加上报量：生产环境务必配合 sampling 控制采样率；隐私级别默认 'mask' 不要随意调成 'allow'。
6. tracing.allowedUrls 必须显式声明：未配置时不会注入追踪头，避免向不可控第三方域名泄漏内部 traceId。
7. longTask 默认关闭：长任务事件量大，按需开启；开启后优先用 LoAF，不支持时降级到 longtask（>50ms）。
8. 产品分析身份与隐私：setUser 的 name 建议使用稳定且不含个人敏感信息的业务 ID；身份状态持久化在本地（key：_arms_pa_user:<pid>），如涉及隐私合规请在退出时调用 reset()；曝光采集默认关闭（collectors.expose），元素需同时带 data-rum-expose 与非空 data-rum-action 才会采集。