Skip to content

Latest commit

 

History

History
439 lines (342 loc) · 23.8 KB

guide.zh_CN.md

File metadata and controls

439 lines (342 loc) · 23.8 KB

使用指南

除通用的使用指南外,你可能还想通过场景示例了解特定场景下的使用方式,或是通过设计文档深入 rrweb 的技术细节。

安装

直接通过 <script> 引入

推荐通过 jsdelivr 的 CDN 安装:

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/rrweb@latest/dist/rrweb.min.css"
/>
<script src="https://cdn.jsdelivr.net/npm/rrweb@latest/dist/rrweb.min.js"></script>

也可以在 URL 中指定具体的版本号,例如:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/rrweb.min.js"></script>

仅引入录制部分

rrweb 代码分为录制和回放两部分,大多数时候用户在被录制的应用中只需要引入录制部分代码,同样可以通过 CDN 安装:

<script src="https://cdn.jsdelivr.net/npm/rrweb@latest/dist/record/rrweb-record.min.js"></script>

其它按需引入方式

除了仅包含录制代码的 record/rrweb-record-min.js 之外,rrweb 还提供了其它多种可选的打包文件。所有包含 .min 的文件为同名文件的压缩版。

# 包含录制、回放、压缩数据、解压缩数据
rrweb-all.js
rrweb-all.min.js
# 包含录制、回放
rrweb.js
rrweb.min.js
# 回放所需的样式文件
rrweb.min.css
# 录制
record/rrweb-record.js
record/rrweb-record.min.js
# 压缩数据
record/rrweb-record-pack.js
record/rrweb-record-pack.min.js
# 回放
replay/rrweb-replay.js
replay/rrweb-replay.min.js
# 解压缩数据
replay/rrweb-replay-unpack.js
replay/rrweb-replay-unpack.min.js

通过 npm 引入

npm install --save rrweb

rrweb 同时提供 commonJS 和 ES modules 两种格式的打包文件,易于和常见的打包工具配合使用。

兼容性

由于使用 MutationObserver API,rrweb 不支持 IE11 以下的浏览器。可以从这里找到兼容的浏览器列表。

快速开始

录制

如果通过 <script> 的方式仅引入录制部分,那么可以访问到全局变量 rrwebRecord,它和全量引入时的 rrweb.record 使用方式完全一致,以下示例代码将使用后者。

rrweb.record({
  emit(event) {
    // 用任意方式存储 event
  },
});

rrweb 在录制时会不断将各类 event 传递给配置的 emit 方法,你可以使用任何方式存储这些 event 以便之后回放。

调用 record 方法将返回一个函数,调用该函数可以终止录制:

let stopFn = rrweb.record({
  emit(event) {
    if (events.length > 100) {
      // 当事件数量大于 100 时停止录制
      stopFn();
    }
  },
});

一个更接近实际真实使用场景的示例如下:

let events = [];

rrweb.record({
  emit(event) {
    // 将 event 存入 events 数组中
    events.push(event);
  },
});

// save 函数用于将 events 发送至后端存入,并重置 events 数组
function save() {
  const body = JSON.stringify({ events });
  events = [];
  fetch('http://YOUR_BACKEND_API', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body,
  });
}

// 每 10 秒调用一次 save 方法,避免请求过多
setInterval(save, 10 * 1000);

配置参数

rrweb.record(config) 的 config 部分接受以下参数

key 默认值 功能
emit 必填 获取当前录制的数据
checkoutEveryNth - 每 N 次事件重新制作一次全量快照
详见“重新制作快照”章节
checkoutEveryNms - 每 N 毫秒重新制作一次全量快照
详见“重新制作快照”章节
blockClass 'rr-block' 字符串或正则表达式,可用于自定义屏蔽元素的类名,详见“隐私”章节
blockSelector null 所有 element.matches(blockSelector)为 true 的元素都不会被录制,回放时取而代之的是一个同等宽高的占位元素
ignoreClass 'rr-ignore' 字符串或正则表达式,可用于自定义忽略元素的类名,详见“隐私”章节
ignoreCSSAttributes null 应该被忽略的 CSS 属性数组
maskTextClass 'rr-mask' 字符串或正则表达式,可用于自定义忽略元素 text 内容的类名,详见“隐私”章节
maskTextSelector null 所有 element.matches(maskTextSelector)为 true 的元素及其子元素的 text 内容将会被屏蔽
maskAllInputs false 将所有输入内容记录为 *
maskInputOptions { password: true } 选择将特定类型的输入框内容记录为 *
类型详见列表
maskInputFn - 自定义特定类型的输入框内容记录逻辑
maskTextFn - 自定义文字内容的记录逻辑
slimDOMOptions {} 去除 DOM 中不必要的部分
类型详见列表
inlineStylesheet true 是否将样式表内联
hooks {} 各类事件的回调
类型详见列表
packFn - 数据压缩函数,详见优化存储策略
sampling - 数据抽样策略,详见优化存储策略
dataURLOptions {} Canvas 图像快照的格式和质量,这个参数将传递给 OffscreenCanvas.convertToBlob(),使用这个参数能有效减小录制数据的大小
recordCanvas false 是否记录 canvas 内容, 可用选项:false, true
recordCrossOriginIframes false 是否记录 cross origin iframes。 必须在每个子 iframe 中注入 rrweb 才能使其工作。 可用选项:false, true
recordAfter 'load' 如果 document 还没有加载完成,recorder 将会在指定的事件触发后开始录制。可用选项: DOMContentLoaded, load
inlineImages false 是否将图片内容记内联录制
collectFonts false 是否记录页面中的字体文件
userTriggeredOnInput false 什么是 userTriggered
plugins [] 加载插件以获得额外的录制功能. 什么是插件?
errorHandler - 一个可以定制化处理错误的毁掉函数,它的参数是错误对象。如果 rrweb recorder 内部的某些内容抛出错误,则会调用该回调。

