@yunzhimao/telemetry

通用行为采集 SDK，源码统一维护在 CRM 仓库的 packages/telemetry-sdk，宿主安装 npm 精确版本。只采集显式行为，不自动捕获 DOM、URL、请求内容或异常。

浏览器

import { createBrowserTracker } from '@yunzhimao/telemetry/browser';

// 宿主使用自己的登录态访问自己的后端；返回 TokenSession + endpoint。
const session = await getHostTelemetrySession();
const tracker = createBrowserTracker({
  identity: session.identity,
  endpoint: session.endpoint,
  appVersion: 'example-1.0.0',
  getToken: () => getHostTelemetrySession(),
});
void tracker.active(); // 仅在已登录用户实际可见访问时调用。
void tracker.track('listing.collect.opened', { });
void tracker.track('listing.collect.submitted');

identity 必须来自宿主后端登录上下文。收到不同身份的 Token 时 SDK 清空队列并暂停，不能用新账号补发旧事件。退出、账号/主体/实例切换先 await tracker.reset() 再 await tracker.destroy()，之后创建新实例；宿主应在网络结果回来后再次核对登录身份，避免异步初始化串号。

插件 / 无 DOM 环境

import { createTracker, extensionStorage } from '@yunzhimao/telemetry/extension';
const tracker = createTracker({
  identity: session.identity, endpoint: session.endpoint, appVersion: 'example-1.0.0',
  getToken: getHostTelemetrySession,
  storage: extensionStorage(chrome.storage.local),
  flushIntervalMs: 0,
});
await tracker.ready;
await tracker.track('listing.collect.submitted', { });
void tracker.flush();

只有 background 获取 Token、创建 SDK 和发送。content script / popup 通过受控内部消息提交固定 eventName和基础设备信息，不能得到 Token；后台验证 sender 和字段。新事件或唤醒时恢复队列并 flush，不能靠 setInterval 保证 MV3 常驻。安装标识可由宿主持久化后通过 anonymousId 注入。业务流程不要等待 flush()；内部消息在 track() 持久化完成后可确认接收。

行为与边界

• eventName 是唯一点位 key，例如 listing.collect.opened / listing.collect.submitted；保留 app.active。业务目录由宿主与 Collector 维护，SDK 不携带 ERP 字典。属性只能发送该点位目录声明的字段，不传用户对象或任意业务数据。
• 默认 20 条 / 10 秒，最多 500 条 / 1 MiB / 24 小时；溢出丢最旧项。只收到 200 且 accepted 等于批次条数后出队。
• 401 最多立即续取一次，429 遵守 Retry-After，网络/5xx 有界退避；413 拆批，422 按索引丢弃坏事件。
• Token 只在内存中，不进入离线队列；事件重试保持 eventId 和原始时间。安装标识不是设备指纹，行为不是可信业务结算依据。
• track() 不等待网络且不向业务抛采集错误；存储失败退回内存。onDiagnostic(code, count) 不含原始事件或 Token。
• destroy() 卸载监听/定时器并保留队列；退出登录必须先 reset() 清队列。关页发送仅尽力而为，关闭标签页的未发送快照不承诺由其他标签页补发，过期后清理。
• 默认入口依赖现代运行时的 fetch、TextEncoder 和安全随机能力；0.2.1 起优先使用 crypto.randomUUID，HTTP 环境缺少该方法时使用 crypto.getRandomValues 生成标准 UUID v4，不使用 Math.random。两者都不可用时初始化报 secure_random_unavailable；浏览器子路径要求 DOM，IndexedDB 不可用时降级内存，插件 storage 由调用方注入；无 Vue/Pinia/CRM 商业依赖。此兼容不替代生产环境的 HTTPS 传输保护。

验证与发布

在仓库根目录运行 pnpm --filter @yunzhimao/telemetry test。pnpm --filter @yunzhimao/telemetry pack --pack-destination .tmp 只生成本地包，不发布。包内容限定为 ESM dist、CommonJS cjs、类型声明和本说明。

发布时同时更新 package.json 与 src/index.ts 的版本号，测试通过后进入 packages/telemetry-sdk 执行 npm publish --access public --registry=https://registry.npmjs.org。宿主使用新版本前需更新依赖、重新构建和部署；仅发布 npm 不会更新已部署页面。不要删除源码目录，也不要把私钥、环境配置、内部服务端包或其他仓库打入包。

ERP 后端 / Node

默认入口同时提供 ESM import 和 CommonJS require，要求 Node 22.12+，使用同一个 createTracker；按可信登录账号隔离队列，禁止跨账号共享 tracker。后端只报告目录中的处理结果，不调用 active()、不带用户设备，不把服务器出口当用户地域。ERP 适配层最多 100 个账号队列，每账号 50 条 / 64 KiB，闲置 5 分钟销毁；无磁盘队列，不保证零丢失。