前端埋点会被广告拦截挡掉，也会因为用户关了页面而丢。订单、付款、退款、续费这类必须准确的事实，建议从你的服务器直接上报。
1. 创建 API 密钥
项目的所有者或管理员到「配置 › 设置 › API 密钥」新建一个密钥，权限勾选「服务端 Track」。密钥以 wck_ 开头，只在创建时显示一次，请马上存进你的密钥管理或环境变量。
不要把密钥写进前端代码、代码仓库或者文档。泄露了就在同一页作废，再建一个新的。
2. 发送事件
curl -X POST "https://api.pathclue.com/api/v1/track" \
-H "Authorization: Bearer wck_你的密钥" \
-H "Content-Type: application/json" \
-d '{"events":[{"event":"purchase","login_id":"u_1001","insert_id":"order-20261018-001","properties":{"revenue":199,"currency":"CNY","order_id":"20261018-001"}}]}'请求体是 { "events": [ … ] }，一次 1 到 1000 条。项目由密钥决定，不需要也不接受在参数里写项目编号。
常用字段
| 字段 | 必填 | 说明 |
|---|---|---|
event | 是 | 事件名，最长 100 字符，命名规则同前端 |
insert_id | 建议 | 幂等键，最长 36 字符。同一个键重发不会多出一行，先到的那条保留 |
login_id | 否 | 你系统里的用户编号，带上后事件会归到这个用户 |
session_id | 否 | 那次访问的会话标识。不带时事件只进事件表，不会被算成一次新访问 |
time | 否 | 毫秒时间戳。和服务器时间相差超过 72 小时时改用当前时间，并在结果里给出警告 |
properties | 否 | 属性，键最长 50；字符串值最长 1000，也可以是数字、布尔或空 |
几点建议：
- 一定带
insert_id，用订单号、支付流水号这类天然唯一的值。这样网络超时后可以放心重试，不会把一笔订单记成两笔。 - 电商报表默认把
purchase当购买、refund当退款，金额取revenue、币种取currency、订单号取order_id。用别的名字也可以，在「全端分析 › 配置 › 经营设置」的电商映射里改。 - 邮箱、手机号如果放在身份字段里，不是哈希值的会先自动哈希，结果里会标出警告。
3. 看返回结果
{ "received": 1, "accepted": 1, "rejected": 0, "events": 1, "results": [] }accepted：通过校验、写入缓冲的条数。rejected大于 0 时，results里会列出是第几条（index）和原因。同一批里的其他事件照常写入。- 返回 401：密钥不对、被作废，或者没有「服务端 Track」权限。
联调时在地址后面加 ?debug=1，接口只做校验、给出完整结果，不会真的入库。
4. 在报表里确认
到「全端分析 › 数据管理 › 事件与属性」或「网站统计 › 事件」查看。带了 login_id 的事件可以在对应用户的档案里看到。
和前端事件怎么配合
不要让同一件事前后端各报一次，否则会算两遍。推荐的分工：前端记意图（点了「立即购买」「提交订单」），服务器记结果（支付成功、退款完成）。这样漏斗里既有中间流失，金额又准。
另外两个接口
除了业务事件，还有两个接口专门用来补充机器人数据：提交网关访问记录、导入 Nginx / Apache 日志。它们只保留被识别为机器人的请求，不能用来记订单，用途见 机器人和 AI 爬虫是怎么识别的。