隐私

页面中可能存在一些隐私相关的内容不希望被录制,rrweb 为此做了以下支持:

  • 在 HTML 元素中添加类名 .rr-block 将会避免该元素及其子元素被录制,回放时取而代之的是一个同等宽高的占位元素。
  • 在 HTML 元素中添加类名 .rr-ignore 将会避免录制该元素的输入事件。
  • 所有带有.rr-mask类名的元素及其子元素的 text 内容将会被屏蔽。
  • input[type="password"] 类型的密码输入框默认不会录制输入事件。
  • 配置中还有更为丰富的隐私保护选项。

重新制作快照

默认情况下,要重放内容需要所有的 event,如果你不想存储所有的 event,可以使用checkout配置。

多数时候你不必这样配置。但比如在页面错误发生时,你只想捕获最近的几次 event ,这里有一个例子:

// 使用二维数组来存放多个 event 数组
const eventsMatrix = [[]];

rrweb.record({
  emit(event, isCheckout) {
    // isCheckout 是一个标识,告诉你重新制作了快照
    if (isCheckout) {
      eventsMatrix.push([]);
    }
    const lastEvents = eventsMatrix[eventsMatrix.length - 1];
    lastEvents.push(event);
  },
  checkoutEveryNth: 200, // 每 200 个 event 重新制作快照
});

// 向后端传送最新的两个 event 数组
window.onerror = function () {
  const len = eventsMatrix.length;
  const events = eventsMatrix[len - 2].concat(eventsMatrix[len - 1]);
  const body = JSON.stringify({ events });
  fetch('http://YOUR_BACKEND_API', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body,
  });
};

由于 rrweb 使用了增量快照机制,我们不能指定数量来捕获最近的几次 event。上面这个例子,你可以拿到最新的 200-400 个 event 来发送给你的后端。

类似的,你可以通过配置 checkoutEveryNms 来捕获最近指定时间的 event :

// 使用二维数组来存放多个 event 数组
const eventsMatrix = [[]];

rrweb.record({
  emit(event, isCheckout) {
    // isCheckout 是一个标识,告诉你重新制作了快照
    if (isCheckout) {
      eventsMatrix.push([]);
    }
    const lastEvents = eventsMatrix[eventsMatrix.length - 1];
    lastEvents.push(event);
  },
  checkoutEveryNms: 5 * 60 * 1000, // 每5分钟重新制作快照
});

// 向后端传送最新的两个 event 数组
window.onerror = function () {
  const len = eventsMatrix.length;
  const events = eventsMatrix[len - 2].concat(eventsMatrix[len - 1]);
  const body = JSON.stringify({ events });
  fetch('http://YOUR_BACKEND_API', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body,
  });
};

在上面的例子中,你最终会拿到最新的 5-10 分钟的 event 来发送给你的后端。

回放

回放时需要引入对应的 CSS 文件:

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/rrweb@latest/dist/rrweb.min.css"
/>

再通过以下 JS 代码初始化 replayer:

const events = YOUR_EVENTS;

const replayer = new rrweb.Replayer(events);
replayer.play();

使用 API 控制回放

const replayer = new rrweb.Replayer(events);

// 播放
replayer.play();

// 从第 3 秒的内容开始播放
replayer.play(3000);

// 暂停
replayer.pause();

// 暂停至第 5 秒处
replayer.pause(5000);

// 销毁播放器 (提示: 这个操作不可逆)
replayer.destroy();

配置参数

可以通过 new rrweb.Replayer(events, options) 的方式向 rrweb 传递回放时的配置参数,具体配置如下:

