# @amplitude/plugin-autocapture-browser 中文文档

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

版本：1\.31\.3
npm 元数据更新时间：2026-11-16T21:58:52.686Z
中文译文更新时间：2026-11-16T21:59:45.393Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.9 MB，308 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2024-04-23T17:51:55.378Z
- 最新版本发布：2026-11-16T21:58:52.297Z
- 近 30 天下载量：9818052（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：184（近 12 个月 100 个）

## 中文简介

暂无中文简介

## 安装

```sh
npm install @amplitude/plugin-autocapture-browser
```

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

## README

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

# @amplitude/plugin-autocapture-browser (β) (中文(简体) )

**这个插件目前位于β中,命名和界面可能会在未来发生变化.**

自动抓取的浏览器 SDK 插件 .

## 安装

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

```sh
# npm
npm install @amplitude/plugin-autocapture-browser@beta

# yarn
yarn add @amplitude/plugin-autocapture-browser@beta
```

## 使用量

这个插件在Amplitude浏览器SDK上方工作,生成自动跟踪的事件并发送到Amplitude.

**阴影DOM:** 通过 `shadowDomEnabled` 选项(本地打开) `elementInteractions`,或者通过远程配置). 见 [SHADOW-DOM.MD (英语)](https://npmcn.com/package/%40amplitude/plugin-autocapture-browser/SHADOW-DOM.md)。 。 。 .

要使用此插件, 您需要安装 `@amplitude/analytics-browser` 版本 `v1.9.1` 或后会.

### 1\. 进口宽度包

-   `@amplitude/analytics-browser`
-   `@amplitude/plugin-autocapture-browser`

```typescript
import * as amplitude from '@amplitude/analytics-browser';
import { autocapturePlugin } from '@amplitude/plugin-autocapture-browser';
```

### 2\. 说明插件

插件接受一个可选参数,即 `Object` 来配置允许的跟踪选项.

```typescript
const plugin = autocapturePlugin({
  cssSelectorAllowlist: [
    '.amp-tracking',
    '[amp-tracking]'
  ],
  pageUrlAllowlist: [
    'https://amplitude.com',
    new RegExp('https://amplitude.com/blog/*')
  ],
  pageUrlExcludelist: [
    'https://amplitude.com/admin',
    new RegExp('^https:\\/\\/amplitude\\.com\\/private\\/.*$')
  ],
});
```

实例:

-   以上情况 `cssSelectorAllowlist` 只允许跟踪元素, 如:
    -   `<button amp-tracking>Click</button>`
    -   `<a class="amp-tracking">Link</a>`
-   以上情况 `pageUrlAllowlist` 只允许跟踪“https://amplitude.com”或任何匹配“https://amplitude.com/blog/\*”的URL上的元素
-   以上情况 `pageUrlExcludelist` 将屏蔽 URL "https://amplitude.com/admin" 或任何匹配"^https:\\/\\/amplitude\\.com\\/private\\/.\*$"模式的URL跟踪,即使它们符合许可列表

#### 选项

| 名称 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `cssSelectorAllowlist` | `string[]` | `['a', 'button', 'input', 'select', 'textarea', 'label', '[data-amp-default-track]', '.amp-default-track']` | 提供时只允许跟踪匹配任何选择器的元素. |
| `pageUrlAllowlist` | `(string|RegExp)[]` | `undefined` | 提供时,只允许跟踪匹配URL的元素. |
| `pageUrlExcludelist` | `(string|RegExp)[]` | `undefined` | 在提供时, 块跟踪匹配 URL 的元素 。 优于许可名单. |
| `shouldTrackEventResolver` | `(actionType: ActionType, element: Element) => boolean` | `undefined` | 提供时, 覆盖所有其他允许列表和配置 . |
| `dataAttributePrefix` | `string` | `'data-amp-track-'` | 允许在事件属性中收集数据属性 . |

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

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

### 4\. 振幅SDK初始化

```typescript
amplitude.init('API_KEY');
```

## 常见问题

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

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

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

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

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

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

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

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

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

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

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

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

