快速接入

订单、注册、退款这类事实从你的服务器上报，不依赖访客浏览器。同一幂等键再发不会多出一行，所以失败后可以放心重放。

前提

你是项目的「所有者」或「管理员」。密钥权限要包含「服务端 Track」。不要把完整密钥写进仓库或文档。

步骤

1. 创建密钥

   打开 控制台配置设置API 密钥，创建时勾选「服务端 Track」。密钥以 wck_ 开头，只在创建时出现一次。

2. 提交一条事件

   向 POST /api/v1/track 发送 JSON。Authorization 用 Bearer wck_…，不要写全密钥。insert_id 最长 36 个字符。time 是毫秒；与服务器相差超过 72 小时时改用当前时间并告警，默认不拒绝。

   curl -X POST "https://YOUR_ORIGIN/api/v1/track" \
     -H "Authorization: Bearer wck_…" \
     -H "Content-Type: application/json" \
     -d '{"events":[{"event":"purchase","login_id":"u_123","insert_id":"order-1001","properties":{"revenue":19.9}}]}'

3. 看响应

   accepted 是通过校验并写入缓冲的条数。rejected 大于 0 时，结果里会带上原因，例如缺少事件名。加查询参数 debug=1 只校验、不入库。

验证

在 控制台全端分析数据管理事件与属性 或 控制台网站统计事件 看到 purchase。带了 login_id 的事件可以出现在对应用户下。

不带会话标识的事件只进事件表，不会被算成一次新的网站访问。要对上某次浏览，把那次浏览的会话标识一并带上。

常见失败

密钥缺失、无效或没有「服务端 Track」权限会返回 401。没有事件名会被拒绝。/api/v1/server/events 是另一条通道，只保留机器人访问，不能用来记订单，见 服务端事件与日志导入。

服务端事件与日志导入

只有业务事件接口能写订单和注册；另外两条只保留被识别成机器人的请求，用来补不执行脚本的抓取。

密钥在 控制台配置设置API 密钥。三条接口分别要「服务端 Track」「写入服务端事件」「导入日志」权限，请求头都是 Authorization: Bearer wck_…。

三条接口

• POST /api/v1/track 写业务事件。
• POST /api/v1/server/events 提交访问记录，人类请求记入 skippedHuman 后丢弃。
• POST /api/v1/server/logs/import 接收 Nginx / Apache combined 格式的日志行，解析失败的行不计入已解析数。

参数

业务事件体是 { "events": [ … ] }，1 到 1000 条。常用字段：

字段	是否必填	说明
type	否	默认 track，还可改档案、绑定标识或按幂等键更新
event	记行为时必填	最长 100
insert_id	更新时必填	最长 36。普通重发不新增一行，先到的保留
session_id	否	最长 32；空着则不进会话表
login_id	否	绑到用户；类型默认登录标识
time	否	毫秒。相差超过 72 小时时改用服务器当前时间并告警，默认不拒绝
properties	否	键最长 50；值可以是字符串（最长 1000）、数字、布尔或空

访问记录每条要有 ua 和 url，可选 ts、ip、method、status、responseTime、referrer。日志导入的 lines 最多 5000 行，每行最长 4000 字符。

默认与限制

业务事件和访问记录每次最多 1000 条，日志导入最多 5000 行；超出的请求在校验时整体被拒绝，不会悄悄截断。不带 session_id 的业务事件留在事件表，不制造新会话。debug=1 只校验。平台缺省记为服务端。

示例

业务事件的最小请求见 服务端事件快速入门。访问记录：

curl -X POST "https://YOUR_ORIGIN/api/v1/server/events" \
  -H "Authorization: Bearer wck_…" \
  -H "Content-Type: application/json" \
  -d '{"events":[{"ua":"Mozilla/5.0 (compatible; ExampleBot/1.0)","url":"https://example.com/"}]}'

错误

密钥缺失、无效或权限不足返回 401。普通浏览器标识打到访问记录接口时会被当成人类跳过，报表里看不到。更新事件却没有 insert_id 会被拒绝。