# @genn-inc/cluebase-frontend-sdk 中文文档

规范地址：https://npmcn.com/package/%40genn-inc/cluebase-frontend-sdk/

版本：0\.0\.23
npm 元数据更新时间：2026-11-11T08:50:44.883Z
中文译文更新时间：2026-11-16T03:57:19.513Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：4.2 MB，171 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：12 个
- peer 依赖：@opentelemetry/api \>=1\.10\.0 \<1\.11\.0
- 首次发布：2026-09-12T01:55:20.446Z
- 最新版本发布：2026-11-11T08:50:44.596Z
- 近 30 天下载量：2316（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

Cluebase Frontend SDK——基于OTel的观测-源事件捕获用于前端apps

## 安装

```sh
npm install @genn-inc/cluebase-frontend-sdk
```

也可以使用：`pnpm add @genn-inc/cluebase-frontend-sdk`、`yarn add @genn-inc/cluebase-frontend-sdk`、`bun add @genn-inc/cluebase-frontend-sdk`

## README

# @genn-inc/cluebase-frontend-sdk (英语)

Cluebase浏览器摄入了SDK.

## 最小融合

之后 `pnpm add @genn-inc/cluebase-frontend-sdk`,预期的Next.js集成是:

```ts
import cluebase from "@genn-inc/cluebase-frontend-sdk";

cluebase.init({
    projectKey: process.env.NEXT_PUBLIC_CLUEBASE_PROJECT_KEY!,
});

cluebase.identify(user.id, { name: user.name });
cluebase.group("organization", organization.id, { name: organization.name });
```

对于 Vite , 使用 `import.meta.env.VITE_CLUEBASE_PROJECT_KEY`对于反应应用程序 使用 Create React App env 合同, 使用 `process.env.REACT_APP_CLUEBASE_PROJECT_KEY`其他前端框架应当 使用由 Cluebase 设置生成的公有项目密钥嵌入名称.

`endpoint` 是可选的,默认为 `https://api.cluebase.io`只设置 当 SDK 必须发送到另一个 Cluebase API 基址时, 如本地 URL 环境.

`projectKey` 是公共摄入键。 API 解决权威 `tenantId`, (中文(简体) ), `projectId`,以及 dev/prod 数据 `ProjectService` 从那个钥匙。 SDK这个 附录 `/api/v1/ingest/browser-tokens` 和条形浏览器观测 内部批量路径.

## 内容 安全政策要求

SDK通过一个WebAssembly模块转换出每个 OpenTeleometry,所以 发送主机页面 `Content-Security-Policy` 标题必须允许:

-   `script-src` 必须包括 `'wasm-unsafe-eval'`。没有它,浏览器就会阻断 `WebAssembly.instantiate` 而模块从不初始化. `'unsafe-eval'` 也工作,但是一种更广泛的赠款,所以更愿意 `'wasm-unsafe-eval'`。 。 。 .
-   `connect-src` 必须允许服务于捆绑的源 `cluebase_sdk_core_wasm_bg.wasm` 资产(通常是) `'self'`),因为模块 相对于 SDK 捆绑在运行时获取.
-   `connect-src` 还必须允许 Cluebase API 来源(`endpoint`,默认情况下 `https://api.cluebase.io`) (中文(简体) ).

邦德勒斯必须释放 `.wasm` 资产。 Webpack 5, Vite, and Next.js 做到这一点 自动为 `new URL(..., import.meta.url)` 构成 SDK 用途.

如果模块无法初始化,则删除每个导出段并计为 a drop 跨度; SDK 不返回到 JavaScript 执行 . 发射前在中转环境中验证保单.

## 责任边界

-   SDK抓取浏览器信号,并在信号明显高风险的地方应用局部最小化.
-   API摄入隐私门对最终允许/拒绝/免问政策具有权威性.
-   工人侧的消毒只是防御深度.
-   SDK 发送 `projectKey`, (中文(简体) ), `schemaVersion`, (中文(简体) ), `sdkType`, (中文(简体) ), `sdkVersion`稳定键,并尽量减少捕获有效载荷.
-   SDK会的 **没有** 权威邮票 `tenant_id`, (中文(简体) ), `project_id`, (中文(简体) ), `environment_id`,或最后原始请求/反应有效载荷.

前端的SDK会 **没有** 拥有最终的原始摄取者许可名单决定.

## 默认隐私/最小化行为

前端 SDK 避免运输明显高风险的平话并保留 MVP 默认事件表面故意缩小.

-   `input_change.value` - > 仅本地值元数据
-   `selection_text` - > 仅是元数据
-   原始选择器/路径 - > 从未序列化;仅稳定键

