数据收集 API

接口与用途

接口	方法	用途
/api/collect	POST	单条浏览器/客户端事件
/api/collect/batch	POST	批量事件
/api/v1/workspaces/:workspaceId/requests	POST	认证的服务器访问日志，不是通用业务 JSON 导入
/api/ai/trace/batch	POST	AI SDK 专用追踪，使用独立契约

浏览器优先使用控制台生成的 SDK 安装代码。业务服务可按下面格式主动推送事件，需要自行完成业务字段适配。目前没有可配置的外部业务 API 定时拉取连接器。

批量事件

POST /api/collect/batch
Content-Type: application/json
Origin: https://example.com

{
  "events": [{
    "appId": "your-app-id",
    "eventId": "subscription-started-123",
    "type": "event",
    "sessionId": "sess-123",
    "visitorId": "visitor-123",
    "userId": "user-123",
    "url": "https://example.com/billing",
    "path": "/billing",
    "hostname": "example.com",
    "timestamp": 1791676800000,
    "data": {"name": "subscription_started", "plan": "pro", "amount": 49.5}
  }]
}

timestamp 使用实际发生时间（Unix 毫秒）；不要照抄示例时间。重试必须保留同一 eventId，不要每次重新生成。事件 ID 的去重能力受队列和存储的去重窗口约束，不是永久幂等保证。

正常响应为 HTTP 200：

{"accepted": 1, "dropped": 0, "sourceRejected": 0}

accepted 表示持久受理，不表示已经入库可查询，也不表示业务事件的真实性已经验证。重传被受理后可以在队列中去重，因此它不是最终新增记录数。dropped 包含结构不合格、应用不可采集、功能关闭、来源拒收、配额采样和超出单批上限等情况；sourceRejected 是其中的来源拒收数。当前没有逐条事件错误列表。

字段与限制

字段	说明
appId	必填，控制台应用 ID，不是工作空间 ID
type	必填，受支持的事件类型
eventId	推荐，稳定且唯一，最长 128 字节，重试复用
sessionId / visitorId	最长 128 字节；缺失时无法可靠去重会话/访客
userId	可选稳定业务用户 ID，最长 256 字节
url / hostname / path	网站事件应填写实际来源，长度上限分别 4096/255/2048 字节
timestamp	实际发生时间；服务端对异常时间做归一化
data	事件附加 JSON，上限 64 KiB；自定义事件使用 data.name

支持 pageview、event、identify、click、scroll、error、form、api、performance、webvital、session、heartbeat、media、兼容类型 leave。AI 追踪及服务器 request 日志使用独立接口。

单批最多 100 条，多出的事件会计入 dropped，请在客户端拆批。服务端对其他元数据、屏幕尺寸、UTM 和来源字段也有校验；不承诺旧文档中的 JSON 深度 5 层或统一 30 天拒收规则。

自定义事件属性分组只支持标量，键须以英文字母开头，使用字母、数字、下划线或连字符，最长 40 字符。金额属性不会自动成为收入求和指标；标准电商报表需使用 trackEcommerce。

单条事件

/api/collect 请求体为上述 events 数组中的单个对象。正常接收返回 {"status":"ok"}；关闭采集、关闭功能或采样可能返回其他状态。来源拒收返回 403；无效结构返回 400；应用不存在返回 404。检查响应正文，不能仅判断 response.ok。

鉴权、来源与重试

浏览器采集接口不需要登录，应用 ID 是公开标识。来源域名校验不能防止服务端伪造 Origin，也不能代替业务数据源鉴权。不要把 API Key 放入网页。

服务器访问日志 /api/v1/workspaces/:workspaceId/requests 需要 X-API-Key、工作空间上下文，且应用必须属于该工作空间；受理成功返回 HTTP 202。它接受 {appId, requests}，每条包含稳定 eventId、时间、IP、User-Agent、URL、HTTP 方法、状态和耗时，不接受任意订单字段映射。

采集端点支持跨域，应用的允许来源策略仍然生效。代理提供的客户端 IP 只有在可信代理设置正确时才可信。不要通过客户端请求头或 JSON 冒充真实客户 IP。

网络错误、429 和 5xx 可按退避策略重试，并尊重 Retry-After。503 ingestion_unavailable 表示持久入队失败。200 丢弃不宜盲目重试，应先检查来源、设置、配额与结构。默认 SDK 有有限重试和缓存，页面退出时的 sendBeacon 返回 true 只表示浏览器接收发送任务。

接入验收应确认受理后在「验证接入」和事件分析中可查询。业务数据质量还需要独立鉴权、字段契约、幂等业务键、完整性对账和失败重放；当前公共采集不等于通用业务数据平台。