• 目前 DataFinder 会话回放功能仅支持在 Web（包括 H5） 环境中使用；

• 使用 DataFinder 会话回放功能需要同时安装 DataFinder Web SDK 与本文介绍的 Session Replay **** SDK。

  名词	解释
  DataFinder Web SDK	DataFinder Web SDK 是 DataFinder 埋点上报客户端 SDK web/js 版本，详细介绍与使用参考Web/JS SDK 帮助文档。
  Session Replay SDK	DataFinder 会话回放功能需要同时安装 DataFinder Web SDK 和 Session Replay SDK 才能使用。Session Replay SDK 负责记录页面上发生的各种信息，以便后续回放。

使用前请先接入 DataFinder Web SDK，并在该 SDK 初始化之后添加Session Replay SDK 集成代码。以下为Session Replay SDK 集成的通用结构，您可结合下文的使用说明章节，基于实际业务需要，修改并集成Session Replay SDK代码。

<script>
(function (n, t) {
  if (!(!t || !n)) { //加载 SDK 资源
    var e = document.createElement('script');
    (e.src = n),
      (e.async = !0),
      (e.crossOrigin = 'anonymous'),
      (e.onload = () => {
        var o = window[window.LogAnalyticsObject];
        o && (o('getConfig') ? t() : o('on', 'ready', t));
      }),
      document.head.appendChild(e);
  }
})('https://lf-dp.bytetos.com/obj/dp-open-internet-cn/replay/0.2/recorder/index.global.js', () => {
  var recorder = new window.ReplaySDK.MultithreadedRecorder({ //初始化 Session Replay SDK
    environment: { baseURL: 'https://gator.volces.com' },
    //baseURL为数据上报服务地址，SaaS云原生环境为：https://gator.volces.com；SaaS非云原生环境为：http://analytics.volcengineapi.com
  });
  recorder.startRecording({
    token: '<APP Key>',
    tags: ['自定义标签']
  });
});
</script>

初始化录制器

window.ReplaySDK.MultithreadedRecorder 是Session Replay SDK 的核心组件，用来初始化录制器对象。

var recorder = new window.ReplaySDK.MultithreadedRecorder({
  environment: { baseURL: "https://gator.volces.com" },
});

• 上述代码中的baseURL为数据上报服务地址。
  • SaaS云原生环境配置为：https://gator.volces.com；
  • SaaS非云原生环境配置为：http://analytics.volcengineapi.com
• 该地址等同 DataFinder Web SDK 初始化时的 channel_domain 地址，可在 数据集成-数据接入-Web JS 中找到具体配置（参考下图）：
• 上述代码中的 new window.ReplaySDK.MultithreadedRecorder()会返回recorder录制器对象，建议保证该对象全局唯一，方便管理录制行为。

启动录制

可以通过上文 recorder 对象的 startRecording 方法启动录制。同一个recorder支持同时启动多个录制，每次调用 startRecording 会返回对应本次录制的 recordingContext，可用来停止录制。

var recordingContext = await recorder.startRecording({
  token: "<APP Key>",
});

startRecording 必须传入一个 token，该字段的来自项目详情-应用列表-应用信息-APP Key，值等同 APP Key：

录制过程支持自定义标签，方便后续检索分析，可以参照下面代码在开始录制的时候传入 tags 参数：

var recordingContext = await recorder.startRecording({
  token: "<APP Key>",
  tags: ['测试标签 1', '测试标签 2']
});

停止录制

使用 recorder.startRecording 返回的 recordingContext 对象支持停止录制。

await recordingContext.stopRecording();

数据安全和脱敏

默认安全行为

Session Replay SDK 在任何情况下都不会记录 <input type="password"> 中的内容（密码）。

内置数据脱敏能力

Session Replay SDK 内置了对身份证、手机号、邮箱、银行卡、IP/MAC 地址、车牌号、车架号、姓名的脱敏规则。
但由于姓名通常没有明显特征，Session Replay SDK 无法自动脱敏，需要您在 HTML 元素上添加 data-finder-replay-mask="name" 属性来启用姓名脱敏，例如：

