怎么从服务端上报事件？

简短回答

创建一个带 服务端 Track 权限的 API 密钥，然后在后端用服务端 SDK（Node.js、PHP、Python、Java、Go）或直接调用 POST /api/v1/track 发送事件。每笔订单或支付都带上 insert_id，重试时就不会重复计数。

什么事件该从服务端发

需要准确计数的都该从服务端发：购买、支付、退款、订阅变更、以数据库为准的注册。这些事件在浏览器里可能因为拦截插件、页面关闭，或支付在另一个域名完成而丢失。浏览量继续用网站脚本采集，避免重复。背景见服务端追踪。

1. 创建密钥

所有者或管理员打开 配置 › 设置 › API 密钥，创建密钥并勾选「服务端 Track」。密钥以 wck_ 开头，只在创建时显示一次。把它放进环境变量或密钥管理服务，不要写进代码仓库，也不要放到浏览器或 App 里。

2. 发送事件

用 Node.js SDK：

npm install @tapcub/node

import { TapCub } from '@tapcub/node';

const tc = new TapCub({ apiKey: process.env.TAPCUB_API_KEY });

tc.track('purchase', {
  loginId: user.id,
  insertId: order.id,
  properties: { revenue: 19.9, currency: 'USD' },
});

SDK 会把事件排队，每 3 秒或攒满 200 条发送一次；遇到网络错误、5xx 和 429 最多重试 5 次。在 Serverless 函数里，返回前先 await tc.flush()。

不用 SDK 时，把密钥放在 Authorization 请求头里，发送 JSON：

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_123","insert_id":"order-1001","properties":{"revenue":19.9}}]}'

一次请求带 1 到 1,000 个事件。time 用毫秒；和服务器时间相差超过 72 小时，会被改成当前时间，并在返回里给出警告。

3. 避免重复计数

把 insert_id（不超过 36 个字符）设成订单号、支付单号这类天然唯一的键，重试时保持不变。服务端保留带这个 ID 的第一条事件。SDK 不会替你生成它。

4. 把事件和访问、来源关联起来

• 会话：不带 session_id 的事件会被存下来并计数，但不计入会话指标。想让这笔购买算在那次访问里，就传那次访问的会话 ID。
• 注册来源：网站脚本开启 data-attribution 后，tapcub.getAttribution() 会返回访客是怎么来的。随注册表单一起发给后端，在 trackSignup 里作为 context.campaign 原样传入，同时带上请求的 IP 和 User-Agent。
• 邮箱和手机号：身份标识在存储前会做哈希；用 bind 发送，不要当普通属性传。

5. 核对

联调时用调试模式（SDK 里设 consumer: 'debug'，或加 ?debug=1）：服务端逐条校验，但不存储。之后发一条真实事件，在 全端分析 › 数据管理 › 事件与属性 或 网站统计 › 事件 里找到它。

常见问题

还没装网站脚本？见安装 TapCub。

相关阅读

• 怎么导入服务器访问日志？
• 用 HTTP API 发送事件
• 创建 API 密钥