JavaScript SDK ⁠-⁠ 初始化 SDK

安装

下面这行命令将安装跟踪器，并随之安装 SDK，让你能够使用跟踪器的所有功能。

npm i @openreplay/tracker

初始化

在实例化 OpenReplay 的跟踪器时，你可以提供若干配置选项，用于自定义录制及录制体验的诸多方面。

你必须在构造函数中设置 projectKey 选项。你可以在 OpenReplay 仪表板的 ‘Preferences > Projects’ 下获取该值。

单页应用（SPA）

如果你的网站是单页应用（SPA），你可以将跟踪器作为单例使用：

import { tracker } from '@openreplay/tracker'

tracker.configure({
	projectKey: PROJECT_KEY,
  ingestPoint: "https://openreplay.mydomain.com/ingest", // when dealing with the self-hosted version of OpenReplay
})

tracker.start() // returns a promise with session info (sessionID, sessionHash, userUUID)

或者，你也可以创建一个新的类实例：

import OpenReplay from '@openreplay/tracker';
//...
const tracker = new OpenReplay({
  projectKey: PROJECT_KEY
});
tracker.start(); // returns a promise with session info (sessionID, sessionHash, userUUID)

服务端渲染（SSR）

否则，如果你的 Web 应用采用服务端渲染（SSR）（即 NextJS、NuxtJS），请使用以下代码片段。确保在应用启动后再调用 tracker.start()（在 useEffect 或 componentDidMount 中）。

import OpenReplay from '@openreplay/tracker/cjs';
//...
const tracker = new OpenReplay({
      projectKey: PROJECT_KEY,
      ingestPoint: "https://openreplay.mydomain.com/ingest", // when dealing with the self-hosted version of OpenReplay
});
//...
function MyApp() {
  useEffect(() => { // use componentDidMount in case of React Class Component
    tracker.start(); // returns a promise with session info (sessionID, sessionHash, userUUID)
  }, [])
}

示例

import OpenReplay from '@openreplay/tracker/cjs';
//...
const tracker = new OpenReplay({
      projectKey: PROJECT_KEY,
      ingestPoint: "https://openreplay.mydomain.com/ingest", // when dealing with the self-hosted version of OpenReplay
      capturePerformance: true,
      __DISABLE_SECURE_MODE: true // for local testing
});

初始化选项

你可以向构造函数传递一组选项。只有 projectKey 是必需的。

通用

projectKey: string 你正在跟踪的项目的 ID。
sessionHash?: string 初始会话的哈希值。当会话在你的 Web 应用中跨越不同子域，而你又希望将它们拼接成一段录制时，这非常有用。如果无法继续该会话（不存在或已结束），跟踪器会自动开始一个新会话。它也会在 stop() 时返回。更多详情请参见此处。
ingestPoint?: string 你的 OpenReplay 域名（即 https://openreplay.mydomain.com/ingest），跟踪器会将事件发送到该域名。对于 OpenReplay Cloud 用户而言此项为可选。默认值：https://api.openreplay.com/ingest（指向 OpenReplay Cloud）。
revID?: string 你的 Web 应用的修订版本 ID。在查找发生在特定发布版本上的问题时很有用。
resourceBaseHref?: string 指 OpenReplay 可以获取资源（样式、字体和图标）的公开可访问域名。由于这些资源是正确进行会话回放所必需的，因此当你的站点（以及资源）托管在私有域名上时，此选项有助于绕过这一限制。示例：https://mypublicsite.com/assets/。
captureIFrames?: boolean 用于捕获 Web 应用中所有同域的 iFrame。如果你希望跟踪某个特定的 iFrame，只需为 <iframe> 标签添加 data-openreplay-capture HTML 属性即可。默认值：true。
disableClickmaps?: boolean 用于禁用 CSS 选择器计算（用于点击热图）。默认值：false。
__debug__: number 用于启用调试日志。默认值：0（禁用）。
- 2：错误。
- 3：错误和警告。
- 4：错误、警告和日志。
- 5：详细。
autoResetOnWindowOpen?: boolean 启用此选项可在从你的应用打开新标签页时重置 sessionID。这会重写 window.open 方法，以避免由于浏览器标签页之间共享会话存储而导致 sessionID 重复。默认值：false。
forceSingleTab: boolean 禁用多标签页录制功能，该功能会将用户在多个标签页中进行的会话拼接成单个回放。相反，启用此选项后，在不同浏览器标签页中捕获的会话将被记录为单独的录制。默认值：false。
disableStringDict: boolean 在录制中禁用字符串字典逻辑（用于优化存储）。默认值：false。
fixedCanvasScaling: boolean 强制以像素密度 1 而非 devicePixelRatio 渲染 canvas 图像。（降低图像的潜在质量，以使最终结果的体积更小）。默认值：false。
disableCanvas?: boolean 禁用 canvas 元素的录制。默认值：false。
assistSocketHost?: string 可用于为 assist 插件连接设置特定的主机。默认值为 ingestPoint 的值。
nodes?: { maintainer: MaintainerOptions } 新的 nodes.maintainer 选项有助于管理内存并清理不再使用的 DOM 节点。它具有以下参数：
- interval: number：每次清理运行之间的时间间隔（以毫秒为单位）。默认值：30 * 1000（30 秒）。
- batchSize: number：每次清理运行期间要检查的节点数量。默认值：2500。
- enabled: boolean：启用或禁用节点维护器。默认值：true。