<div data-finder-replay-mask="name">张三</div>

忽略指定的元素

通过为 HTML 元素添加 data-finder-replay-mask="ignore" 属性即可忽略该元素，例如：

<div data-finder-replay-mask="ignore">L4</div>

自定义打码

通过为 HTML 元素添加 data-finder-replay-mask 或 data-finder-replay-mask="true" 属性即可将其文本内容替换为 *（星号），例如：

<div data-finder-replay-mask>Masked</div>

<!-- 或者 -->
<div data-finder-replay-mask="true">Masked</div>

脱敏效果示例

通常完成SDK接入后，大约几分钟后即可在DataFinder页面中查看上报的会话回放视频数据。
您可以在接入完成后，手动打开页面并对页面进行刷新操作，来触发会话回放数据上报，然后登录DataFinder控制台，在分析功能>高级分析>会话回放页面查看上报的数据，以进行数据接入验证。

示例1：完成集成demo

<script>
  (function (win, export_obj) {
    win["TeaAnalyticsObject"] = export_obj;
    if (!win[export_obj]) {
      function _collect() {
        _collect.q.push(arguments);
      }
      _collect.q = _collect.q || [];
      win[export_obj] = _collect;
    }
    win[export_obj].l = +new Date();
  })(window, "collectEvent");
</script>
<script
  async
  src="https://lf3-data.volccdn.com/obj/data-static/log-sdk/collect/collect-autotrack-rangers.js"
></script>
<script>
  window.collectEvent("init", {
    app_id: Number('<APP ID>'),
    channel_domain: "https://gator.volces.com",
    disable_sdk_monitor: true, //用于禁止SDK启动后自身监控事件 onload 的上报
  });
  window.collectEvent("start");
</script>
<script>
(function (n, t) {
  if (!(!t || !n)) {
    var e = document.createElement('script');
    (e.src = n),
      (e.async = !0),
      (e.crossOrigin = 'anonymous'),
      (e.onload = () => {
        var o = window[window.LogAnalyticsObject];
        o && (o('getConfig') ? t() : o('on', 'ready', t));
      }),
      document.head.appendChild(e);
  }
})('https://lf-dp.bytetos.com/obj/dp-open-internet-cn/replay/0.2/recorder/index.global.js', () => {
  var recorder = new window.ReplaySDK.MultithreadedRecorder({
    environment: { baseURL: 'https://gator.volces.com' },
  });
  recorder.startRecording({
    token: '<APP Key>',
  });
});
</script>

示例2：多实例场景

假设您通过以下方式启用了 DataFinder Web SDK 的多实例功能：

// 实例1，上报到 appid={{APPID_1}}
window.collectEvent('init', {
    app_id: {{APPID_1}},
    // .....其他初始化配置
});
window.collectEvent('start');

// 实例2，上报到 appid={{APPID_2}}
// 此处"finder"可用任意的名称，只需与下文 start 处保持一致
window.collectEvent('finder.init', {  
    app_id: {{APPID_2}},
    // .....其他初始化配置
});
// 此处"finder"可用任意的名称，只需与上文 init 处保持一致
window.collectEvent('finder.start');

