怎么用 HTTP API 发送事件？

简短回答

向 https://api.pathclue.com/api/v1/track 发 POST，在 Authorization: Bearer 请求头里放一个带「服务端 Track」权限的密钥，请求体是 {"events": [ … ]}，一次 1 到 1,000 个事件。接入期间加上 ?debug=1：服务端会校验每个事件并逐条返回结果，但不入库。

没有你所用语言的服务端 SDK，或者要从网关、任务调度器发送时，用 HTTP API。如果你的技术栈有 SDK（Node.js、Python、PHP、Java、Go），优先用 SDK：它已经处理了批量、重试和刷新。见从服务端发送事件。

开始之前

• 创建一个带「服务端 Track」（track:write）权限的项目 API 密钥：创建和管理 API 密钥。
• 密钥只放在服务端，比如环境变量 TAPCUB_API_KEY。
• 页面浏览继续交给网站脚本。HTTP API 用来发业务事件（订单、付款、注册）和用户档案更新，不用来发浏览。

发送头一个事件

curl -X POST "https://api.pathclue.com/api/v1/track?debug=1" \
  -H "Authorization: Bearer $TAPCUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "type": "track",
      "event": "purchase",
      "login_id": "u_1001",
      "insert_id": "ord_1001",
      "time": 1759363200123,
      "properties": { "revenue": 19.9, "currency": "USD" },
      "context": { "platform": "server" }
    }]
  }'

调试模式的响应带 debug: true，results 里每个事件一条，附带警告。没有问题后去掉 ?debug=1 再发一次。事件会出现在 全端分析 › 数据 › 事件与属性。

事件字段

事件类型

例子：一个请求里同时更新档案、绑定邮箱。

{ "events": [
  { "type": "profile_set", "login_id": "u_1001", "properties": { "plan": "pro", "$name": "Ada" } },
  { "type": "bind", "login_id": "u_1001", "identities": { "email": "ada@example.com" } }
] }

邮箱或手机号如果不是 64 位十六进制的哈希值，服务端会先哈希再存储，这一条会返回警告 plaintext_identity_hashed。想完全不发送明文，就自己先做 SHA-256。

读懂响应

成功的调用返回 received、accepted、rejected、events（进入缓冲的行数）和 results。非调试模式下，results 只列出失败或有警告的条目：index 是它在 events 里的位置，ok: false 表示这一条没有入库。同一请求里的其他条目照常接收。

在地址参数里加 validation_behavior=enforce，任何产生警告的条目都会被拒绝，比如用来确保明文邮箱永远不会被接收。

错误、限制和重试

重试规则：每次重试都保持同一个 insert_id，避免重复计数；指数退避，限制重试次数；尽量批量发送（每次最多 1,000 个事件），不要一个事件发一次请求。

相关

• 从服务端发送事件
• 创建和管理 API 密钥
• 服务端追踪