# @amplitude/plugin-session-replay-browser 中文文档

规范地址：https://npmcn.com/package/%40amplitude/plugin-session-replay-browser/

版本：1\.36\.7
npm 元数据更新时间：2026-11-06T19:45:58.891Z
中文译文更新时间：2026-11-06T19:46:50.084Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40amplitude/plugin-session-replay-browser
原文对照：https://npmcn.com/package/%40amplitude/plugin-session-replay-browser/?lang=original
项目主页：https://github.com/amplitude/Amplitude-TypeScript
源码仓库：https://github.com/amplitude/Amplitude-TypeScript

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：5.5 MB，75 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2023-06-28T15:11:59.482Z
- 最新版本发布：2026-11-06T19:45:58.521Z
- 近 30 天下载量：4509132（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：329（近 12 个月 138 个）

## 中文简介

暂无中文简介

## 安装

```sh
npm install @amplitude/plugin-session-replay-browser
```

也可以使用：`pnpm add @amplitude/plugin-session-replay-browser`、`yarn add @amplitude/plugin-session-replay-browser`、`bun add @amplitude/plugin-session-replay-browser`

## README

[![](https://static.amplitude.com/brand/amplitude-logo-with-text.svg)](https://amplitude.com/)  

# @ amplitude/plugin-session- replay-浏览器

用于会话重放的官方浏览器 SDK 插件

## 安装

该软件包发布在国家预防机制登记册上,可用npm和纱线安装.

```sh
# npm
npm install @amplitude/plugin-session-replay-browser

# yarn
yarn add @amplitude/plugin-session-replay-browser
```

## 使用量

这个插件在Amplitude浏览器SDK上方工作,并在内置特性中添加会话回放功能. 要使用此插件, 您需要安装 `@amplitude/analytics-browser` 版本 `v1.9.1` 或后会.

此插件要求启用会话的默认跟踪 。 如果配置中未启用对会话的默认跟踪,插件会自动启用.

### 1\. 进口宽度包

-   `@amplitude/analytics-browser`
-   `@amplitude/plugin-session-replay-browser`

```typescript
import * as amplitude from '@amplitude/analytics-browser';
import { sessionReplayPlugin } from '@amplitude/plugin-session-replay-browser';
```

### 2\. 辅助会话重放插件

插件必须通过下列代码在振幅实例中注册 。 插件接受一个可选参数,即 `Object` 根据您的使用大小写配置插件.

```typescript
amplitude.init(API_KEY);
const sessionReplayTracking = sessionReplayPlugin({
  sampleRate: undefined
});
```

#### 选项

| 名称 | 类型 | 默认 | 需求 | 说明 |
| --- | --- | --- | --- | --- |
| `sampleRate` | `number` | `undefined` | 对 | 使用此选项来控制将选择多少会话进行回放收藏 。 将收集一个选定的会话进行回放,而未选择的会话将不进行回放.  
  
数字应该是0到1之间的小数 `0.01`,代表您希望随机选择重放收藏的会话的分数。 在大量会议上, `0.01` 将选择 `1%` 这些届会. |
| `privacyConfig` | `object` | `undefined` | 没有 | 支持高级口罩配置与 CSS 选择器. |
| `forceSessionTracking` | `boolean` | `false` | 没有 | 如果启用此功能, 我们将迫使浏览器 SDK 也发送开始和结束会话事件 . |
| `debugMode` | `boolean` | `false` | 没有 | 添加额外的调试事件属性来帮助调试仪器问题(如不匹配的app). 只推荐调试初始设置,不推荐生产. |
| `configServerUrl` | `string` | 没有 | `undefined` | 指定获取远程配置的端点 URL。 如果提供,它会覆盖默认服务器区配置. |
| `trackServerUrl` | `string` | 没有 | `undefined` | 指定发送会话重放数据的端点 URL。 如果提供,它会覆盖默认服务器区配置. |
| `shouldInlineStylesheet` | `boolean` | 没有 | `true` | 如果样式表被内化,样式表的内容将被存储. 在回放时,将使用所存储的样式表,而不是试图远程取取. 这可以防止由于缺少样式表而出现被损坏的回放. 注:内置样式表可能不会在所有情况下都有效。 如果这是 `undefined` 样式表将被内置. |
| `inlineImages` | `boolean` | 没有 | `false` | 当真实时, 图像源被内入为 rrweb 快照中的数据 URL, 因此重放不依赖于在播放时获取远程图像资产 。 增加快照有效载荷大小。 传到rrweb's `inlineImages` 记录选项. |
| `storeType` | `string` | 没有 | `idb` | 指定如何存储重放事件. `idb` 当所有事件在抓取时无法发送时,使用 IndexedDB 来持续重放事件. `memory` 存储重放事件只存在于内存中,指在页面关闭时事件会丢失. 如果索引DB不可用,系统会回到 `memory`。 。 。 . |
| `performanceConfig.enabled` | `boolean` | 没有 | `true` | 如果启用, 事件压缩将会被推迟到浏览器闲置期间进行. |
| `performanceConfig.timeout` | `number` | 没有 | `undefined` | 可选超时( 毫秒) `requestIdleCallback` API (英语). 如果指定,这个值将用来设定浏览器在执行被推迟的压缩任务之前等待的最大时间,即使浏览器没有闲置. |
| `performanceConfig.mergeMutations` | `boolean` | 没有 | `false` | 如果启用,连续突变事件在压缩前被合并为单个事件. 这样可以减少存储的事件数和内线的串联 `style` 在同一节点上突变(上行-write-wins),不改变重放语义. |
| `experimental.useWebWorker` | `boolean` | 没有 | `false` | 如果SDK应该使用网络工人来压缩回放事件. |

### 3\. 安装插件到振幅 SDK

```typescript
amplitude.add(sessionReplayTracking);
```

### 4\. 开始和停止录音(可选)

插件实例曝光 `start()` 财务报告和审定财务报表 `stop()` 这样您就可以暂停并恢复抓取而不移除插件 。 取样、确定目标和选择退出仍然适用.

```typescript
const sessionReplayTracking = sessionReplayPlugin({
  sampleRate: 1,
});
amplitude.add(sessionReplayTracking);

// Pause capture, for example on a sensitive screen
sessionReplayTracking.stop();

// Resume capture
await sessionReplayTracking.start();
```

## 隐私

默认情况下,会话重放会掩盖所有输入,这意味着输入中的文本会以星号重放的形式出现: `***`。您可能根据您的使用情况需要更具体的遮盖控制,所以我们提供以下控制:

#### 1\. 解密投入

在您的应用程序代码中, 添加类 `.amp-unmask` 对任意 **投入** 你想在重播中解开他的短信 在会话回放中,可以读取输入此类输入的准确文本,文本不会被转换为星号.

#### 2\. 面具非输入要素

在您的应用程序代码中, 添加类 `.amp-mask` 对任意 **非输入元素** 你希望从重播中掩盖出他的短信 元素中的文本,以及它的孩子,都会被转换为星号.

#### 3\. 块式非文本元素

在您的应用程序代码中, 添加类 `.amp-block` 到任何您想要从重播集中屏蔽的元素。 该元素会作为具有相同维度的占位符出现在回放中.

#### 4\. CSS选取器的块状元素.

在SDK初始化代码中,可以配置SDK来以基于CSS选择器来阻断元素.

```typescript
const sessionReplayTracking = sessionReplayPlugin({
  sampleRate: 0.01,
  privacyConfig: {
      blockSelector: ['.ignoreClass', '#ignoreId']
  }
});
```

## 调试

### 本地开发时使用调试模式

由于会话重放插件只在页面焦点时记录并标记事件,这在本地开发浏览器控制台打开时有时可能会出问题. 如果你对重播有意见, 尝试转动设置 `debugMode:true` 看看这是否有助于解决问题.

## 常见问题

### 如何安装 @amplitude/plugin-session-replay-browser？

在项目目录运行 npm install @amplitude/plugin-session-replay-browser，或使用 pnpm add / yarn add / bun add。

### @amplitude/plugin-session-replay-browser 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @amplitude/plugin-session-replay-browser 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @amplitude/plugin-session-replay-browser 可以商用吗？

@amplitude/plugin-session-replay-browser 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @amplitude/plugin-session-replay-browser 的下载量有多少？

根据 npm 官方下载统计，@amplitude/plugin-session-replay-browser 在 2026/10/06 – 2026/11/04 这 30 天内被下载 4,509,132 次，日均约 150,304 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @amplitude/plugin-session-replay-browser 还在维护吗？

最新版本 1\.36\.7 发布于 2026/11/07（1 天前）；至今共发布 329 个版本，其中过去 12 个月发布了 138 个；首次发布于 2023/06/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。