订单、支付、退款、注册这类事件应该在你的服务端上报,浏览器拦截不了,也伪造不了。五个服务端 SDK 都封装 POST /api/v1/track,各语言方法相同、行为一致。日志式的 POST /api/v1/server/events 是另一条接口,这些 SDK 不会调用它,见 服务端事件。
共同行为
密钥与地址
在 控制台配置设置API 密钥 创建密钥,勾选 服务端 Track。密钥以 wck_ 开头,只在创建时显示一次;放在服务端配置里,不要写进代码仓库,也不要放到浏览器或 App 里。收数地址已内置在 SDK 里,不用设置地址选项;只有 TapCub 给你专用地址时(例如私有部署)才需要填。
方法
| 方法 | 记录什么 |
|---|---|
track | 业务事件,可带登录 ID、设备 ID、会话 ID、幂等键、时间、账户和请求上下文 |
trackSignup | 注册事件 sign_up,把匿名设备关联到新的登录 ID;invitedBy 写成 $invited_by |
bind / unbind | 增加或移除身份(邮箱、手机号、unionid、openid、自定义);邮箱和手机号在 SDK 里先做 SHA-256 |
profileSet / profileSetOnce / profileIncrement / profileAppend / profileUnset | 用户属性;$name、$email、$phone、$avatar 是显示字段 |
itemSet / itemDelete | 维度表,例如商品、文章、门店 |
trackUpdate / trackOverwrite | 合并或替换同一 insertId 的已入库事件属性 |
groupSet | 账户 type:id 的属性;事件用 group 参数归到账户 |
flush / close | 立即发送队列 / 停止并发送剩下的 |
Python 用下划线写法(track_signup、profile_set),Go 用导出名(TrackSignup)。字段规则见 SDK 总览与支持矩阵。
发送方式
| 方式 | 行为 |
|---|---|
| batch | 除 PHP 外的默认方式。事件先进内存队列,每 3 秒或攒满 200 条发送一次,单次最多 1000 条、1 MB;内存里最多留 10,000 条,超出丢最早的并报 QUEUE_FULL |
| sync | PHP 的默认方式。每次调用立即发送,失败时抛错 |
| debug | 同 sync,但请求 ?debug=1:服务端逐条校验并返回结果,不入库。接入时使用 |
网络错误、5xx、429 最多重试 5 次,指数退避(0.5 秒起翻倍,最长 30 秒),并遵守 Retry-After;重试时整批原样重发。其他 4xx 不重试。batch 方式下,放弃重试的失败、以及成功响应里被拒绝的事件交给错误回调;flush 和 close 则直接抛出第一个错误。
幂等
SDK 不会自动生成 insertId。不能重复计数的事件,请传不超过 36 个字符的自然键,例如订单号或支付流水号,你自己的代码重试时也保持不变。服务端对同一 insertId 只保留一条事件。
发送前清洗
只要有一条事件不符合字段规则,服务端会拒绝整个请求,所以每个 SDK 在入队前都会清洗:超过 1000 个字符的字符串截断,嵌套对象转成 JSON 字符串,items 这类对象数组保留一层,未知的上下文字段和非法值丢弃。ID 不会被截断:ID 过长、登录类型未知、账户键格式不对都按参数错误处理,不入队。五个 SDK 跑同一组一致性用例(SDK 仓库的 packages/shared/test-vectors/track)。
记录注册来源
网站脚本知道访客从哪里来,tapcub.getAttribution() 返回这份来源。注册表单提交时把这个对象一起带到后端,原样放进 context.campaign,同时带上请求的 ip 和 user_agent,没有 Cookie 时 TapCub 用它们推断来源。下面各语言都有示例。
错误
| 错误码 | 含义 |
|---|---|
NO_API_KEY / BAD_API_KEY | 401:没带密钥、密钥无效或过期,或没有 服务端 Track 权限 |
VALIDATION | 400:请求体不符合字段规则,消息里列出前几处问题 |
HTTP_<status> | 其他失败状态码 |
NETWORK | 重试完仍没有响应 |
EVENT_REJECTED | 请求成功,但部分事件被拒绝,例如给不存在的用户设属性;附带逐条警告 |
QUEUE_FULL | 内存队列溢出,丢弃了最早的事件 |
每个错误都带着没入库的事件。发送成功只代表服务端收下了;第一次接入请到事件列表确认,见 服务端事件与日志导入。
Node.js
需要 Node.js 18 及以上,无依赖,同时提供 ESM、CommonJS 和类型。
安装
npm install @tapcub/node初始化
import { TapCub } from '@tapcub/node';
const tc = new TapCub({
apiKey: process.env.TAPCUB_API_KEY,
onError: (err) => console.warn(err.code, err.message),
});可选项:endpoint、consumer('batch' / 'sync' / 'debug')、maxBatch、flushIntervalMs、maxQueueSize、maxRetries、timeoutMs、gzip、onError、logger、fetch。
事件
tc.track('purchase', {
loginId: user.id,
insertId: order.id,
properties: { revenue: 19.9, currency: 'USD', items: [{ item_id: 'sku-1', price: 19.9, quantity: 1 }] },
});方法返回 Promise,batch 方式下立即完成。参数错误抛 TypeError。
身份
tc.trackSignup(user.id, {
deviceId: req.body.tapcubDeviceId,
invitedBy: req.body.inviterId,
context: { campaign: req.body.attribution, ip: req.ip, user_agent: req.get('user-agent') },
});
tc.profileSet(user.id, { plan: 'pro', $name: user.name });
tc.bind(user.id, { email: user.email });退出
收到 SIGTERM 时调用 await tc.close();进程 beforeExit 时也会自动发送。在 Serverless 函数里,返回前 await tc.flush(),或者用 consumer: 'sync'。
PHP
需要 PHP 8.0 及以上,以及 ext-curl、ext-json。
安装
composer require tapcub/tapcub-php初始化
use TapCub\TapCub;
$tc = new TapCub(getenv('TAPCUB_API_KEY'));第二个参数是地址(传 null 用默认值),第三个参数是选项:consumer('sync' / 'batch' / 'debug')、maxBatch、maxQueueSize、maxRetries、timeout、gzip、onError、logger(PSR-3 风格)。
事件
$tc->track('purchase', [
'loginId' => $user->id,
'insertId' => $order->id,
'properties' => ['revenue' => 19.9, 'currency' => 'USD', 'items' => [['item_id' => 'sku-1', 'price' => 19.9, 'quantity' => 1]]],
]);sync 方式下每次调用返回服务端响应,失败抛 TapCubException(getErrorCode()、getStatus()、getEvents())。参数错误抛 InvalidArgumentException。空数组和数字键数组一律按 JSON 对象发送。
身份
$tc->trackSignup((string) $user->id, [
'deviceId' => $request->input('tapcubDeviceId'),
'invitedBy' => $request->input('inviterId'),
'context' => ['campaign' => $request->input('attribution'), 'ip' => $request->ip(), 'user_agent' => $request->userAgent()],
]);
$tc->profileSet((string) $user->id, ['plan' => 'pro', '$name' => $user->name]);批量发送
设置 'consumer' => 'batch' 后,事件在攒满 200 条、调用 flush() / close()、客户端被销毁或请求结束时发送,这时的失败交给 onError。队列任务和常驻进程(Octane、RoadRunner、Swoole)里,每个任务结束时调用 flush()。
Python
需要 Python 3.8 及以上,只用标准库,带类型标注。
安装
pip install tapcub初始化
from tapcub import TapCub
tc = TapCub(os.environ["TAPCUB_API_KEY"], on_error=lambda e: log.warning("%s %s", e.code, e))关键字参数:consumer("batch" / "sync" / "debug")、max_batch、flush_interval(秒)、max_queue_size、max_retries、timeout、gzip、on_error、logger。batch 方式由后台线程发送,解释器退出时自动发送剩余事件。
事件
tc.track(
"purchase",
login_id=user.id,
insert_id=order.id,
properties={"revenue": 19.9, "currency": "USD", "items": [{"item_id": "sku-1", "price": 19.9, "quantity": 1}]},
)time 可以是毫秒时间戳或 datetime。参数错误抛 ValueError;sync 方式下发送失败抛 TapCubError。
身份
tc.track_signup(
user.id,
device_id=data.get("tapcubDeviceId"),
invited_by=data.get("inviterId"),
context={"campaign": data.get("attribution"), "ip": request.META.get("REMOTE_ADDR"), "user_agent": request.headers.get("User-Agent")},
)
tc.profile_set(user.id, {"plan": "pro", "$name": user.name})任务进程
脚本、Lambda 函数和 Celery 任务返回前调用 tc.flush()。预先 fork 的服务(gunicorn --preload、uWSGI)要在 fork 之后再创建客户端,后台线程不会跟着 fork 过去。
Java
需要 Java 11 及以上,运行时无依赖。
安装
<dependency>
<groupId>com.tapcub</groupId>
<artifactId>tapcub-java</artifactId>
<version>0.1.0</version>
</dependency>Gradle:implementation("com.tapcub:tapcub-java:0.1.0")。
初始化
import com.tapcub.server.TapCub;
TapCub tc = TapCub.builder(System.getenv("TAPCUB_API_KEY"))
.onError(e -> log.warn("tapcub {} {}", e.getCode(), e.getMessage()))
.build();构建器选项:endpoint、mode(BATCH / SYNC / DEBUG)、maxBatch、flushInterval、maxQueueSize、maxRetries、timeout、gzip、flushOnShutdown、onError、logger、httpClient。客户端线程安全,实现了 AutoCloseable;Spring Boot 里声明成 Bean 并设 destroyMethod = "close"。
事件
tc.track("purchase", new TrackOptions()
.loginId(user.getId())
.insertId(order.getId())
.property("revenue", 19.9)
.property("items", List.of(Map.of("item_id", "sku-1", "price", 19.9, "quantity", 1))));参数错误抛 IllegalArgumentException;sync 方式下发送失败抛 TapCubException。
身份
tc.trackSignup(user.getId(), new SignupOptions()
.deviceId(form.getTapcubDeviceId())
.invitedBy(form.getInviterId())
.context(Map.of("campaign", form.getAttribution(), "ip", req.getRemoteAddr(), "user_agent", req.getHeader("User-Agent"))));
tc.profileSet(user.getId(), Map.of("plan", "pro", "$name", user.getName()));手里没有浏览器传来的来源对象时,可以用 Campaign 逐个字段构建。
Go
需要 Go 1.21 及以上,只用标准库。
安装
go get github.com/tapcub/tapcub-go初始化
tc, err := tapcub.New(os.Getenv("TAPCUB_API_KEY"), tapcub.Config{
OnError: func(err error) { log.Println(err) },
})
if err != nil {
log.Fatal(err)
}
defer tc.Close()tapcub.Config 字段:Endpoint、Consumer(ConsumerBatch / ConsumerSync / ConsumerDebug)、MaxBatch、FlushInterval、MaxQueueSize、MaxRetries、Timeout、Gzip、OnError、Logger、HTTPClient,零值可直接用。
事件
err := tc.Track("purchase", &tapcub.TrackOptions{
LoginID: user.ID,
InsertID: order.ID,
Properties: tapcub.Properties{"revenue": 19.9, "items": []tapcub.Properties{{"item_id": "sku-1", "price": 19.9, "quantity": 1}}},
})参数错误包装了 tapcub.ErrInvalidArgument;发送错误是 *tapcub.Error(Code、Status、Events)。
身份
err := tc.TrackSignup(user.ID, &tapcub.SignupOptions{
DeviceID: form.DeviceID,
InvitedBy: form.InviterID,
Context: &tapcub.Context{Campaign: form.Attribution, IP: clientIP(r), UserAgent: r.UserAgent()},
})
_ = tc.ProfileSet(user.ID, tapcub.Properties{"plan": "pro", "$name": user.Name})浏览器传来的来源 JSON 可以直接解码成 *tapcub.Campaign。