rrweb 文档
rrwebDocs

简体中文

English

简体中文

English

浏览器客户端 ​

Public API Key Format

Your public API key starts with public_key_rr_ followed by an alphanumeric string (e.g., public_key_rr_1Q8A…). This key identifies your tenant and ensures proper data isolation. This key is safe to use in browser-side code as it only has write permissions.
🛈 Sign In or create an account in the rrweb Cloud dashboard to see your API Keys inline in these docs!

rrweb 浏览器客户端在浏览器中录制 rrweb 事件，并将其发送到 rrweb Cloud。对于使用打包器构建的应用代码，请使用 npm 包。

在生产页面启用之前，请先在录制和隐私设置中选择屏蔽、脱敏、采样和高级捕获行为。

通过 npm 安装 ​

从 npm 安装 @rrweb/browser-client，并用你的公开 API 密钥调用 start()；它会通过 WebSocket 将事件流式传输到 rrweb Cloud，在 WebSocket 不可用时回退到 HTTP POST。

bash
npm install @rrweb/browser-client

使用你的公开 API 密钥开始录制：

javascript
import { start } from '@rrweb/browser-client';

start({
  publicApiKey: 'your-public-api-key-here',
});

标准的 rrweb Cloud 连接会通过 WebSocket 流式传输事件到 https://api.rrweb.com/。当 WebSocket 不可用或 WebSocket 连接中断时（例如页面卸载时），浏览器客户端还会使用 POST 端点作为回退。

通过 CDN 安装 ​

当你无法打包 npm 包，或需要 script 标签集成时，请加载 CDN 模块构建；对于经典的 script 标签用法，也提供暴露 window.rrwebBrowserClient 并支持 autostart 属性的 UMD 构建。

从 npm 打包仍然是应用代码的推荐默认方式，因为它可以让你锁定并审查所发布的确切版本。

html
<script type="module">
  import { start } from 'https://cdn.rrweb.com/browser-client/next/browser-client.js';

  start({
    publicApiKey: 'your-public-api-key-here',
  });
</script>

如果你需要经典的全局 script 标签，请使用位于 https://cdn.rrweb.com/browser-client/next/browser-client.umd.min.cjs 的 UMD 构建。UMD 构建会暴露 window.rrwebBrowserClient，并支持 autostart 属性。

自定义配置 ​

向 start() 传递一个配置对象，或者在带有 autostart 的 UMD script 标签用法中，在 <script> 标签体内提供相同的 JSON 配置。

关于浏览器客户端自有选项与转发给 record() 的 rrweb 选项之间的区别，请参阅录制和隐私设置。

浏览器客户端选项 ​

  • publicApiKey（必填）：用于认证的公开 API 密钥。该密钥用于标识你的租户，并且只有写入权限，因此在浏览器端代码中使用是安全的。可从你的 rrweb Cloud 仪表板获取。
  • serverUrl：可选的事件端点。默认为 https://api.rrweb.com/recordings/{recordingId}/events/ws。URL 中需包含 {recordingId}，否则客户端会将录制 ID 作为查询参数添加。http 和 https URL 会被转换为 ws 和 wss 用于 WebSocket 连接，而 HTTP 回退会向去掉结尾 /ws 的同一端点发起 POST。UMD script 标签安装方式在省略此选项时，也可以从托管脚本 URL 推断。当需要通过你自己的域名路由事件时，请参阅录制端点代理。
  • includePii（默认：false）：是否包含可能涉及个人身份信息的可选访客元数据。请参阅可选访客元数据指南。
  • autostart（默认：false）：仅与 script 标签用法相关。它控制脚本是否在页面就绪后立即调用 start()。
  • jsSource：可选的来源标识符，用于编程式加载器。URL 值在记录时会去掉查询字符串和哈希。
  • jsEntrypoint：可选的入口标签。直接调用 start() 时默认为 programmatic，script 标签自动启动时默认为 script-tag。
javascript
import { start } from '@rrweb/browser-client';

start({
  // REQUIRED: your public API key
  publicApiKey: 'your-public-api-key-here',

  // Standard rrweb recording options can be mixed in.
  blockSelector: '.my-block-class',
  inlineImages: false,
  recordCanvas: false,
});

附加应用元数据 ​

在初始配置中提供一个 meta 对象，将键/值对与录制关联起来，以便之后能以对你的应用有意义的方式检索；如果需要在录制已经开始后再关联数据，请使用 addMeta()。

