事件类型与业务埋点

浏览器事件使用统一结构。SDK 自动生成 eventId、访客/会话 ID、页面、语言、屏幕、设备信号和发生时间；登录后的业务用户关联需要 identify。重试保留相同 eventId。

{
  "eventId": "stable-event-id",
  "appId": "your-app-id",
  "type": "event",
  "sessionId": "session-id",
  "visitorId": "visitor-id",
  "userId": "optional-business-user-id",
  "url": "https://example.com/checkout",
  "path": "/checkout",
  "hostname": "example.com",
  "timestamp": 1791676800000,
  "data": {"name": "checkout_completed", "plan": "pro"}
}

时间使用实际 Unix 毫秒，不要复制示例时间。受理与限制见采集 API。

自定义事件

在业务成功回调中执行。使用控制台安装代码的指令队列，可兼容 SDK 异步加载：

window.antdock.push(['trackEvent', 'subscription_started', {
  plan: 'pro', channel: 'website'
}]);

如果只表达一次按钮点击，使用声明式属性：

<button data-antdock-event="signup_cta" data-antdock-prop-plan="pro">开始试用</button>

按钮点击和表单提交不能代表真实注册或付款成功。事件名保持稳定，不要将订单号或用户 ID 拼进事件名。声明式事件名称以英文字母开头，使用字母/数字/下划线/点/冒号/连字符，最长 100 字符。

事件分析提供事件数、会话数、访客数及最近时间；可按页面、来源、国家、设备、浏览器或一个自定义标量属性分组。属性键限英文字母开头、字母/数字/下划线/连字符、最长 40 字符。嵌套对象和数组可保留，但不作为该分析页的分组维度；金额属性不会自动生成 SUM/AVG 指标。

用户关联与标准电商

// 登录成功后，传稳定业务 ID；无需传姓名、邮箱或密码
window.antdock.push(['identify', 'USER-123', { plan: 'pro' }]);

// 后端确认付款后，保留稳定订单号与实际币种/金额
window.antdock.push(['trackEcommerce', {
  action: 'purchase', transactionId: 'ORDER-123',
  revenue: 99.99, currency: 'CNY',
  items: [{ id: 'SKU-1', name: 'Pro', price: 99.99, quantity: 1 }]
}]);

// 退出业务账号时重置关联
window.antdock.push(['reset']);

标准电商事件存为 type=event，名称例如 ecommercePurchase。普通 trackEvent('purchase', {amount: 99.99}) 不会自动成为标准收入报表的数据。

自动采集的数据

能力从该应用的控制台开关读取；安装一次后无需重新安装。字段名与 SDK 一致，以下为主要 data 字段，并非任意服务端 JSON 映射。

事件/能力	type / 名称	主要内容
页面与 SPA 路由	pageview	title 与实际访问的 url/path
点击	click	x/y、selector、elementPath、tag、viewportWidth/viewportHeight；安全标签可用 data-antdock-label 显式提供
滚动	event / scrollDepth	depth；按滚动里程碑记录
表单	form	formAction=start/submit/abandon、formId、fieldCount、filledCount、fillTimeMs；不采输入值
API 请求	api	method、url（路径）、status、duration、ok；不采请求/响应正文
错误	error	errorType、message、stack、filename、lineno、colno 等
浏览器性能	webvital	metric、value；TTFB/FCP/LCP/CLS/INP
会话	heartbeat / session	累计活跃、持续时间等信息
媒体	media	action=play/pause/ended 等、媒体标签/路径及播放进度

错误类型使用 jsError、promiseRejection、resourceError、apiError。框架已捕获的异常需要框架错误桥接；SDK 不能自动知道所有业务失败。

{"type":"error","appId":"your-app-id","data":{"errorType":"jsError","message":"Example error","filename":"app.js","lineno":123}}

Web Vitals 使用独立 webvital 事件，不是把所有指标塞进普通自定义事件。除 CLS 为无单位小数外，主要耗时值使用毫秒；指标是否产生取决于浏览器支持与实际交互，INP 需要交互。

{"type":"webvital","appId":"your-app-id","data":{"metric":"CLS","value":0.002}}

独立采集契约

performance 与 leave 可用于兼容相应客户端，不能将任意名字当作已支持的 type。服务器访问日志 type=request 使用认证的 /api/v1/workspaces/:workspaceId/requests；AI 追踪使用 AI SDK 和 /api/ai/trace/batch。不要把 request 或 llm_trace 发到通用浏览器采集接口。

SDK 遵循远程开关、隐私设置与采样策略；一次业务事件的浏览器上报不等于权威业务账本或零丢失保证。自定义服务端业务接口的定时拉取、schema 映射和任意指标计算目前尚未提供。