rrweb 自定义事件机制详解

rrweb 自定义事件机制详解

rrweb record and replay the web 项目地址: https://gitcode.com/gh_mirrors/rr/rrweb

rrweb 作为一款强大的 Web 页面录制与回放工具，提供了丰富的功能来满足各种场景需求。其中自定义事件机制是一个非常有用的特性，它允许开发者在录制过程中插入自定义的业务数据，并在回放时获取这些数据。

什么是自定义事件

自定义事件是 rrweb 提供的一种扩展机制，它允许开发者在录制过程中标记特定的业务时刻，并附加相关的业务数据。这些数据会作为录制数据的一部分被保存下来，在回放时可以获取和使用。

自定义事件的应用场景

自定义事件在以下场景中特别有用：

1. 表单提交记录：记录用户提交表单时的具体数据
2. 错误追踪：捕获页面中的异常信息
3. 关键操作标记：标识用户的关键操作节点
4. 性能指标记录：记录特定操作的性能数据
5. 业务事件追踪：跟踪特定的业务事件发生

如何使用自定义事件

1. 添加自定义事件

在录制过程中，可以通过 record.addCustomEvent API 添加自定义事件：

// 开始录制
rrweb.record({
  emit(event) {
    // 处理录制事件
  }
});

// 添加表单提交事件
rrweb.record.addCustomEvent('form-submit', {
  formId: 'user-register',
  fields: ['name', 'email', 'phone'],
  timestamp: Date.now()
});

// 添加错误事件
rrweb.record.addCustomEvent('js-error', {
  message: error.message,
  stack: error.stack,
  pageUrl: window.location.href
});

2. 参数说明

addCustomEvent 方法接受两个参数：

1. tag（字符串）：事件的标识符，用于区分不同类型的事件
2. payload（任意类型）：与事件相关的数据，可以是对象、数组、字符串等

3. 回放时处理自定义事件

在回放过程中，可以通过监听 custom-event 事件来获取自定义事件：

const replayer = new rrweb.Replayer(events);

replayer.on('custom-event', (event) => {
  if (event.tag === 'form-submit') {
    console.log('表单提交数据:', event.payload);
  } else if (event.tag === 'js-error') {
    console.error('捕获到的错误:', event.payload);
  }
});

4. 在时间轴上可视化

如果使用 rrweb-player 进行回放，可以通过配置 tags 属性在时间轴上可视化自定义事件：

new rrwebPlayer({
  target: document.body,
  props: {
    events,
    tags: {
      'form-submit': '#4CAF50',  // 绿色
      'js-error': '#F44336',     // 红色
      'page-load': '#2196F3',    // 蓝色
    },
  },
});

最佳实践

1. 命名规范：为自定义事件的 tag 制定统一的命名规范，如使用小写字母和连字符
2. 数据结构：保持 payload 的数据结构一致，便于后续处理
3. 适度使用：不要过度使用自定义事件，只记录真正需要的数据
4. 性能考虑：避免在 payload 中包含过大的数据
5. 错误处理：在监听自定义事件时做好错误处理

注意事项

1. 自定义事件会作为录制数据的一部分，增加整体数据量
2. 确保 payload 中的数据是可序列化的，避免包含不可序列化的对象
3. 在回放处理自定义事件时，注意与页面回放的同步问题

通过合理使用自定义事件机制，可以大大增强 rrweb 录制回放的实用性和业务价值，为产品分析、错误排查和用户行为研究提供更多维度的数据支持。

rrweb record and replay the web 项目地址: https://gitcode.com/gh_mirrors/rr/rrweb