@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 中的发送规则
稳定的密钥优先级 :
data-testiddata-qa- 保险
name - 保险
aria-label - 结构倒置
Cluebase特定DOM属性不是MVP稳定键合同的一部分. 抓取的稳定键是最佳证据,不是权威业务 意为.
取样和费用警卫
sampling.sessionSampleRate控制会话是否发出正则抓取- 超大小事件在最后下降前分阶段降解:
- 无生有效载荷体
- 仅元数据/中文本
- 只有外壳
- 超大批次停留在所配置的有效载荷下
流线可靠性
SDK冲出:
visibilitychange- > (中文)hiddenpagehide
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 KiBfetch编号 :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释放出指纹或只有形状的文摘,而不是原始值.
要在简写中捕捉到一个特定的领域,两件事都必须是真实的:
- 现场路径在 Cluebase 隐私屏幕中选择. Cluebase提供
选择SDK与摄取反应,SDK应用. 这是
不是一个
init选项:在政策到达之前,以及何时交付 无法读取策略, 每一个值都会被掩盖 . - 相同的属性密钥出现在工程的服务器侧
项目服务
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 身份状态 .