@genn-inc/cluebase-frontend-sdk

中文文档
0.0.23发布于 2026/11/11TypeScriptES Module近 30 天下载 2316

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

中文使用文档
文档目录15 节
  1. 最小融合
  2. 内容 安全政策要求
  3. 责任边界
  4. 默认隐私/最小化行为
  5. 取样和费用警卫
  6. 流线可靠性
  7. 保留冲洗合同
  8. 退化事件合同
  9. 隐私和PII处理
  10. 1. 硬密度:PII/运输前秘密被剥去
  11. 2. 默认假冒:任意值被掩盖,除非允许列入清单
  12. 3. 操作结果:在发射前配置服务器许可列表
  13. 建筑边界
  14. 明确事件 Emit: cluebase.track
  15. 身份生命周期:组织

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

Cluebase浏览器摄入了SDK.

最小融合

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

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 后端摄入核心执行最终 分类、未知的诊断处理、后端请求相关性,以及 最原始的正常化.

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可能释放出一个明确的语义动作:

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,工人使用 保存匿名 识别用户 组织证据:

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 共发布 16 个版本,首次发布于 2026/09/12;过去 12 个月发布了 16 个版本。

版本发布日期距今
0.0.23latest2026/11/114 天前
0.0.202026/11/115 天前
0.0.192026/11/096 天前
0.0.182026/11/0510 天前
0.0.172026/11/0511 天前
0.0.152026/11/0213 天前

关于 @genn-inc/cluebase-frontend-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 和提交记录判断。