update docs

docs/recipes/canvas.md

@@ -0,0 +1,23 @@
+# Canvas
+
+Canvas is a special HTML element, which will not be recorded by rrweb by default. There are some options for recording and replaying Canvas.
+
+Enable recording Canvas：
+
+```js
+rrweb.record({
+  emit(event) {},
+  recordCanvas: true,
+});
+```
+
+Enable replaying Canvas：
+
+```js
+const replayer = new rrweb.Replayer(events, {
+  UNSAFE_replayCanvas: true,
+});
+replayer.play();
+```
+
+**Enable replaying Canvas will remove the sandbox, which may cause a potential security issue.**

docs/recipes/custom-event.md

@@ -0,0 +1,53 @@
+# Custom Event
+
+You may need to record some custom events along with the rrweb events, and let them be played as other events. The custom event API was designed for this.
+
+After starting the recording, we can call the `record.addCustomEvent` API to add a custom event.
+
+```js
+// start recording
+rrweb.record({
+  emit(event) {
+    ...
+  }
+})
+
+// record some custom events at any time
+rrweb.record.addCustomEvent('submit-form', {
+  name: 'Adam',
+  age: 18
+})
+rrweb.record.addCustomEvent('some-error', {
+  error
+})
+```
+
+`addCustomEvent` accepts two parameters. The first one is a string-type `tag`, while the second one is an any-type `payload`.
+
+During the replay, we can add an event listener to custom events, or configure the style of custom events in rrweb-player's timeline.
+
+**Listen to custom events**
+
+```js
+const replayer = new rrweb.Replayer(events);
+
+replayer.on('custom-event', (event) => {
+  console.log(event.tag, event.payload);
+});
+```
+
+**Display in rrweb-player**
+
+```js
+new rrwebPlayer({
+  target: document.body,
+  props: {
+    events,
+    // configure the color of tag which will be displayed on the timeline
+    tags: {
+      'submit-form': '#21e676',
+      'some-error': 'red',
+    },
+  },
+});
+```

docs/recipes/customize-replayer.md

