# @brizz/browser 中文文档

规范地址：https://npmcn.com/package/%40brizz/browser/

版本：0\.3\.3
npm 元数据更新时间：2026-10-28T14:02:27.257Z
中文译文更新时间：2026-11-08T15:46:00.748Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40brizz/browser
原文对照：https://npmcn.com/package/%40brizz/browser/?lang=original
项目主页：https://www.brizz.ai/

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

- 包体积（解压后）：210 kB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：8 个
- peer 依赖：logrocket \*
- 首次发布：2026-05-21T12:08:38.916Z
- 最新版本发布：2026-10-28T14:02:27.047Z
- 近 30 天下载量：39648（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

用于浏览器的 Brizz 产品分析 SDK

## 安装

```sh
npm install @brizz/browser
```

也可以使用：`pnpm add @brizz/browser`、`yarn add @brizz/browser`、`bun add @brizz/browser`

## README

# @britz/浏览器

[布丽兹](https://www.brizz.ai/) 用于浏览器应用的产品分析 SDK. 输出 `track('event_name', {...})` 调用 OpenTeleometry 日志记录到您的 Brizz 网关, 所以前端 在同一 Brizz 会话中,相互作用与后端代理跟踪相关.

轻量级和依赖型灯:一个小捆绑,没有框架锁定,而PII口罩被建入. 通过 npm 或 CDN 丢入任何网络应用程序 `<script>` 标记并开始发送几行事件.

> 将分析器建为节点后端? 使用 [`@brizz/sdk`](https://www.npmjs.com/package/@brizz/sdk)。 。 。 .

## 安装

```bash
npm install @brizz/browser
# or
pnpm add @brizz/browser
```

或者通过CDN:

```html
<script src="https://unpkg.com/@brizz/browser/dist/index.iife.js"></script>
<script>
  const brizz = Brizz.init({ dsn: 'https://brizz-ing-c-XXX@telemetry.brizz.dev/acme-web' });
  brizz.setSessionId('session-from-your-backend');
  brizz.track('clicked_submit', { plan: 'pro' });
</script>
```

## 快开始

```ts
import { Brizz } from '@brizz/browser';

const brizz = Brizz.init({
  dsn: 'https://brizz-ing-c-9k3xPq2v...@telemetry.brizz.dev/<service-name>',
});

// Same session_id your backend uses on agent traces:
brizz.setSessionId('session-from-your-backend');

brizz.track('clicked_submit', { plan: 'pro', step: 'checkout' });
```

## 输入选项

| 选项 | 类型 | 页:1 |
| --- | --- | --- |
| `dsn` | `string` | 客户端 DSN URL : `https://brizz-ing-c-<bearer>@<host>/<service>`相互排斥 `apiKey`编号 :`baseUrl`编号 :`appName`。 。 。 . |
| `apiKey` | `string` | 手持证相. 使用代替 `dsn` 如果你喜欢明确的选项。 必须是客户 DSN ()`brizz-ing-c-`) (中文(简体) ). |
| `baseUrl` | `string` | 网关来源,例如:. `https://telemetry.brizz.dev`。无需 `dsn`。 。 。 . |
| `appName` | `string` | 服务名称; 成为 `service.name`。无需 `dsn`。 。 。 . |
| `disableBatch` | `boolean` | 立即把每起事件都打扫干净 默认 `false` (活动批次为~5秒). |
| `logLevel` | `'debug' | 'info' | 'warn' | 'error' | 'none'` | 默认 `'warn'`。 。 。 . |
| `masking` | `boolean | object` | 启用带有内置模式的 PII 掩码( N)`true`)或提供自定义配置. |
| `headers` | `Record<string, string>` | 每个OTLP请求附加的可选附加HTTP头. |

## 会话关联

浏览器 SDK 是 **没有** 薄荷、旋转或持续会话编号。 你来决定身份 通常你自己的后端薄荷薄荷把它传播到前端(这个SDK)和 您的代理后端( 节点 SDK) 。 每个 `track()` 调用 id 作为 `LogAttributes['brizz.session.id']` (canonic Brizz键——同节点SDK使用的一键) 这样 Brizz可以 加入仪表板上的两半 事件名称类似反射到 `LogAttributes['event.name']`。 。 。 .

### 默认会话

对于常见的单会场案件,一次次设定编号 `track()` 用它来:

```ts
brizz.setSessionId('whatever-the-customer-decides'); // sticky across track() calls
brizz.track('clicked_submit', { plan: 'pro' });
brizz.setSessionId(null); // e.g. on logout
```

### 平行会议

当单页主机超过一个逻辑会话( 如两个聊天部件, 并排) 比较一下,在支持聊天的同时打开一个产品内副驾驶,使用 `brizz.session(id)` 获取一个 带会话的发射器。 每个 `track()` 在邮票上 绑定的id,独立于 默认.