请参阅应用元数据指南，其中还展示了如何在服务端关联元数据，而无需将其暴露给前端。

javascript
import { start } from '@rrweb/browser-client';

start({
  publicApiKey: 'your-public-api-key-here',
  meta: {
    user_id: 'user-123',
    session_id: 'existing-session-id',
    org_id: 'org-9',
    plan: 'pro',
    environment: 'production',
  },
});

覆盖 rrweb 录制选项 ​

在 start() 配置中，将 rrweb 录制选项与 publicApiKey 一起传入；在覆盖之前，请通过录制和隐私设置查看 Cloud 默认值和兼容性。

完整的共享 API 请参阅 rrweb 录制选项。

javascript
import { start } from '@rrweb/browser-client';

start({
  publicApiKey: 'your-public-api-key-here',
  meta: {
    session_id: 'existing-session-id',
  },
  blockSelector: '.my-block-class',
  inlineImages: false,
  recordCanvas: false,
});

浏览器客户端 API ​

start() ​

开始一次录制并建立 WebSocket 摄取。它封装了 rrweb 录制和 rrweb Cloud 传输。

javascript
import { start } from '@rrweb/browser-client';

start({
  publicApiKey: 'your-public-api-key-here',
});

getRecordingId() ​

浏览器客户端生成的每次录制都与一个存储在浏览器 sessionStorage 中的录制 ID 关联。这可以区分多标签浏览会话中的不同标签页。

如果你在 start() 之前调用 getRecordingId()，浏览器客户端会创建一个 ID，并在录制开始时使用它。如果录制 ID 为 null，则无法进行会话录制，因为该 ID 是服务端存储录制数据的主键。

javascript
import { getRecordingId } from '@rrweb/browser-client';

const recordingId = getRecordingId();

if (recordingId) {
  console.log(`
    recording can be retrieved from
    https://api.rrweb.com/recordings/${recordingId}
  `);
} else {
  console.log('recording not possible due to sessionStorage restrictions');
}

addMeta() ​

addMeta() 将键和值与一次录制关联。之后在检索录制列表时可以使用这些键值。

另请参阅等效的 API 端点：POST /recordings/{recordingId}/metadata。

如果多次调用 addMeta()，新键会被添加，已有键会被更新。

javascript
import { addMeta } from '@rrweb/browser-client';

addMeta({
  user_id: 'user-123',
  org_id: 'org-9',
  plan: 'pro',
  environment: 'production',
});

如果你更喜欢分组访问，默认的客户端导出也暴露了相同的方法：

javascript
import rrwebClient from '@rrweb/browser-client';

rrwebClient.addMeta({
  user_id: 'user-123',
});

addPageviewMeta() ​

addPageviewMeta() 将键和值与当前页面浏览关联。当元数据应描述当前 URL 或路由，而不是整个录制时，请使用它。

javascript
import { addPageviewMeta } from '@rrweb/browser-client';

addPageviewMeta({
  route_name: 'Checkout',
  experiment: 'new-payment-flow',
});

addCustomEvent() ​

addCustomEvent() 将一个自定义 rrweb 事件加入队列。用于那些应在回放中可见的应用特定时刻。

javascript
import { addCustomEvent } from '@rrweb/browser-client';

addCustomEvent('cart-updated', {
  item_count: 3,
});

stop(false) ​

stop(false) 会立即停止底层的 rrweb 录制器并断开 WebSocket 连接，但不会清除录制 ID。你可以在同一页面上再次调用 start()。下一次录制会以一个新的 rrweb FullSnapshot（全量快照）事件开始，并继续使用当前的录制 ID。

javascript
import { stop } from '@rrweb/browser-client';

stop(false);

stop(true) ​

调用 stop(true) 还会从存储中清除 recordingId。下一次 start() 调用会使用一个全新的录制 ID。当你通过元数据分配会话 ID，并希望新的浏览器会话以 FullSnapshot（全量快照）开始时，这会很有用。

javascript
import { stop } from '@rrweb/browser-client';

stop(true);

通过 CDN 手动开始录制 ​

导入 CDN 模块，并在你的应用就绪时调用 start()，例如在检查完是否应录制该会话之后。

html
<script type="module">
  import { start } from 'https://cdn.rrweb.com/browser-client/next/browser-client.js';

  if (shouldRecordSession()) {
    start({
      publicApiKey: 'your-public-api-key-here',
      includePii: false,
    });
  }
</script>