rrweb 文档
rrwebDocs

简体中文

English

简体中文

English

@rrweb/browser-client ​

概述 ​

用于将 rrweb 会话录制到兼容 rrweb Cloud 的 API 的浏览器客户端。它封装了 rrweb 录制，通过 WebSocket 流式传输事件，并为缓冲的事件提供 HTTP POST 回退。

本 README 介绍 npm/ESM 包。关于托管脚本代码片段以及更完整的 rrweb Cloud 设置，请参阅 JavaScript SDK 指南。

安装 ​

bash
npm install @rrweb/browser-client

快速开始 ​

js
import rrwebBrowserClient, {
  start,
  stop,
  addMeta,
  getRecordingId,
} from '@rrweb/browser-client';

start({
  publicApiKey: 'public_key_rr_...',
  includePii: false,
  meta: {
    userId: 'user-123',
    environment: 'production',
  },
});

addMeta({ plan: 'pro' });

console.log('recording id', getRecordingId());
stop(false);

默认导出暴露了相同的方法：

js
rrwebBrowserClient.start({
  publicApiKey: 'public_key_rr_...',
});

选项 ​

  • serverUrl：可选的事件端点。默认为 https://api.rrweb.com/recordings/{recordingId}/events/ws。自定义 URL 中需包含 {recordingId}，否则客户端会将其作为查询参数添加。http 和 https URL 会被转换为 ws 和 wss 用于 WebSocket 连接，而 HTTP 回退会向去掉结尾 /ws 的同一端点发起 POST。当通过你自己的域名路由事件时，请参阅录制端点代理。
  • publicApiKey：随 WebSocket 和 HTTP 回退请求一同发送的公开只写 API 密钥。rrweb Cloud 的公开密钥采用 public_key_rr_... 格式。请参阅 API 密钥。
  • includePii：默认 false。启用后，客户端会包含额外的访客元数据，例如语言、时区、屏幕尺寸、标题和 referrer 信息。请参阅可选访客元数据。
  • meta：在录制事件之前发送的自定义录制元数据。内置诊断信息（如 recordVersion、recordCommitHash、jsSource 和 jsEntrypoint）会在自定义元数据之后自动添加。请参阅应用元数据。
  • jsSource：可选的来源标识符，用于程序化加载器。URL 值在记录时会去除查询字符串和哈希。
  • jsEntrypoint：可选的入口标签。直接调用 start() 时默认为 programmatic，script 标签自动启动时默认为 script-tag。
  • rrweb 录制选项：其他选项会透传给 rrweb 的 record()，例如脱敏、屏蔽、采样和 DOM 捕获选项。请参阅 rrweb 录制文档。

样式表捕获 ​

目前使用 inlineStylesheet 实现样式表捕获兼容。待 assets 分支的 captureAssets 录制 API 落地后，captureAssets.stylesheets 将取代该兼容路径。

录制辅助方法 ​

  • getRecordingId()：返回当前录制 ID，如有需要会在 start() 之前创建。录制 ID 存储在 sessionStorage 中，因此不同标签页拥有独立的录制上下文。
  • addMeta(payload)：在录制开始后添加或更新录制元数据。
  • addPageviewMeta(payload)：为当前页面浏览添加元数据。
  • addCustomEvent(tag, payload)：将一个自定义 rrweb 事件加入队列。
  • stop(resetRecordingId)：停止 rrweb 录制并关闭 WebSocket。传入 true 可在下次 start() 之前清除已存储的录制 ID。

延伸阅读 ​

本地开发/测试环境变量 ​

运行本地集成测试时，将本包中的 .env.example 复制为 .env。

bash
VITE_RRWEB_BROWSER_CLIENT_SERVER_URL=http://localhost:8787/recordings/{recordingId}/events/ws
VITE_RRWEB_BROWSER_CLIENT_API_BASE_URL=http://localhost:8787
VITE_TEST_API_KEY=public_key_rr_XXXX

在 GitHub 上编辑 README

@rrweb/browser-client 发布说明 ​

2.1.1 ​

补丁变更 ​

  • 更新依赖 []：
    • rrweb@2.1.1
    • @rrweb/record@2.1.1
    • @rrweb/types@2.1.1
    • @rrweb/utils@2.1.1

2.1.0 ​

补丁变更 ​

2.0.1 ​

补丁变更 ​

  • 更新依赖 [5f52d63]：
    • rrweb@2.0.1
    • @rrweb/utils@2.0.1
    • @rrweb/record@2.0.1
    • @rrweb/types@2.0.1

2.0.0 ​

补丁变更 ​