```ts
const supportChat = brizz.session('support-thread-7');
const copilot = brizz.session('copilot-session-42');

supportChat.track('typed', { length: 12 });
copilot.track('accepted_suggestion', { tool: 'rename' });
```

范围放出物是便宜的——每个会话缓存一次再利用,或者在苍蝇上创建. 他们分享 同样的基础运输,所以 `brizz.flush()` 冲出一切; `supportChat.flush()` 是一个 方便代表给父母.

偏爱 `brizz.session(id)` 将默认值替换为 `setSessionId` 前后时 课程是并行的——同步事件处理器通过互换,否则会盖上错误的id.

## 自动文本

每个 `track()` 调用自动附加以下属性,全部在 `brizz.internal.browser.*` 名称空间 :

-   `brizz.internal.browser.current_url`, (中文(简体) ), `brizz.internal.browser.referrer`, (中文(简体) ), `brizz.internal.browser.page_title`
-   `brizz.internal.browser.browser`, (中文(简体) ), `brizz.internal.browser.browser_version`, (中文(简体) ), `brizz.internal.browser.os`, (中文(简体) ), `brizz.internal.browser.os_version`, (中文(简体) ), `brizz.internal.browser.user_agent`
-   `brizz.internal.browser.locale`, (中文(简体) ), `brizz.internal.browser.screen_width`, (中文(简体) ), `brizz.internal.browser.screen_height`

这些来自 `window`, (中文(简体) ), `document`, (中文(简体) ), `navigator`,以及 `screen` 在事件燃起的时刻.

## 会话重播关联

如果您的页面还运行 FullStory, Mixpanel 会话重放, 或者 LogRocket, Briz 自动目录 与匹配会话一起录制。 Brizz会话上出现了深层连锁徽章 仪表板——一击重放.

| 提供者 | 设置 | 选择出去 |
| --- | --- | --- |
| 完整的故事 | 无——当他们的片段在页面上时自动发现 | `disableFullStory: true` |
| 混音板 | 无 – 在工程上启用会话重放时自动检测到 | `disableMixpanel: true` |
| 日志 | CDN片段没有. 关于npm包,见下文. | `disableLogRocket: true` |

对于日志 **npm 软件包**,添加一个副作用导入:

```ts
import { Brizz } from '@brizz/browser';
import '@brizz/browser/integrations/logrocket';
import LogRocket from 'logrocket';

LogRocket.init('myapp/myapp');
Brizz.init({ dsn: '...' });
```

## 线条格式

每个 `track()` 生产一个OTel记录,由 `BatchLogRecordProcessor` 导出为 电话: OTLP-JSON `<baseUrl>/v1/logs`数字 :

```http
POST https://telemetry.brizz.dev/v1/logs
Authorization: Bearer brizz-ing-c-9k3xPq2v...
X-Brizz-Service-Name: acme-web
Content-Type: application/json

{ "resourceLogs": [...] }
```

那么,网关:

1.  认证客户端 DSN 记号符
2.  检查 `Origin` 与允许的DSN原产地对抗
3.  重写资源 `service.name` 从 `X-Brizz-Service-Name`
4.  出版到NATS 不变

## 套装大小

包裹船有三种形式:

| 构建 | 大小( gzip) | 使用 |
| --- | --- | --- |
| 无害环境管理`dist/index.js`(中文(简体) ) | ~8千贝 | npm + 捆绑(Vite/Webpack/Rollup). OTel道具保持对外. |
| CJS (英语:`dist/index.cjs`(中文(简体) ) | ~8千贝 | npm for CommunityJS Conserence. 中国植物物种信息数据库. |
| IIFE( 国际妇女教育研究所)`dist/index.iife.js`(中文(简体) ) | ~19 KB 键 | 光盘N `<script>` 标签。 OTel 防弹针捆绑. |

如果捆绑超过其预算大小, CI 失败 `size-limit` 配置为 `package.json`) (中文(简体) ).

## 浏览器支持

目标ES2022——以现代常绿浏览器(Chrome,Safari,Firefox,Edge)运行.

## 链接

-   [网站](https://www.brizz.ai/)
-   [文档](https://docs.brizz.ai/)

## 许可证

阿帕奇 - 2.0

## 常见问题

### @brizz/browser 是什么？

用于浏览器的 Brizz 产品分析 SDK

### 如何安装 @brizz/browser？

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

### @brizz/browser 支持 TypeScript 吗？

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

### @brizz/browser 支持 ESM 还是 CommonJS？

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

### @brizz/browser 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @brizz/browser 可以商用吗？

@brizz/browser 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @brizz/browser 的下载量有多少？

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

### @brizz/browser 还在维护吗？

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