当前 MVP 默认值 :

-   成功网络输出 1 `request_finished`
-   失败的网络发出一个 `request_failed`
-   标准动作抓取输出 `element_clicked`, (中文(简体) ), `form_submitted`, (中文(简体) ), `input_committed`, (中文(简体) ), `toggle_changed`, (中文(简体) ), `selection_committed`, (中文(简体) ), `file_selected`,以及 `drag_drop_completed`
-   队列有效载荷到达48KB发送时,正常批量冲出 阈值,默认情况下每180秒,或当页面是 离开
-   事件类型不会改变 MVP 中的发送规则

稳定的密钥优先级 :

1.  `data-testid`
2.  `data-qa`
3.  保险 `name`
4.  保险 `aria-label`
5.  结构倒置

Cluebase特定DOM属性不是MVP稳定键合同的一部分. 抓取的稳定键是最佳证据,不是权威业务 意为.

## 取样和费用警卫

-   `sampling.sessionSampleRate` 控制会话是否发出正则抓取
-   超大小事件在最后下降前分阶段降解:
    -   无生有效载荷体
    -   仅元数据/中文本
    -   只有外壳
-   超大批次停留在所配置的有效载荷下

## 流线可靠性

SDK冲出:

-   `visibilitychange` - > (中文) `hidden`
-   `pagehide`

`beforeunload` 故意不使用: 它禁用后向缓存/ 前向缓存 在移动浏览器上是不可靠的.

排行榜是最佳办法 SDK 持续未发送源事件 `localStorage` 并仅在摄入的 API 接受批量后将其删除. 生命周期会话 URL 在输入原始内容之前, 剥离查询字符串和散列 SDK事件有效载荷.

Token 获取失败, 以指数回放重排下一场冲浪 和 jitter( 基数 1, 顶数 30, 5 后倒回正常的冲浪腔) 尝试); 永久失败(例如被撤销的项目)停止重试而不是 永远旋转.

## 保留冲洗合同

-   卸载/ 隐藏冲出总是试图通过认证送出 `fetch` 与 `keepalive` 提示, 无论浏览器符号是否是 已缓存
-   当批量只包含两个具有 URL安全倒计时(`project_key`, (中文(简体) ), `browser_token` ——见后端 `fix/browser-ingest-token-query-fallback`和有效载荷加上这些 查询参数符合共享的 64 KiB `fetch`编号 :`sendBeacon` 预算 也尝试卸下冲洗 `navigator.sendBeacon` 首先,它保持 页面被撕下后发送。 A 类 `sendBeacon` 队列成功是 从未作为确认的发送处理( 浏览器 API 无法报告) 服务器侧结果 ; 它回到相同的恒定外框重试 财务报告和审定财务报表 `idempotency_key` 除去其它未解决的发送

## 退化事件合同

下游摄入剂必须接受这些作为正常输入:

-   无生有效载荷体
-   仅元数据 + 计划
-   只有 shell 事件

## 隐私和PII处理

SDK应用了分层隐私模型:

### 1\. 硬密度:PII/运输前秘密被剥去

SDK 剥离一组内置属性密钥 **在此之前** 活动结束 浏览器。 这些密钥无法被所交付的隐私政策所揭开—— 选择 `body.email` 在 Cluebase 隐私屏幕中不会绕过 难为倒地.

硬密度类别(大小写和分隔符不敏感) - `userEmail`, (中文(简体) ), `user-email`, (中文(简体) ), `USER_EMAIL`, (中文(简体) ), `email_address` 全部匹配 :

-   认证证书 : `authorization`, (中文(简体) ), `cookie`, (中文(简体) ), `set-cookie`, (中文(简体) ), `password`, (中文(简体) ), `passwd`, (中文(简体) ), `secret`, (中文(简体) ), `token`, (中文(简体) ), `access_token`, (中文(简体) ), `refresh_token`, (中文(简体) ), `session`, (中文(简体) ), `session_token`, (中文(简体) ), `api_key`, (中文(简体) ), `apikey`, (中文(简体) ), `private_key`
-   PII类: `email`, (中文(简体) ), `phone`, (中文(简体) ), `credit_card`, (中文(简体) ), `ssn`

此列表是服务器端最难被摄入的严格超级集 (单位:千美元)`@cluebase/shared` `INGEST_HARD_DENY_KEYS`)),通过CI对等测试执行 所有三个SDK.

### 2\. 默认假冒:任意值被掩盖,除非允许列入清单

穿过硬地门的属性仍然 **默认隐藏**。 。 。 . SDK释放出指纹或只有形状的文摘,而不是原始值.

