@model-go/track

ModelGo 前端埋点 SDK —— 统一批量上报、公共属性自动注入、脱敏白名单。

供 6 个终端接入：app(console_web / marketing_web / doc_web) × region(cn / global)。

安装

pnpm add @model-go/track

用法

import { init, track, pageView, TrackApp, TrackRegion } from '@model-go/track'

init({
  app: TrackApp.ConsoleWeb,
  region: TrackRegion.CN,
  // baseURL 不传 = 相对路径，走当前域名自带的 /api 代理（console-web 现有约定）
  // reportIntervalMs / maxBatchSize / sampleRate 不传则用内置兜底 5000ms / 50 / 1
})

track('api_key_create_click', { source: 'overview_page' })
pageView('overview', '/dashboard', { view_mode: 'mine' })

登录态（如控制台）附带额外请求头（如 X-Tenant-Id）：

init({
  app: TrackApp.ConsoleWeb,
  region: TrackRegion.CN,
  // 每次上报时动态调用，反映当前最新的租户/工作区状态
  getAuthHeaders: () => ({
    'X-Tenant-Id': getActiveTenantId(),
  }),
})

React：

import { useTrack } from '@model-go/track/react'

function OverviewPage() {
  const { pageView, track } = useTrack()
  useEffect(() => { pageView('overview') }, [])
  return <button onClick={() => track('export_click')}>导出</button>
}

设计要点

• 接口路径固定：POST /api/v1/events:batch 写死在 SDK 内部，调用方只能通过 baseURL 换域名，换不了路径。
• 上报节奏可按终端配置：reportIntervalMs/maxBatchSize/sampleRate 是 init() 的一等参数，6 个终端各自按场景传值；不传则用内置兜底 5000ms/50/1。P1 接入远程配置接口后优先级为 远程配置 > init 显式值 > 内置兜底。
• 脱敏白名单：props 只允许 string/number/boolean，命中黑名单关键字（token/secret/prompt/response/email/phone 等）或黑名单值模式的字段直接丢弃，不做"打码后上报"。
• 可靠性：定时器 flush + 达到 maxBatchSize 立即 flush + 页面卸载用 sendBeacon 兜底；event_id 保证 ingest 侧幂等去重。
• 前端只报意图/曝光/点击：结果与金额一律以服务端事实为准，埋点不作为计费与安全追责依据。

开发

pnpm install
pnpm build
pnpm test
pnpm typecheck

发布

pnpm release          # patch，非交互直接发布
pnpm release -- minor
node scripts/release.mjs patch --dry   # 演练，不发不推

License

MIT © ModelGo