上面的代码中，window.collectEvent('finder.init', {app_id: {{APPID_2}}...), 表示初始了一个 appId 为 {{APPID_2}}，命名为 finder 的 Finder Web SDK 实例，如果您希望将回放通过 finder 实例上传到 appId 为 {{APPID_2}} 的项目中，可以参考下面代码在 MultithreadedRecorder 的构造函数中传入sdk 配置：

new window.ReplaySDK.MultithreadedRecorder({sdk: (k, ...params) => window.collectEvent(`finder.${k}`, ...params)})

示例3：录制 Canvas

Session Replay SDK 支持录制 Canvas 2d，目前还处于实验阶段，如果录制时遇到任何问题，可联系火山引擎技术支持人员协助排查处理。

注意事项

可能需要在引入图表库之前引入 Session Replay SDK 的脚本，从而让Session Replay SDK 能够提前处理 Path2D 等全局对象。

const recorder = new window.ReplaySDK.MultithreadedRecorder(({ html: {canvas: true} });

// 开启录屏
recorder.startRecording(...)

报错处理

• **浏览器报错：**Tainted canvases may not be exported.
• **原因：**通过 Image 的 src 加载多个不同源图片时，会触发该浏览器安全限制，禁止通过 Canvas.toDataURL 导出数据。
• **解决方案：**使用 fetch 将图片加载到内存中的 Blob，再使用 Image 加载该 Blob 即可。

  interface ObserveOptions {
      snapshot: boolean;
      /**
       * 抽样录制，开启这个参数会使用截图的方式录制canvas，改进稳定性，但会增加录制的存储成本。
       * 数字等同于录制的帧率，最大值15帧
       */
      sampling?: boolean | SamplingOptions;
  }
  
  interface SamplingOptions {
      /**
       * 帧率，最大值 15
       *
       * @default 3
       */
      fps: number;
      /**
       * @default
       * {
       *   type: "image/webp",
       *   quality: 0.6
       * }
       */
      dataURLOptions?: {
          type?: string;
          quality?: number;
      };
  }
  
  const recorder = new window.ReplaySDK.MultithreadedRecorder(({ html: {canvas: {
      snapshot: true,
      sampling: true
  } });
  
  // 开启录屏
  recorder.startRecording(...)
  

示例4：录制iFrame

同域

被录制的 iFrame 同域的情况下，Session Replay SDK 会自动注入脚本，仅需如下配置即可：

const recorder = new window.ReplaySDK.MultithreadedRecorder({
  // 配置自动注入参数
  html: {
    iframe: {
      autoInject: true,
      injectScript: 'https://lf-dp.bytetos.com/obj/dp-open-internet-cn/replay/0.2/recorder/index.global.js'
    }
  }
});

// 开启录屏
recorder.startRecording({...});

跨域

被录制的 iFrame 跨域的情况下，需要手动在该 iFrame 中集成Session Replay SDK 脚本。

• 在父级页面创建 Recorder 时开启 iFrame 配置：

const recorder = new window.ReplaySDK.MultithreadedRecorder({ html: {iframe: true} });

// 开启录屏
recorder.startRecording(...)

• 子 iFrame 页面中引入Session Replay SDK：

<script src="https://lf-dp.bytetos.com/obj/dp-open-internet-cn/replay/0.2/recorder/index.global.js" async crossOrigin="anonymous"/>

为什么查看 DataFinder 会话回放网络请求的时候看不到返回值？

默认情况下 Session Replay SDK 不录制网络请求的返回值，如果希望录制返回值，需要通过下面的方式开启：

new window.ReplaySDK.MultithreadedRecorder({network: { captureResponseBody: true }})

为什么录制后在 DataFinder 会话回放页面中查不到回放？

埋点落库有时间差，如果长时间查不到，说明开始录制的埋点没有正确上报。
在 DataFinder 会话回放开始录制时，会自动上报一个埋点 sr_start_recording ，该埋点会记录回放 ID 等元数据，是决定列表中能否查到回放的**唯一因素**。
首先通过数据验证功能，查看 sr_start_recording 埋点是否正确上报，有以下几种可能埋点没有正确上报

1. 上报到了错误的项目下，需要检查埋点上报的 appId是否与您所在项目的 appId 一致，在 DataFinder 的 项目中心-项目详情查看正确的 appId；
2. 控制台报错，提示找不到 appId，说明传入的实例错误。请确保 Session Replay SDK 的初始化脚本在 DataFinder Web SDK 之后加载，如果使用了多实例配置，请参考上文正确配置 Session Replay SDK 初始化逻辑。

为什么上传状态是「尚未上传」？

有几种原因：

1. 录制未停止：如果未主动停止录制，Session Replay SDK 仅当用户刷新页面、关闭页面等情况下才自动停止并告知后端生成录屏记录，因此建议可能的情况下都手动停止录屏；
2. 上报失败：常见于用户快速关闭、刷新页面，录制过短数据无法上传。