文档目录

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
google 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 事件的回传见转化。