JavaScript SDK ⁠-⁠ 初始化 SDK

安装

以下命令将安装跟踪器以及 SDK，方便您利用所有的跟踪器功能。

npm i @openreplay/tracker

初始化

在实例化 OpenReplay 的跟踪器时，您可以提供多个配置选项来自定义录制和录制体验的各个方面。

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

Single Page Applications (SPA)

如果您的网站是一个 Single Page Application (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)

Server-side Rendered (SSR)

否则，如果您的 Web 应用是 Server-Side-Rendered (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 强制 canvas 图像以像素密度 1 而非 devicePixelRatio 渲染。（降低图像的潜在质量，使最终结果更小）。默认值：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 如果用户的浏览器启用了“请勿跟踪”标志，则不要启动跟踪器。默认值：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 有关。它与必须设置为 true 的 captureIFrames 选项一起使用。

	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