@@ -0,0 +1,72 @@
+# Customize the Replayer
+
+When rrweb's Replayer and the rrweb-player UI do not fit your need, you can customize your replayer UI.
+
+There are several ways to do this:
+
+1. Use rrweb-player, and customize its CSS.
+2. Use rrweb-player, and set `showController: false` to hide the controller UI. With this config, you can implement your controller UI.
+3. Use the `insertStyleRules` options to inject some CSS into the replay iframe.
+4. Develop a new replayer UI with rrweb's Replayer.
+
+## Implement Your Controller UI
+
+When using rrweb-player, you can hide its controller UI:
+
+```js
+new rrwebPlayer({
+  target: document.body,
+  props: {
+    events,
+    showController: false,
+  },
+});
+```
+
+When you are implementing a controller UI, you may need to interact with rrweb-player.
+
+The follwing APIs show some common use case of a controller UI:
+
+```js
+// toggle between play and pause
+rrwebPlayer.toggle();
+// play
+rrwebPlayer.play();
+// pause
+rrwebPlayer.pause();
+// update the dimension
+rrwebPlayer.$set({
+  width: NEW_WIDTH,
+  height: NEW_HEIGHT,
+});
+rrwebPlayer.triggerResize();
+// toggle whether to skip the inactive time
+rrwebPlayer.toggleSkipInactive();
+// set replay speed
+rrwebPlayer.setSpeed(2);
+// go to some timing
+rrwebPlayer.goto(3000);
+```
+
+And there are some ways to listen rrweb-player's state:
+
+```js
+// get current timing
+rrwebPlayer.addEventListener('ui-update-current-time', (event) => {
+  console.log(event.detail.payload);
+});
+
+// get current state
+rrwebPlayer.addEventListener('ui-update-player-state', (event) => {
+  console.log(event.detail.payload);
+});
+
+// get current progress
+rrwebPlayer.addEventListener('ui-update-progress', (event) => {
+  console.log(event.detail.payload);
+});
+```
+
+## Develop a new replayer UI with rrweb's Replayer.
+
+Please refer [rrweb-player](https://github.com/rrweb-io/rrweb-player).

docs/recipes/dive-into-event.md

@@ -0,0 +1,70 @@
+# Dive Into Events
+
+The events recorded by rrweb are a set of strictly-typed JSON data. You may discover some flexible ways to use them when you are familiar with the details.
+
+## Data Types
+
+Every event has a `timestamp` attribute to record the time it was emitted.
+
+There is also a `type` attribute indicates the event's type, the semantic of event's type is:
+
+```
+type -> EventType.DomContentLoaded
+event -> domContentLoadedEvent
+
+type = EventType.Load
+event -> loadedEvent
+
+type -> EventType.FullSnapshot
+event -> fullSnapshotEvent
+
+type -> EventType.IncrementalSnapshot
+event -> incrementalSnapshotEvent
+
+type -> EventType.Meta
+event -> metaEvent
+
+type -> EventType.Custom
+event -> customEvent
+```
+
+The EventType is Typescript's numeric enum, which is a self-increased number from 0 in runtime. You can find its definition in this [list](https://github.com/rrweb-io/rrweb/blob/9488deb6d54a5f04350c063d942da5e96ab74075/src/types.ts#L10).
+
+In these kinds of events, the incrementalSnapshotEvent is the event that contains incremental data. You can use `event.data.source` to find which kind of incremental data it belongs to:
+
+```
+source -> IncrementalSource.Mutation
+data -> mutationData
+
+source -> IncrementalSource.MouseMove
+data -> mousemoveData
+
+source -> IncrementalSource.MouseInteraction
+data -> mouseInteractionData
+
+source -> IncrementalSource.Scroll
+data -> scrollData
+
+source -> IncrementalSource.ViewportResize
+data -> viewportResizeData
+
+source -> IncrementalSource.Input
+data -> inputData
+
+source -> IncrementalSource.TouchMove
+data -> mouseInteractionData
+
+source -> IncrementalSource.MediaInteraction
+data -> mediaInteractionData
+
+source -> IncrementalSource.StyleSheetRule
+data -> styleSheetRuleData
+
+source -> IncrementalSource.CanvasMutation
+data -> canvasMutationData
+
+source -> IncrementalSource.Font
+data -> fontData
+```
+
+enum IncrementalSource's definition can be found in this [list](https://github.com/rrweb-io/rrweb/blob/master/src/types.ts#L64).

docs/recipes/export-to-video.md

@@ -0,0 +1,7 @@
+# Convert To Video
+
+The event data recorded by rrweb is a performant, easy to compress, text-based format. And the replay is also pixel perfect.
+
+But if you really need to convert it into a video format, there are some tools that can do this work.
+
+Use [rrvideo](https://github.com/rrweb-io/rrvideo).

docs/recipes/index.md

@@ -0,0 +1,67 @@
+# Recipes
+
+> You may also want to read the [guide](../../guide.md) to understand the APIs, or read the [design docs](../) to know more technical details of rrweb.
+
+## Scenarios
+
+### Record And Replay
+
+Record and Replay is the most common use case, which is suitable for any scenario that needs to collect user behaviors and replay them.
+
+[link](./record-and-replay.md)
+
+### Dive Into Events
+
+The events recorded by rrweb are a set of strictly-typed JSON data. You may discover some flexible ways to use them when you are familiar with the details.
+
+[link](./dive-into-event.md)
+
+### Load Events Asynchronous
+
+When the size of the recorded events increased, load them in one request is not performant. You can paginate the events and load them as you need.
+
+[link](./pagination.md)
+
+### Real-time Replay (Live Mode）
+
+If you want to replay the events in a real-time way, you can use the live mode API. This API is also useful for some real-time collaboration usage.
+
+[link](./live-mode.md)
+
+### Custom Event
+
+You may need to record some custom events along with the rrweb events, and let them be played as other events. The custom event API was designed for this.
+
+[link](./custom-event.md)
+
+### Interact With UI During Replay
+
+By default, the UI could not interact during replay. But you can use API to enable/disable this programmatically.
+
+[link](./interaction.md)
+
+### Customize The Replayer
+
+When rrweb's Replayer and the rrweb-player UI do not fit your need, you can customize your own replayer UI.
+
+[link](./customize-replayer.md)
+
+### Convert To Video
+
+The event data recorded by rrweb is a performant, easy to compress, text-based format. And the replay is also pixel perfect.
+
+But if you really need to convert it into a video format, there are some tools that can do this work.
+
+[link](./export-to-video.md)
+
+### Optimize The Storage Size
+
+In some Apps, rrweb may record an unexpected amount of data. This part will help to find a suitable way to optimize the storage.
+
+[link](./optimize-storage.md)
+
+### Canvas
+
+Canvas is a special HTML element, which will not be recorded by rrweb by default. There are some options for recording and replaying Canvas.
+
+[link](./canvas.md)

docs/recipes/interaction.md

@@ -0,0 +1,19 @@
+# Interact With UI During Replay
+
+By default, the UI could not interact during replay. But you can use API to enable/disable this programmatically.
+
+```js
+const replayer = new rrweb.Replayer(events);
+
+// enable user interact with the UI
+replayer.enableInteract();
+
+// disable user interact with the UI
+replayer.disableInteract();
+```
+
+rrweb uses the `pointer-events: none` CSS property to disable interaction.
+
+This will let the replay more stable and avoid some problems like navigate by clicking an external link.
+
+If you want to enable user interaction, like input, then you can use the `enableInteract` API. But be sure you have handled the problems that may cause unstable replay.

docs/recipes/live-mode.md

@@ -0,0 +1,27 @@
+# Real-time Replay (Live Mode）
+
+If you want to replay the events in a real-time way, you can use the live mode API. This API is also useful for some real-time collaboration usage.
+
+When you are using rrweb's Replayer to do a real-time replay, you need to configure `liveMode: true` and call the `startLive` API to enable the live mode.
+
+```js
+const replayer = new rrweb.Replayer([], {
+  liveMode: true,
+});
+
+replayer.startLive(FIRST_EVENT.timestamp - BUFFER);
+```
+
+When calling the `startLive` API, there is an optional parameter to set the baseline time. This is quite useful when you live scenario needs a buffer time.
+
+For example, you have an event recorded at timestamp 1500. Calling `startLive(1500)` will set the baseline time to 1500 and all the timing calculation will be based on this.
+
+But this may cause your replay to look laggy. Because data transportation needs time(such as the delay of the network). And some events have been throttled(such as mouse movements) which has a delay by default.
+
+So we can configure a smaller baseline time to the `startLive` API, like `startLive(500)`. This will let the replay always delay 1 second than the source. If the time of data transportation is not longer than 1 second, the user will not feel laggy.
+
+When live mode is on, we can call `addEvent` API to add the latest events into the replayer:
+
+```js
+replayer.addEvent(NEW_EVENT);
+```

docs/recipes/optimize-storage.md

@@ -0,0 +1,104 @@
+# Optimize The Storage Size
+
+In some Apps, rrweb may record an unexpected amount of data. This part will help to find a suitable way to optimize the storage.
+
+Currently, we have the following optimize strategies:
+
+- block some DOM element to reduce the recording area
+- use sampling config to reduce the events
+- use deduplication and compression to reduce storage size
+
+## Block DOM element
+
+Some DOM elements may emit lots of events, and some of them may not be the thing user cares about. So you can use the block class to ignore these kinds of elements.
+
+Some common patterns may emit lots of events are:
+
+- long list
+- complex SVG
+- element with JS controlled animation
+
+## Sampling
+
+Use the sampling config in the recording can reduce the storage size by dropping some events:
+
+**Scenario 1**
+
+```js
+rrweb.record({
+  emit(event) {},
+  sampling: {
+    // do not record mouse movement
+    mousemove: false
+    // do not record mouse interaction
+    mouseInteraction: false,
+    // set the interval of scrolling event
+    scroll: 150 // do not emit twice in 150ms
+    // set the timing of record input
+    input: 'last' // When input mulitple characters, only record the final input
+  }
+})
+```
+
+**Scenario 2**
+
+```js
+rrweb.record({
+  emit(event) {},
+  sampling: {
+    // Configure which kins of mouse interaction should be recorded
+    mouseInteraction: {
+      MouseUp: false,
+      MouseDown: false,
+      Click: false,
+      ContextMenu: false,
+      DblClick: false,
+      Focus: false,
+      Blur: false,
+      TouchStart: false,
+      TouchEnd: false,
+    },
+  },
+});
+```
+
+## Compression
+
+### Use packFn to compress every event
+
+rrweb provides a pako-based simple compress function rrweb.pack.
+
+You can use it by passing it as the `packFn` in the recording.
+
+```js
+rrweb.record({
+  emit(event) {},
+  packFn: rrweb.pack,
+});
+```
+
+And you need to pass rrweb.unpack as the `unpackFn` in replaying.
+
+```js
+const replayer = new rrweb.Replayer(events, {
+  unpackFn: rrweb.unpack,
+});
+```
+
+### Compress the whole session
+
+Use packFn to compress every event may not get the best result.
+
+It's recommended to compress the whole session in the backend, which will have a more efficient compression ratio for some algorithms like deflate.
+
+## Deduplication
+
+Another optimizing strategy is deduplication.
+
+Since we need to simulate hover in the replay, rrweb will try its best to inline CSS styles in the events.
+
+So if we are applying rrweb to github.com, we may record many duplicate CSS styles across sessions.
+
+We can iterate the events and extract CSS. Then we can only store one copy of the styles.
+
+This strategy is also possible for the full snapshot across sessions.

docs/recipes/pagination.md

@@ -0,0 +1,23 @@
+# Load Events Asynchronous
+
+When the size of the recorded events increased, load them in one request is not performant. You can paginate the events and load them as you need.
+
+rrweb's API for loading async events is quite simple:
+
+```js
+const replayer = new rrweb.Replayer(events);
+
+replayer.addEvent(NEW_EVENT);
+```
+
+When calling the `addEvent` API to add a new event, rrweb will resolve its timestamp and replay it as need.
+
+If you need to load several events, you can do a lool like this:
+
+```js
+const replayer = new rrweb.Replayer(events);
+
+for (const event of NEW_EVENTS) {
+  replayer.addEvent(event);
+}
+```

docs/recipes/record-and-replay.md

@@ -0,0 +1,31 @@
+# Record And Replay
+
+Record and Replay is the most common use case, which is suitable for any scenario that needs to collect user behaviors and replay them.
+
+You only need a simple API call to record the website:
+
+```js
+const stopFn = rrweb.record({
+  emit(event) {
+    // save the event
+  },
+});
+```
+
+You can use any approach to store the recorded events, like sending the events to your backend and save them into the database.
+
+But you should guarantee:
+
+- a set of events are sorted by its timestamp
+- save every event
+
+You can use the `stopFn` to stop the recording.
+
+The replay is also as simple as putting events into rrweb's Replayer.
+
+```js
+const events = GET_YOUR_EVENTS;
+
+const replayer = new rrweb.Replayer(events);
+replayer.play();
+```