样式表

inlineCss: number：强制跟踪器将远程样式表作为常规消息进行录制和发送，而不是在后端对其进行缓存。当 CSS 文件为私有文件、因而无法被 OpenReplay 后端缓存时，这非常有用。可选值为：
- 0：CSS 文件由后端缓存。默认行为。
- 1：将尝试把链接的 css 文件录制为 AdoptedStyleSheet 对象。
- 2：获取该文件，然后为回放模拟 AdoptedStyleSheets 行为。
- 3：获取该文件，然后将其作为纯 css 保存在 <style> 节点内 —— 如果你的 CSS 文件中有大量简写属性，请使用此选项（可解决 CSSOM 规范的一个 bug）。
css: CssRulesOptions：为使用 emotion-js 库构建的应用（即 MUI 组件）提供更好的支持。它带有以下参数：
- scanInMemoryCSS: boolean：如果你在使用由 emotionjs 创建的样式时遇到问题，请将其打开。默认值：false。
- checkCssInterval: number：扫描具有空规则的被跟踪样式表的频率。默认值：200（毫秒）。
- checkLimit: number：适用于变更数量有限和/或样式表在初次渲染后于客户端进行水合的情况。对每个样式表单独应用。该值应 = X/checkCssInterval，其中 X 为以毫秒为单位的观察时长。默认值：0（禁用）。

隐私

respectDoNotTrack?: boolean 如果用户浏览器中启用了 do-not-track 标志，则不启动跟踪器。默认值：false。
obscureTextEmails?: boolean 遮蔽文本元素中的电子邮件。电子邮件将被转换为一串随机的星号。默认值：true。
obscureTextNumbers?: boolean 遮蔽文本元素中的数字。数字将被转换为一串随机的星号。默认值：false。
obscureInputEmails?: boolean 遮蔽输入字段中的电子邮件。电子邮件值将被转换为一串随机的星号。默认值：true。
obscureInputNumbers?: boolean 遮蔽输入字段中的数字。数字值将被转换为一串随机的星号。如果禁用此项，请务必清理输入字段中可能包含的敏感数据，例如邮政编码或信用卡详情。默认值：true。
obscureInputDates?: boolean 遮蔽输入字段中的日期。日期值将被转换为一串随机的星号。默认值：false。
defaultInputMode?: 0 | 1 | 2 输入值的默认捕获模式。分别为：明文、遮蔽或忽略。默认值：2（忽略）。
urls：让你通过以下选项自定义页面位置事件的录制方式：
- urlSanitizer?: (url: string) => string 让你清理页面 url（例如用于移除使用令牌）。
- titleSanitizer?: (title: string) => string 让你清理页面标题。
resourceNameSanitizer?: (url: string) => string 让你清理已录制网络资源的 URL。