key 默认值 功能
speed 1 回放倍速
root document.body 回放时使用的 HTML 元素
loadTimeout 0 加载异步样式表的超时时长
skipInactive false 是否快速跳过无用户操作的阶段
showWarning true 是否在回放过程中打印警告信息
showDebug false 是否在回放过程中打印 debug 信息
blockClass 'rr-block' 需要在回放时展示为隐藏区域的元素类名
liveMode false 是否开启直播模式
insertStyleRules [] 可以传入多个 CSS rule string,用于自定义回放时 iframe 内的样式
triggerFocus true 回放时是否回放 focus 交互
UNSAFE_replayCanvas false 回放时是否回放 canvas 内容,开启后将会关闭沙盒策略,导致一定风险
pauseAnimation true 当播放器停止播放时,是否将 CSS 动画也停止播放
mouseTail true 是否在回放时增加鼠标轨迹。传入 false 可关闭,传入对象可以定制轨迹持续时间、样式等,配置详见类型
unpackFn - 数据解压缩函数,详见优化存储策略
plugins [] 加载插件以获得额外的回放功能. 什么是插件?
useVirtualDom true 在播放器跳转到一个新的时间点的过程中,是否使用 Virtual Dom 优化
logger console 当播放器出现警告或错误时用来打印日志的对象

使用 rrweb-player

rrweb 自带的回放只提供所有的 JS API 以及最基本的 UI,如果需要功能更强的回放播放器 UI,可以使用 rrweb-player。

安装

rrweb-player 同样可以使用 CDN 方式安装:

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/rrweb-player@latest/dist/style.css"
/>
<script src="https://cdn.jsdelivr.net/npm/rrweb-player@latest/dist/index.js"></script>

或者通过 npm 安装:

npm install --save rrweb-player
import rrwebPlayer from 'rrweb-player';
import 'rrweb-player/dist/style.css';
使用

通过 props 传入 events 数据及配置项

new rrwebPlayer({
  target: document.body, // 可以自定义 DOM 元素
  // 配置项
  props: {
    events,
  },
});
配置项参数
key 默认值 功能
events [] 包含回放所需的数据
width 1024 播放器宽度
height 576 播放器高度
autoPlay true 是否自动播放
speedOption [1, 2, 4, 8] 倍速播放可选值
showController true 是否显示播放器控制 UI
tags {} 可以以 key value 的形式展示自定义事件在时间轴上的颜色
... - 其它所有 rrweb Replayer 的配置参数均可透传

事件

开发者可能希望监听回放时的各类事件,例如在跳过无用户操作的时间时给用户一些提示。

rrweb 的 Replayer 提供了 on API 用于提供该功能

const replayer = new rrweb.Replayer(events);
replayer.on(EVENT_NAME, (payload) => {
  ...
})

其包含的事件如下:

事件类型 描述
start 回放开始 -
pause 回放暂停 -
finish 回放完成 -
resize 回放视图大小发生变化 { width, height }
fullsnapshot-rebuilded 全量快照完成重建 event
load-stylesheet-start 开始加载远端样式表 -
load-stylesheet-end 加载远端样式表完成 -
skip-start 开始跳过无用户操作时间 { speed }
skip-end 结束无用户操作时间 { speed }
mouse-interaction 回放鼠标交互事件 { type, target }
event-cast 回放 event event
custom-event 回放自定义事件 event
destroy 销毁播放器 -

使用 rrweb-player 时,也可以通过 addEventListener API 使用相同的事件功能,并且会获得 3 个额外的事件:

事件类型 描述
ui-update-current-time 当前回放时间点 { payload }
ui-update-player-state 当前回放状态 { payload }
ui-update-progress 当前回放百分比 { payload }

REPL 工具

在不安装 rrweb 的情况下,也可以通过使用 REPL 工具试用 rrweb 录制 web 应用。

运行 yarn repl,将会启动浏览器并在命令行要求输入一个测试的 url:

Enter the url you want to record, e.g https://react-redux.realworld.io:

输入后等待浏览器打开指定页面,并在命令行中出现以下提示信息:

Enter the url you want to record, e.g https://react-redux.realworld.io: https://github.com
Going to open https://github.com...
Ready to record. You can do any interaction on the page.
Once you want to finish the recording, enter 'y' to start replay:

此时可以在页面中进行交互,待所需录制操作完成后,在命令行输入 y,测试工具就会将刚刚的操作进行回放,用于验证录制是否成功。

回放时命令行中将出现以下提示信息:

Enter 'y' to persistently store these recorded events:

此时可以再次在命令行中输入 y,测试工具将把已录制的内容存入一个静态 HTML 文件中,并提示存放位置:

Saved at PATH_TO_YOUR_REPO/temp/replay_2018_11_23T07_53_30.html

该文件默认使用最新 bundle 的 rrweb 代码,所以我们可以在修改代码后运行 npm run bundle:browser,之后刷新静态文件就可以查看最新代码对回放的影响并进行调试。