要在简写中捕捉到一个特定的领域,两件事都必须是真实的:

1.  现场路径在 Cluebase 隐私屏幕中选择. Cluebase提供 选择SDK与摄取反应,SDK应用. 这是 不是一个 `init` 选项:在政策到达之前,以及何时交付 无法读取策略, 每一个值都会被掩盖 .
2.  相同的属性密钥出现在工程的服务器侧 项目服务 `observationAnalysisPropertyAllowlist`。 。 。 .

如果条件1持有但条件2不持有,则该值存储在 原始观察存储仅 - `facts_json.analysisProperties.projected` 将 空并域不会出现在 Cluebase 分析 UI 中.

### 3\. 操作结果:在发射前配置服务器许可列表

未设定发射的客户 `observationAnalysisPropertyAllowlist` 将会看到自定义事件名称在 `observation_type` 不过 **无预测属性** 在仪表板。 这个 原始观察商店保存有用于调试的被遮盖/仅使用的证据,同时 分析投影仍然为空,直到服务器允许列表包含 字段。 通过 Cluebase 管理员 UI 或工程服务配置服务器授权列表 允许列表 API 在对您想要的属性名称进行隐私审查后 分析项目.

## 建筑边界

前端SDK是一个浏览器包装器 围绕捕获,隐私最小化, 相关传播和运输。 发送源信号信封 作为 `sdk_source_signal_observed`; Cluebase 后端摄入核心执行最终 分类、未知的诊断处理、后端请求相关性,以及 最原始的正常化.

```text
browser capture / OTel network span
  -> frontend SDK source-signal envelope
  -> /api/v1/ingest/browser
  -> apps/api/src/modules/ingest core
```

规则:

-   保持浏览器代码限于原始事实、关联上下文、标准OTel 属性、局部最小化和运输.
-   不添加仅前端分类, 源码策略, 语义 DOM 说明,或自定义后退行为.
-   在后端摄入器核心中添加分类器行为, 这样前端发源 请求,Node.js,Python,以及未来的SDK包装器都会收到同样的行为.
-   保护 `interaction_id`, (中文(简体) ), `request_span_id`, (中文(简体) ), `request_id`,以及 `trace_id` 只要有时间 用户-行动联系是一种吸收性合同,而不是 仅显示字段.

### 明确事件 Emit: `cluebase.track`

当 DOM 自动抓取不能推断操作时( 例如自定义) 键盘快捷键、 API 唯一背景同步或多步 UI flow),主机app可能释放出一个明确的语义动作:

```ts
import cluebase from "@genn-inc/cluebase-frontend-sdk";

cluebase.track("report.create", { source: "shortcut", result: "success" });
```

`cluebase.track` 输出 a `custom_emitted` 用于非产品动作的事件 由DOM自动抓取覆盖. 保持财产隐私的安全和稳定;工人 下游产生更高层次的语义学. 事件名称必须匹配 `^[A-Za-z0-9_.:-]{1,128}$`; 无效的名字在公开警告下删除.

### 身份生命周期:组织

前端的 SDK 暴露了 MVP 身份识别的生命周期 API,工人使用 保存匿名 识别用户 组织证据:

```ts
cluebase.identify("user_42", { plan: "pro" });
cluebase.group("organization", "org_3", { name: "Acme Inc." });
cluebase.reset();
```

MVP没有暴露 Cluebase `account` 或者说 `workspace` 作为公共团体类型。 如果 客户产品将其公司概念称为账户、工作空间、租户,或 球队,通过稳定 公司编号作为 `cluebase.group("organization", ...)`。 。 。 . 空白或非字符串 `identify` 用户编号和 `organization` 组 id 是 以公开警告方式删除, 不更新 SDK 身份状态 .

## 常见问题

### @genn-inc/cluebase-frontend-sdk 是什么？

Cluebase Frontend SDK——基于OTel的观测-源事件捕获用于前端apps

### 如何安装 @genn-inc/cluebase-frontend-sdk？

在项目目录运行 npm install @genn-inc/cluebase-frontend-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@opentelemetry/api（\>=1\.10\.0 \<1\.11\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @genn-inc/cluebase-frontend-sdk 支持 TypeScript 吗？

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

### @genn-inc/cluebase-frontend-sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @genn-inc/cluebase-frontend-sdk 可以商用吗？

@genn-inc/cluebase-frontend-sdk 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @genn-inc/cluebase-frontend-sdk 的下载量有多少？

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

### @genn-inc/cluebase-frontend-sdk 还在维护吗？

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

