# @betterbugs/web-sdk 中文文档

规范地址：https://npmcn.com/package/%40betterbugs/web-sdk/

版本：0\.0\.47
npm 元数据更新时间：2026-09-21T12:36:07.482Z
中文译文更新时间：2026-11-08T00:14:56.250Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40betterbugs/web-sdk
原文对照：https://npmcn.com/package/%40betterbugs/web-sdk/?lang=original
项目主页：https://github.com/betterbugs/web-sdk#readme
源码仓库：https://github.com/betterbugs/web-sdk

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

- 包体积（解压后）：4.1 MB，26 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=16\.8\.0，react-dom \>=16\.8\.0
- 首次发布：2025-06-05T11:17:53.776Z
- 最新版本发布：2026-09-21T12:36:07.252Z
- 近 30 天下载量：6516（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：55（近 12 个月 13 个）

## 中文简介

Betterbugs 的网络 sdk 软件包

## 安装

```sh
npm install @betterbugs/web-sdk
```

也可以使用：`pnpm add @betterbugs/web-sdk`、`yarn add @betterbugs/web-sdk`、`bun add @betterbugs/web-sdk`

## README

# BetterBugs 网络 SDK 软件

使用 BetterBugs Web SDK 简化您网络应用中的bug 报告 .

BetterBugs Web SDK 允许您以最小的设置和努力将错误报告能力包含在您的应用程序中.

现在,你可以用方便用户和易于执行的发布问题报告能力来增强你的应用,比如媒体捕捉,日志跟踪,获得两分钟倒风会话视频,以及实时钩子来帮助你和你的团队报告,诊断,有效解决问题.

## 拆开它

使用"BetterBugs Web SDK",您可以使用错误报告功能来增强您的网络应用程序,从而可以捕捉有关这些问题的有用数据. 再来点.

## SDK的主要特征

-   **无缝一体化** ——快速安装并方便使用,有几行代码.
-   **可配置参数** —— 参数的tweak设置, 如 metaData, recordType, cause Annotation等, 还有许多其他.
-   **使用方法** ——以显示(),隐藏(),开始记录()等程序方法控制SDK,以及许多其他方法.
-   **事件钩** ——为了更深入的整合,请收听有钩子的特定生命周期事件,如抓取截图后(屏幕截图),提交bug(bugSubmit),或录制起(录制停止)等,以及许多其他.
-   **会话倒转( 即将到来)** – 自动记录会话的最后2分钟,以捕捉所有用户交互. 它完全适用于刚刚发生的自动捕捉问题,并有助于追踪导致虫子的动作.
-   **浮动部件自定义** - 控制部件的外观和位置.

## 快速安装

要安装SDK,请使用以下命令:

### 国家防范机制安装

```shell
npm install @betterbugs/web-sdk
```

### Yarn 安装

```shell
yarn add @betterbugs/web-sdk
```

## BetterBugs Web SDK 初始化:使用实例

安装后, 将您网络应用中 SDK 实例初始化 :

### 类型脚本

```typescript
import { Betterbugs } from '@betterbugs/web-sdk';

new Betterbugs({
  apiKey: process.env.TEST_API_KEY || '',
  mode: 'production',
});
```

## 实例代码概览

这就是它的作用:

**1 - 导入 Betterbugs SDK** – 从 @ betterbugs/web-sdk 包中拉入更好的bugs.

**2 - 创建新实例** ——配置对象设置以下选项:

-   **键**: 从环境变量(process.env.PROJECT API KEY)中获取值.
-   **模式**:在生产环境中运行以获取额外的调试特性.

## 配置选项: 自定义 SDK 行为

