rrweb 文档
rrwebDocs

简体中文

English

简体中文

English

应用元数据 ​

应用元数据是附加到录制上的一组字符串键值对。用它可查找相关录制、组合多录制回放，并按发布或灰度上下文进行筛选。

隐私边界 ​

在分配会话、访客或用户标识符之前，请先制定元数据策略。优先使用由你的应用创建的不透明标识符，而不是姓名、邮箱地址、账号或其他可直接识别身份的值。只要你的系统能解析这些不透明标识符，它们仍可能属于个人数据。

为录制和元数据关联建立同意或其他合法依据。定义访问控制，将录制和元数据的访问限制在已授权的角色内，选择与套餐和工作区策略匹配的保留期限，并支持适用的访问与删除请求。当用户撤回同意时，停止录制并停止添加元数据；删除或解除此前收集的录制关联是独立的生命周期操作。

提供给浏览器客户端的元数据在浏览器中是可见的。用户可以在页面状态或网络流量中查看它，任何持有公开写入密钥的人都可以提交浏览器授权的写入。不要将机密或仅限服务器的分类信息放入浏览器元数据，请从经过认证的可信服务器发送。

将录制关联到用户或会话 ​

录制 ID 用于区分各个浏览器上下文（例如不同标签页）。你自己的不透明会话 ID 可以将多个录制 ID 组合为一次跨标签页的回放。不透明的访客或用户 ID 可以找到同一应用身份在不同会话或设备上的录制。

在登录后添加用户 ID，可以把该录制中更早的登录前部分追溯性地关联到已认证用户。这会使用户登录前的活动可以通过登录后的标识符被发现。在做出同意、访问控制、保留与删除决策时把这一关联纳入考量；如果该范围不合适，就不要提交这一更新。

如果你的应用还没有定义这些标识符，请参阅 可选的访客元数据。该可选项与应用元数据相互独立，并且不会让已录制的 DOM 内容变为匿名。

键与值 ​

  • 值以字符串形式存储。序列化布尔值或数字时要有意识地进行，并保持格式稳定。
  • 同一录制提交相同的键会覆盖其之前的值，只保留最新的值。
  • 使用稳定的名称，例如 app_user_id、app_session_id、environment、app_version、feature_flag。
  • 保持 schema 精简，避免原始的、自由格式的用户输入。

浏览器可见的元数据 ​

非机密的应用上下文，在 start() 时或之后通过 addMeta() 设置；机密信息和仅限服务器使用的分类属于下面的服务器路径。

在启动浏览器客户端时附加非机密的应用上下文，或随后使用 addMeta()：

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

start({
  publicApiKey: 'public_key_rr_your_key',
  meta: {
    app_user_id: 'usr_7f3b92a1',
    app_session_id: 'ses_019fd6c3',
    environment: 'production',
    app_version: '2026.08.06',
  },
});

当自动启动配置或 addMeta() 提供这些值时同样适用：将它们视为对浏览器可见。

从受信服务器设置元数据 ​

私有 API 密钥只在可信服务器上使用。下面的示例使用在 API 中有效的录制 UUID，将仅限服务器的元数据直接发送到 捕获元数据操作：

ts
const recordingId = '550e8400-e29b-41d4-a716-446655440000';
const response = await fetch(
  `https://api.rrweb.com/recordings/${recordingId}/metadata`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.RRWEB_CLOUD_PRIVATE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      support_case_id: 'case_019fd6c3',
      account_segment: 'enterprise',
    }),
  },
);

if (!response.ok) {
  throw new Error(`Metadata write failed: ${response.status}`);
}

在发起 Cloud 请求前，先验证已登录的操作员可以更新该录制。绝不要把私有 API 密钥返回给浏览器。

让浏览器通过你的服务器写入元数据 ​

通过一个同源路由代理元数据调用，由你的服务器认证用户、校验归属、推导仅限服务器的字段，并在发起 Cloud 请求前添加私有密钥。

当浏览器动作需要添加必须由你的服务器授权或推导的元数据时，调用同源的应用端点。浏览器只发送录制 ID 和允许的输入；你的服务器负责认证用户、校验归属、推导仅限服务器的字段，然后执行上文所述的经过认证的 Cloud 请求。

ts
const response = await fetch('/api/recording-metadata', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    recordingId: '550e8400-e29b-41d4-a716-446655440000',
    supportCaseId: 'case_019fd6c3',
  }),
});

if (!response.ok) {
  throw new Error('The application could not attach recording metadata');
}

不要把这个同源代理与浏览器直接请求 Cloud API 混淆：私有凭据和授权校验始终保留在你的服务器上。

获取当前录制 ID ​

浏览器客户端在捕获开始时生成录制 ID。通过 getRecordingId() 读取，当需要服务器端数据充实（enrichment）时用经过认证的应用请求发送给你的服务器。不同的标签页获得各自的录制 ID；页面视图是否可以复用 ID 取决于 录制 ID 中描述的浏览器客户端生命周期。

参考 ​