请注意，被排除的数据会在发送到 OpenReplay 服务器之前进行遮蔽或抑制。对上述选项所做的更改无法追溯生效，仅适用于新收集的数据。更多详情请参见 Sanitize Data。

控制台

consoleMethods?: Array<'log' | 'info' | 'warn' | 'error' 'debug' | 'assert'> | null 指定要捕获的控制台方法列表。默认值：['log', 'info', 'warn', 'error', 'debug', 'assert']
consoleThrottling?: number 每秒捕获的最大控制台条目数。默认值：30。

异常

captureExceptions?: boolean 捕获 JavaScript 异常和堆栈跟踪。默认值：true。

时序

captureResourceTimings?: boolean 记录资源时序。默认值：true。
capturePageLoadTimings?: boolean 记录页面加载时序。默认值：true。
capturePageRenderTimings?: boolean 计算页面渲染指标，例如 Speed Index、Visually Complete 或 Time To Interactive。需要 captureResourceTimings = true。默认值：true。

性能

capturePerformance?: boolean 用于捕获性能指标，例如帧率、CPU 和内存消耗。默认值：true。
longTasks?: boolean 用于捕获 long-animation-frame 事件。默认值：false。

网络

network 选项与捕获 fetch 和 XHR 的网络请求及负载相关。

network?: {
    failuresOnly: boolean;
    sessionTokenHeader: string;
    ignoreHeaders: Array<string> | boolean;
    capturePayload: boolean; // make sure you sanitize your data before enabling it
    sanitizer: (RequestResponseData) => RequestResponseData | null;
		captureInIframes: boolean;
  	axiosInstances: AxiosInstance[];
    useProxy?: boolean;
		tokenUrlMatcher?: (url: string) => boolean;
  }

有关示例以及如何脱敏敏感数据的更多详情，请参见 Network Options。

Canvas

canvas 选项与捕获 canvas/WebGL 元素相关：

canvas?: {
  disableCanvas?: boolean
  fixedCanvasScaling?: boolean
  useAnimationFrame?: boolean
  fileExt?: 'webp' | 'png' | 'jpeg' | 'avif'
}

有关如何启用此功能以及可用选项的更多详情，请参见 Canvas and WebGL。

跨域 iFrame

crossdomain 选项与捕获来自不同域的 iFrame 相关。它需与 captureIFrames 选项配合使用，而后者必须设置为 true。

	crossdomain?: {
		/**
		 * Enable cross-domain tracking
		 * @default false
		 * */
		enabled?: boolean
		/**
		 * Used to specify the parent domain, will be '*' by default
		 * (Check your CSP settings)
		 * @default '*'
		 * */
		parentDomain?: string
	}

自 Tracker 版本 14.0.10 起，在处理跨域 iFrame 时，HTML 元素上不再需要 data-domain 属性。

有关如何捕获来自不同域的 iFrame 的更多详情，请参见 Cross-domain iFrame Tracking。

鼠标指针

mouse 选项与捕获点击选择器以构建点击热图相关。

mouse?: 
  {
  disableClickmaps?: boolean
  minSelectorDepth?: number
  nthThreshold?: number
  maxOptimiseTries?: number
  }

disableClickmaps?: boolean 完全禁用选择器计算。默认值：false。
minSelectorDepth?: number 优化后选择器的最小长度（默认 2）。示例：body > div > div > p => body > p
nthThreshold?: number 在回退到 nth-child 选择器之前尝试选择器的次数。这是一项开销很大的操作，可能会带来显著的额外开销，请勿设置高于 2000。默认值：1000。
maxOptimiseTries?: number 优化并缩短选择器的尝试次数。默认值：10 000。

重新连接

connAttemptCount?: number 当跟踪器的 HTTP 请求无法到达后端时的最大重试次数。默认值：10。
connAttemptGap?: number 每次重试之间的时长（以毫秒表示）。默认值：8000。

安全

__DISABLE_SECURE_MODE?: boolean 用于在没有 SSL 的站点上允许跟踪器与后端之间的不安全连接。这应仅用于开发目的。默认值：false。

JavaScript SDK - 初始化 SDK