update docs

SaolaAI · Nov 19, 2020 · 6c4f10e · 6c4f10e
1 parent a2cd3e2
commit 6c4f10e
Show file tree

Hide file tree

Showing 16 changed files with 649 additions and 72 deletions.
diff --git a/README.md b/README.md
@@ -7,6 +7,13 @@
 
 # rrweb
 
+<div style="padding: 0.5rem 0.75rem;text-align: center;background-color: black;font-weight: 700;">
+  <span style="background: #4950f6;color: white;padding: 6px 8px;border-radius: 3px;margin-right: 4px;font-weight: 12px;">New</span>
+  <a href="http://www.myriptide.com/rrweb-community/" target="_blank" style="color: white !important;border-bottom: 2px solid rgba(255, 255, 255, 0.6);text-decoration: none;">
+    The new adventure of the rrweb community</a
+  >
+</div>
+
 [![Build Status](https://travis-ci.org/rrweb-io/rrweb.svg?branch=master)](https://travis-ci.org/rrweb-io/rrweb)
 [![Join the chat at https://gitter.im/rrweb-io/rrweb](https://badges.gitter.im/rrweb-io/rrweb.svg)](https://gitter.im/rrweb-io/rrweb?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 ![total gzip size](https://img.badgesize.io/https://cdn.jsdelivr.net/npm/rrweb@latest/dist/rrweb.min.js?compression=gzip&label=total%20gzip%20size)
@@ -24,6 +31,8 @@ rrweb refers to 'record and replay the web', which is a tool for recording and r
 
 [**📚 Read the rrweb guide here. 📚**](./guide.md)
 
+[**Recipes**](./docs/recipes/index.md)
+
 ## Project Structure
 
 rrweb is mainly composed of 3 parts:

diff --git a/README.zh_CN.md b/README.zh_CN.md
@@ -7,6 +7,13 @@
 
 # rrweb
 
+<div style="padding: 0.5rem 0.75rem;text-align: center;background-color: black;font-weight: 700;">
+  <span style="background: #4950f6;color: white;padding: 6px 8px;border-radius: 3px;margin-right: 4px;font-weight: 12px;">New</span>
+  <a href="http://www.myriptide.com/rrweb-community-cn/" target="_blank" style="color: white !important;border-bottom: 2px solid rgba(255, 255, 255, 0.6);text-decoration: none;">
+    rrweb 社区新的征程</a
+  >
+</div>
+
 [![Build Status](https://travis-ci.org/rrweb-io/rrweb.svg?branch=master)](https://travis-ci.org/rrweb-io/rrweb)
 [![Join the chat at https://gitter.im/rrweb-io/rrweb](https://badges.gitter.im/rrweb-io/rrweb.svg)](https://gitter.im/rrweb-io/rrweb?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 ![total gzip size](https://img.badgesize.io/https://cdn.jsdelivr.net/npm/rrweb@latest/dist/rrweb.min.js?compression=gzip&label=total%20gzip%20size)

diff --git a/docs/recipes/canvas.md b/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.**
diff --git a/docs/recipes/custom-event.md b/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',
+    },
+  },
+});
+```
diff --git a/docs/recipes/customize-replayer.md b/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).
diff --git a/docs/recipes/dive-into-event.md b/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).
diff --git a/docs/recipes/export-to-video.md b/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).
diff --git a/docs/recipes/index.md b/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)
diff --git a/docs/recipes/interaction.md b/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.
diff --git a/docs/recipes/live-mode.md b/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);
+```