您可以用以下参数自定义 SDK 行为 :

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| 键 | 字符串 | 您的工作空间 API 密钥( 需要) |
| 项目编号 | 字符串 | 向错误报告的项目 。 需要使用工作空间 API 密钥; 如果您正在使用遗留的项目范围密钥, 请省略 . |
| 元数据 | 记录 < 字符串 QQ 数字, 字符串 QQ 数字 无效 > | 自定义附于报表的元数据( 例如 { userId: 123}) |
| 记录类型 | "录音录像""DOMRIORD" | "录音录像"(英語:record Video)类型(为SPA所推荐)是传统媒体录制视频和音频的方法. "DomRecord"类型(为多页Apps推荐)是DOM记录方法,可能不如"record Video"类型准确. **保留它, SDK 选择浏览器支持的最佳模式** 看到了吗 [记录模式](https://npmcn.com/package/%40betterbugs/web-sdk/#readme-recording-modes)。 。 。 . |
| 禁用剪贴板 | 布尔 | 禁用截图抓取 |
| 禁用记录 | 布尔 | 禁用屏幕记录 |
| 需要的媒体 | 布尔 | 在提交报告之前,需要截图或屏幕记录。 两者均忽略 `disableScreenshot` 财务报告和审定财务报表 `disableRecording` 已启用。 默认 : `false`。 。 。 . |
| 启用注释 | 布尔 | 为截图启用注释工具 . |
| 显示动作按钮 | 布尔 | 显示/隐藏浮动动作按钮 . |
| 职位 | {上? :字符串,左? :字符串,右? :字符串,下? : 字符串 : | 控制部件的屏幕位置 . |
| 模式 | "开发""生产" | 设定开发或生产模式(默认为"生产").  
  
“ 开发” 模式可以在应用程序开发时设置: 报表表将放弃电子邮件字段, 转而显示 **记者** (所需)和 **收件人** (可选)拾取者, 与你的工作空间的成员。 "出品"模式是针对终端用户的,指应用程序的客户可以通过Email域在直播环境中报告出一出错误. |
| 电子邮件 | 字符串 | 正在报告错误的用户的电子邮件地址 。 只在"生产"模式下工作. |
| 样式 | {主题 ? : “ 浅色 ”\\ “ 暗色 ” , 主颜色 ? : 字符串 , 主格式 ? : 字符串 , 次要格式 ? : 字符串 , 次要格式 ? : 字符串 , 文本格式 ? : 字符串 , 音译格式 ? : 字符串 , 输入格式 | 设置部件的样式 |
| 动作按钮组件 | 反应 反应节点 QQ 字符串 | 动作按钮的组件(接受反应组件或HTML字符串). |
| 成功信头图文集 | 字符串 | 成功信息主标题文本. |
| 主标题 | 字符串 | 部件的主要标题文本 |
| 成功Message Subheader 文本 | 字符串 | 成功消息的子标题文本 . |
| 最大记录 分钟 | 编号 | 设定最大记录长度 |
| 电子邮件字段标签 | 字符串 | 设置电子邮件字段的标签 |
| 电子邮件 Field 定位符 | 字符串 | 设置电子邮件字段的占位符 |
| 电子邮件 | 布尔 | 显示预填 `email` 但阻止记者编辑 仅在地址从 `email` 选项或 `setEmail()` 是有效的 —— 如果缺少或错误的字段仍然可以编辑, 所以报告人可以提供表单需要的地址 。 仅限生产模式. 默认为 `false`。 。 。 . |
| 标题字段标签 | 字符串 | 设置标题字段的标签 |
| 字段定位符 | 字符串 | 设置所有权字段的占位符 |
| 说明 字段标签 | 字符串 | 设置描述字段的标签 |
| 说明 实地定位符 | 字符串 | 设置描述字段的占位符 |
| 问题类型 | 字符串 \[\] | B. 关于 **问题类型** 报告表格中下降。 这里给出的列表取代内置选项( E)`General Enquiry`, (中文(简体) ), `Give Feedback`, (中文(简体) ), `Report a Bug`)而不是添加到其中. 条目被修剪并去复制;如果无一可用,SDK会发出警告并保留内置选项. |
| 首选项 | 布尔 | 从浏览器的截图中获取像素,而不是重新交出DOM. 默认为 `true`。见 [截图精度](https://npmcn.com/package/%40betterbugs/web-sdk/#readme-screenshot-accuracy) 见下文. |

## 截图精度

屏幕截图是用两个引擎中的一个自动拍摄的 浏览器支持.

**本地抓取( 默认, 所有桌面浏览器) .** SDK 请求浏览器 通过 `getDisplayMedia`。结果与 已看到用户,包括跨原生iframes, `<video>`, WebGL 和画布内容, 和现代CSS,例如: `backdrop-filter` 和混合模式。 区域 ("作物") 抓取从同一个框架被裁剪出,所以两种模式看起来都是一样的.

成本是每个抓取一个浏览器许可提示. 用户看到的内容 这个提示取决于引擎:

| 浏览器 | 提示 | 页:1 |
| --- | --- | --- |
| 克罗姆、边缘、歌剧、勇敢 | 此标签, 预选 | 一击确认 |
| 萨法里 (macOS), Firefox | 屏幕或窗口拾取器 | WebKit和Gecko没有显示“ 此标签” 表面, 因此用户共享屏幕或窗口, SDK 将页面的取景端切出框架 |
| 移动(iOS + Android) | —— 说 | 移动设备屏幕抓取时没有浏览器;总是使用 DOM 渲染 |

在Safari和Firefox上,SDK会自动返回到DOM渲染中 无法在共享框架中可靠地定位视图端口,或者如果框架到来 在分辨率低于DOM渲染时会产生尖锐的 相貌比真实事物模糊相.

如果用户完全排除了提示,则不拍摄截图. 下降为 被当成是"不要抓我",而不是要求低信度被俘.

**DOM渲染(倒计时).** 用于移动浏览器, 当 `preferNativeCapture: false`,当无法捕获或 根据上述规则,拒绝。 页面由 DOM 重排 `html2canvas-pro`,在 JavaScript 中重新执行 CSS 版式,因此 **某些网站不准确**. 已知的限制:

| 内容 | 结果 |
| --- | --- |
| 交叉来源 `<iframe>` (付款表、嵌入式地图、第三方部件) | Renders 空白 — 浏览器没有给出读取这些像素的任何页面方式 |
| `<video>` | 空白或海报框 |
| WebGL / 三维画布 | 仅用于装入 SDK 后创建的画布; 否则为空白 |
| `backdrop-filter`混合模式 口罩, `color-mix()` | 可能与屏幕不同 |
| 没有 CORS 头的跨原生图像 | 录取 |

当 SDK 返回到 DOM 渲染并检测到其中任何一种 捕捉地区,它显示记者 在捕捉时间警告如此 不准确的截图不会被忽略 .

设定 `preferNativeCapture: false` 总是使用 DOM 渲染而从未显示 允许即时 —— 适当, 如果该即时器在您的产品和 您的页面不包含上述内容.

## 记录模式

`recordType` 控制屏幕录制方式.

-   **`recordVideo`** ——通过浏览器的真实视频 `MediaRecorder`最高点 忠诚:它记录的是屏幕上的内容,有音频.
-   **`domRecord`** ——记录DOM突变并重放. 没有视频文件, 工作 通过页面导航保持准确.

### 离开 `recordType` 未设置( 建议)

SDK检测到访客浏览器实际能提供什么,并选择 最佳模式——在浏览器支持屏幕捕获的任何地方,真实的视频, DOM记录到其他任何地方。 浏览器引擎的记录格式不同; sDK在内部处理,所以回放和上传都一样 而你没有配置.

### 设置 `recordType` 明确

你的选择被尊重,没有能力替代 您想要在所有用户中有一个一致的录制格式。 如果浏览器 无法支持您的要求, SDK 登录一个控制台警告而不是 沉默地压倒你.

唯一的例外是 **电子**,不支持 DOM 记录: `domRecord` 被压在地上 `recordVideo` 并警告你们.

## 程序方法:控制SDK行为

控制BetterBugs SDK行为的现有方法;

| 方法 | 说明 |
| --- | --- |
| 设置电子邮件( C) | 更新错误记者的电子邮件 . |
| 设置( S) | 更新部件的样式 . |
| 获取样式( C) | 获取部件的样式 . |
| 显示 () | 显示浮动部件 |
| 隐藏( c) | 隐藏浮动部件 . |
| 打开 Widget () | 打开错误报告部件 . |
| 关闭 Widget () | 关闭错误报告部件 . |
| 设置Metadata () | 更新所附元数据. |
| 抓取Screenshot( ) | 触发截图抓取. |
| 开始记录( C) | 开始录音. |
| 停止记录( C) | 停止持续录音. |
| 日期( ) | 注册事件听众 . |
| 关闭( c) | 解除事件听众的注册 . |
| 销毁() | 摧毁BetterBugs的例子. |

## 生命周期事件钩: 为深化一体化

用于倾听生命周期事件的可用钩子 :

| 活动 | 触发描述 |
| --- | --- |
| 电子邮件 更新 | 邮件更新时触发 . |
| 截图 | 在截图被捕获后触发. |
| 开始录音 | 录音开始时触发. |
| 录音停止 | 当录音停止时触发. |
| 提交错误 | 提交错误后触发 |
| 元数据更新 | 更新元数据时触发 |
| 位置 更新 | 当部件位置改变时触发 . |
| 部件打开 | 打开部件时触发 . |
| 关闭部件 | 当部件关闭时触发 . |
| 显示动作按钮 | 显示动作按钮时触发 . |
| 隐藏动作按钮 | 当动作按钮被隐藏时触发 . |
| 会话创建 | 当创建新会话时触发 . |

## 浮动部件自定义选项

浮动部件可以通过各种方式定制:

-   **定位** ——使用{上,左,右,下}定义部件位置.
-   **UI 自定义** 修改按钮样式、背景和主色调.

## 常见问题

### @betterbugs/web-sdk 是什么？

Betterbugs 的网络 sdk 软件包

### 如何安装 @betterbugs/web-sdk？

在项目目录运行 npm install @betterbugs/web-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=16\.8\.0）、react-dom（\>=16\.8\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @betterbugs/web-sdk 支持 TypeScript 吗？

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

### @betterbugs/web-sdk 支持 ESM 还是 CommonJS？

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

### @betterbugs/web-sdk 可以商用吗？

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

### @betterbugs/web-sdk 的下载量有多少？

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

### @betterbugs/web-sdk 还在维护吗？

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