文档目录
Meta、TikTok 和 Google 的 CAPI
更新于 2026年11月17日
Velotrak 把已批准的转化从你在后台创建的集成发到 Meta、TikTok 或 Google。Free 每个平台一个 CAPI 账号。Pro、Team 和 Founder 不限制个数。CAPI 投递不受授权开关限制。
添加集成
创建一个 kind 为 capi 的集成。凭据在 PostgreSQL 里加密保存。列表接口不返回凭据。
| 平台 | 必须填写 | 发送端使用的地址 |
|---|---|---|
| meta | pixel_id(只能是数字)、token |
POST graph.facebook.com/v19.0/<pixel id>/events,token 在 JSON 正文里 |
| tiktok | pixel_id、token |
POST business-api.tiktok.com/open_api/v1.3/event/track/,请求头 Access-Token |
measurement_id(G- 开头)、api_secret |
POST www.google-analytics.com/mp/collect |
后台把 Meta 和 TikTok 的 token 标成「Access Token」,把 Google 的字段标成「Measurement ID」和「API Secret」。产品里没有测试事件代码字段。account_id 可选,默认取第一个凭据值。
Free 的上限是每个平台一个活动的 CAPI 账号。再创建或重新启用会被拒绝。Pro、Team 和 Founder 把这个上限存成 0,表示不限制。点击路径在所有套餐上都会投递 CAPI,包括 Free。定价页写的是同一件事:三个平台都有 CAPI,Free 每个平台一个账号。
发送哪些事件
只有没有异常的 approved 转化会入队。转化上的 goal 决定平台事件名:
| Goal | Meta | TikTok | Google(GA4) |
|---|---|---|---|
| sale | Purchase | CompletePayment | purchase |
| lead | Lead | SubmitForm | generate_lead |
| install | CompleteRegistration | CompleteRegistration | sign_up |
| subscribe | Subscribe | Subscribe | subscribe |
| 其他 | goal 原名 | goal 原名 | goal 原名 |
金额和货币是安装的主货币下的付款。Meta 还收到 IP、User-Agent,以及用点击上的 fbclid 拼出的 fbc(fb.1.<点击时间>.<fbclid>)。它不发送 fbp。TikTok 收到 IP、User-Agent,以及点击里有的 ttclid。Google Measurement Protocol 收到金额、货币和一个 client id。没有单独的 GA client id 时,发送端退回使用点击 ID。它不向 Google 发送 gclid、IP 或 User-Agent。浏览器脚本 /velotrak.js 用同一个事件 ID(点击 ID、goal 和平台的 SHA1)触发 fbq 和 ttq。它不触发 Google 浏览器标签。
哪一个集成收到事件:先看活动的 capi_account_id,否则看流量源模板的 capi_account_id,否则发给该平台上每一个活动的 CAPI 集成。官网把最后一种叫「broadcast」。
失败
出站队列对失败的发送最多重试 8 次,间隔为 1 分钟、5 分钟、30 分钟、2 小时和 6 小时,然后把任务标成 dead。HTTP 客户端超时 10 秒。超过 7 天的点击记为 expired,不再发送。集成已暂停或删除时,任务被丢弃。结果在出站日志(GET /api/logs/outbound),包括 failed、retrying、dead 和 expired。产生这条 approved 事件的回传见转化。