Facebook / Meta
Orbitra 有两套相互独立的 Facebook 集成。它们解决同一个闭环中相反的两半,配置位置也不同:
| 作用 | 方向 | 位置 | |
|---|---|---|---|
| Facebook Costs | 把 Meta 的广告花费导入追踪器 | Meta → Orbitra | Integrations → Facebook Costs |
| Facebook Conversions API | 把追踪器的转化发送给 Meta | Orbitra → Meta | Integrations → Facebook Conversions |
两者也能从底层数据所在的位置进入:花费连接显示在 Aggregators 页面(它们是 engine 为 facebook 的 aggregator_connections 行),活动的像素可以从活动自己的 Integrations 标签页编辑。无论从哪里进去,数据都一样 — Integrations 页是入口,另外两处是特定场景下的视图。
两者互不依赖。花费导入给你真实的 ROI;Conversions API 把浏览器像素丢掉的事件补给 Meta 的优化系统。
1. 活动设置(两套集成共同的前提)
两套集成都依赖广告带进追踪器的参数。活动设置一次,两套同时生效。
创建活动,选择 Facebook 流量来源模板,并把生成的 URL 参数填进广告的 URL parameters 字段:
ad_id={{ad.id}}&adset_id={{adset.id}}&campaign_id={{campaign.id}}&ad_name={{ad.name}}&adset_name={{adset.name}}&campaign_name={{campaign.name}}&site={{site_source_name}}
关键规则:
{{adset.id}}不是可选项。 当点击上没有广告 ID 时(例如 Advantage+ 下创意轮换),花费导入靠它兜底。- 不要添加
fbclid={fbclid}。fbclid由 Meta 自己附加。把它声明成宏会产生一个空值并覆盖真实值,Conversions API 随之失去匹配依据。 - 如果流量经过会重新打包宏的应用或 prelander,把它们以
sub_id_N转发,并告诉花费连接它们落在了哪里 — 见经由 App 的流量。
Orbitra 通过共享的 core/ClickParams.php 采集器捕获这些参数。它捕获 fbclid 和可用的 _fbp / _fbc 值;浏览器追踪还会收集初始请求之后创建的 cookie。广告 URL 宏不会创建 fbp 浏览器标识。外部落地页、同意与跨渠道身份见浏览器匹配与同意。
2. Facebook Costs
获取访问令牌
带 ads_read 权限的长期 User Access Token 或 System User Token 都可以。生产环境应当用 System User token — 它不会随个人会话过期。
- <https://business.facebook.com/settings/system-users> → 添加一个系统用户
- 把广告账户分配给它,权限选 View performance(或完全控制)
- Generate token → 选择你的应用 → 勾选
ads_read→ 复制
token 只显示一次。关掉弹窗前先保存好。
广告账户 ID
在 Ads Manager 里 — 即 act_1234567890 这个值。Orbitra 接受带或不带 act_ 前缀两种写法。
创建连接
Integrations → Facebook Costs → Add account:
| 字段 | 说明 |
|---|---|
| Access Token | 长期 token 或 system user token |
| Ad Account ID | act_1234567890 |
| Facebook API version | 默认为支持的最新版本;老账户可以固定用旧版本 |
| Proxy | 可选,格式 scheme://user:pass@host:port,也接受 socks5:// |
| Update spend every | cron 每隔多久重读一次花费 |
| Advanced: parameter mapping | 仅用于经 App 中转的流量 — 见下文 |
每个账户行显示状态和下次更新时间,并带有 Update spend(立即手动同步一次)、Pause/Resume、Clone 和 Delete。
Test connection 读取的是广告账户本身(名称、币种、时区、状态),而不是 insights 报表 — 空报表也是有效答案,否则一个失效的 token 会被掩盖。
同步什么,什么时候同步
- 定时同步(
aggregator_cron.php)每轮重读最近 5 天,连接首次同步时读 30 天。 - 广告平台会追溯修订历史:花费延迟归因,当天的数字是全天不断增长的累计值。因此记录按
(connection_id, external_id)做 upsert,归因重新计算、绝不累加 — 同一天重复同步是安全且幂等的。 - 花费按广告层级以
time_increment=1拉取,所以每行是某一天某一条广告的数据。
Cron — 小时以下的同步间隔(20/30 分钟)需要 cron 本身每几分钟跑一次;到期检查按连接逐个进行,跑得频繁也不费资源:
*/5 * * * * php /var/www/orbitra/aggregator_cron.php >> /var/log/orbitra_aggregator.log 2>&1
常用参数:--force(忽略周期)、--connection=5、--days=30。
花费如何落到点击上
对每条导入的记录,Orbitra 按从最具体到最宽的层级找出它所属的点击:
ad_id(也可写作creative_id、creative)adset_id(也可写作adgroup、adgroupid、ad_group_id)campaign_id(也可写作campaign、campaignid、ad_campaign_id)
当天的花费随后在当天匹配到的点击之间平均分摊 — 与手动录入花费用的是同一个平摊 CPC 模型。
币种
Meta 按广告账户的币种出数。Orbitra 在存储前换算成追踪器币种(Settings → currency),因此花费和收入永远在同一单位下。汇率从 open.er-api.com 获取并缓存 12 小时。
想自己固定汇率(离线安装,或想用你银行的牌价),设置 fx_rates_manual_json — 取值为每 1 美元兑多少:
{"EUR": 0.92, "RUB": 92.5}
手动汇率永远优先于拉取的汇率表。平台的原始金额和币种保存在 cost_records.raw_json 的 _orbitra 字段下,汇率错了事后可以还原。
经由 App 的流量
如果宏到达时已被重新打包 — Facebook → app → Orbitra — 就以 sub ID 转发:
- 在 Facebook:
sub_id_3={{adset.id}} - 从应用传给 Orbitra:
sub_id_3={sub_id_3} - 在账户的 Advanced: parameter mapping 里,把 Adset ID arrives in parameter 设为
sub_id_3
ad_id_param 和 campaign_id_param 用法相同。覆盖键先试,标准键兜底,因此部分映射只会降级,而不会导致什么都匹配不上。
排错
"Fetched N, matched 0"(拉到 N 条,匹配 0 条) — 花费到了,但没有一条能挂到点击上。cron 日志会明确写出这一点。几乎总是活动 URL 缺少 ad_id / adset_id / campaign_id。到 ⚙ → Logs → Traffic 查看最近一条点击的参数。
账户行上的 Update spend 会给出确切原因(no_spend、no_clicks、no_ids、macros、ids_differ),并附日期和两侧的 ID — 见 Costs。未匹配的行每次同步都会重试。
同步报错并附带 Meta 消息 — 消息是 Meta 原样返回的。常见的有:
- code 190 — token 过期或被吊销。重新签发。
- code 100,"(#100) ... field" — API 版本不再支持某个字段。把连接换到更新的版本。
- code 17 / 613 — 触发限流。调大同步间隔。
- 响应为空或被拦截 — Meta 正在按地区/IP 过滤追踪器的服务器。给连接配置代理。
日期边界看起来错位 — Meta 按广告账户时区出日报,追踪器按服务器时间存点击。两者不一致时,临近午夜的花费会落到相邻的一天。把广告账户时区与服务器对齐,或接受这个边缘误差。
3. Facebook Conversions API
相当一部分流量上浏览器像素是被拦截的 — 广告拦截器、ITP、iOS。联盟一回调 postback,Orbitra 立刻知道每一笔转化,并且掌握点击的 IP、user agent、fbclid 和 _fbp。在服务端发送事件,就能补回像素丢掉的部分。
获取 Conversions API token
Events Manager → 你的像素 → Settings → Conversions API → Generate access token。立刻复制;它只显示一次。
Pixel ID 在同一页面上(Events Manager → Data sources)。
配置
Integrations → Facebook Conversions → Add account(或在活动内部,从它自己的 Integrations 标签页 → Facebook Pixel — 同一条记录):
| 字段 | 说明 |
|---|---|
| Campaign | 该像素接收哪个活动的转化 |
| Pixel ID | 来自 Events Manager |
| Conversions API token | 服务端发送靠它开启 |
| Status → Meta event | 哪个追踪器状态产生哪个 Meta 事件 |
| Test event code | 可选,来自 Events Manager → Test events |
| Proxy | 可选,格式与花费连接相同 |
| Event source URL | 事件实际发生的页面;网站类事件 Meta 必填 |
没有 token 的像素行保持纯浏览器模式 — 列表会把它标记为 Browser pixel only,而不是当成可用的集成展示。没有 token 之前,服务端什么都不发送。
默认映射:
| 追踪器状态 | Meta 事件 |
|---|---|
lead | Lead |
sale | Purchase |
deposit | Purchase |
registration | CompleteRegistration |
rejected | 不发送 |
trash | 不发送 |
rejected 和 trash 是有意不映射的:把被拒的 lead 当成转化喂回去,会教优化系统买来更多恰恰错误的流量。
Send test event 立即发送一条事件,优先用你最近一条带 fbclid 的真实点击。到 Events Manager → Test events 下查看。
发送的内容
event_name from the mapping
event_time when the postback arrived
event_id <click_id>_<status>[_<tid>] ← reuse as browser eventID if sending both channels
action_source website
event_source_url configured event URL, or actual URL supplied with the postback
user_data
client_ip_address the click's IP (unhashed — Meta requires this)
client_user_agent the click's user agent (unhashed — Meta requires this)
fbc from _fbc, or rebuilt from fbclid
fbp from the _fbp cookie
external_id SHA-256 of the visitor's captured meta_external_id
em, ph, fn, ln SHA-256, from the postback
ct, st, zp, country SHA-256, from the click's geo
custom_data
value, currency from the postback payout
IP、user agent、fbc 和 fbp 不加哈希直接发送。个人匹配字段和访客的 Meta external ID 做哈希。旧版 external_id 追踪参数保持不变:对其他流量来源它可能指广告点击,因此不会自动复用为 Meta 访客身份。
事件 URL 不是引流 referrer
在集成里配置真实的结账/感谢页 URL,或让合作方在 postback 里附带 URL 编码的 event_source_url。显式配置的 URL 优先。配置宏 {campaign_url}、{landing_url} 和 {clickid} 仍然可用,但只在它们确实描述该事件所在页面时使用。{landing_url} 使用捕获到的落地页上下文(或保存的落地页 URL),绝不是点击的 Facebook/Google 引流 referrer。
对于发生在不同页面的事件,活动的 Event source URL 文本框还接受一个高级 JSON 映射,以最终的 Meta 事件名为键:
{"InitiateCheckout":"{campaign_url}","Purchase":"{offer_url}"}
这是显式配置,不是对你漏斗的默认推断。只有当发起结账发生在活动页、而购买在所选 offer 的 URL 完成时,才照抄这个示例。映射里缺键时允许使用集成里显式配置的 URL;键存在但为空/非法时不会替换成其他页面。URL 的选择永远不会禁用事件本身。普通 URL 设置和现有宏的行为保持不变。
{offer_url} 通过现有的 offer/联盟参数和点击宏规则,解析该点击持久化记录中选中的 offer。它不会挑活动里的第一个 offer、不跟随重定向、也不会去发现第三方的确认页。它使用 postback 到达时刻的 offer 配置,而不是历史快照:转化尚未到齐时请保持 offer 配置稳定,或者干脆不配置该事件、改为通过集成提供真实 URL。当 offer 重定向到另一个发生事件的页面时,不要使用它。
这份高级映射是活动级设置;Pixel Vault 的 URL 字段仍然接受普通 URL。按照既有的配置同步行为,保存关联的中央配置文件会覆盖活动的 URL 覆盖项,因此编辑配置文件之后请复查这些覆盖项。手动测试端点不提供活动/offer 宏上下文;做有代表性的手动测试时请直接给显式真实 URL,不要指望它自己发现结账页。
Orbitra 不会从你的落地页猜测联盟的结账 URL。如果没有任何有效 URL,它会记录一条配置警告并省略该字段,保留已入队的意图和 Meta 的投递结果。升级之前,依赖旧版 referrer 兜底的集成需要一个真实的事件 URL:网站类事件 Meta 必填此字段,缺失时可能拒绝请求。不要拿访客从未用过的页面顶替。浏览器端 reportConversion() 会带上当前页面;当集成掌握更准确的信息时,显式提供的 event_source_url 可以覆盖它。
浏览器匹配与同意
原生落地页/offer 路径以及当前的 tracking.js、kclient.js 和 PHP KClient 都支持共享的 meta-matching.js 采集器。它保留不透明的 cookie 值,包括 Parameter Builder 后缀。新的 fbclid 会替换过期的 fbc;同一点击的多次观测保留其时间戳。标识符不会被截断到通用的 512 字节追踪参数上限。
新的匹配 cookie/身份仅限于以下访问:挂有启用的 Facebook 活动像素、已有 fbclid/fbc/fbp 上下文,或显式 meta_matching=1。无关的活动不会因为升级了 Orbitra 就获得 Meta cookie。在符合条件的已保存浏览器访问上,如果启用了 cookie,采集器会复用 _fbp,缺失时一次性创建一个第一方浏览器 cookie。它还会把匿名 orbitra_visitor 身份保留 90 天。两者都不会在转化时刻生成。cookie 采集在早期执行,页面加载后、外发交互和页面退出时再次执行。一个带签名、限定点击范围的 POST 只能更新 fbp、fbc 和首次观测到的落地页 URL,不能更新访客身份、IP、User-Agent 或转化。这些更新只影响后续载荷,不影响已入队的事件。
外部落地页也要更新它们复制的客户端文件。PHP KClient 转发的是访客 IP/User-Agent 和浏览器 cookie,而不是托管服务器的身份;把 echo $client->matchingScript(); 放在落地页 <head> 靠前的位置,以便捕捉较晚出现的 cookie(timerScript() 也包含它)。落地页服务器上的可信代理处理要保持配置正确;不要信任任意转发的 IP。
这是对 Meta 文档化参数规则的一个聚焦实现,不是官方 Parameter Builder SDK 及其全部可选浏览器增强功能的安装。参见 Meta 的 Parameter Builder guidance 和 fbp/fbc specification。
采集器不是同意管理平台。运营者必须按自己的同意政策控制追踪。use_cookies=0 可禁用匹配采集器;来访访问带 meta_matching=0 时对该点击禁用。外部 JavaScript 集成在加载客户端之前设置 window.orbitra_meta_matching = false 即可退出;PHP 客户端可用 ->param('meta_matching', '0')。原生 HTML 注入使用延迟脚本:落地页在延迟脚本运行之前设置的内联同意标志可以禁用浏览器采集。它无法撤销 HTTP 响应里已经完成的服务端采集/cookie。不允许采集时,请在响应这次访问之前就使用服务端控制项。
在浏览器 Pixel 中复用访客 ID
采集器不安装也不触发 Meta Pixel。在你现有的、已获同意的 Pixel 配置里,在第一个真实浏览器事件之前传入同一个原始身份:
const visitorId = window.OrbitraMatching?.getExternalId();
if (visitorId) {
fbq('init', 'YOUR_PIXEL_ID', { external_id: visitorId });
}
// Your existing real Pixel events follow; do not initialize the same Pixel twice.
在客户端/采集器就绪之后使用,包括原生落地页上的延迟加载。PHP 集成可用 $client->getExternalId() 获取同一个原始值(嵌入 JavaScript 时用 json_encode)。Orbitra 会为 CAPI 对它哈希一次。不要用订单号替换它、不要再次哈希、也不要在 postback 里另造一个 ID。既有的点击/subid 关系会把它一路带到联盟转化;维持这层关系不需要 email 和电话。它仍需要真实的 Pixel/CAPI 关联才能帮助 Meta 匹配;只创建一个 ID 并不能保证匹配成功。Meta external ID guidance。
要发送 PII,把它加进入站 postback:
https://tracker.example/<postback_key>/postback?subid=3sh8so4er3&status=sale&payout=2.61&[email protected]&fn=John&ln=Snow&ph=+71234567890
取值先按 Meta 要求规范化(email 转小写、电话只留数字)再哈希 — 未规范化的哈希永远匹配不上。
投递与重试
转化、点击合计和符合条件的 CAPI 意图在同一个短 SQLite 事务里提交。队列写入失败会回滚该单元并返回错误(锁竞争耗尽时为 503),发送方因此可以重试。浏览器转化 GIF 会保留这些服务端错误,而不是伪装成 HTTP 200。通知和出站 S2S 的准备留在写事务之外。
重复的 postback 会复用同一转化、像素、事件名和事件 ID 对应的既有意图,包括已失败/已投递的行。不同的状态/事件或交易 ID 可以创建独立的事件。队列幂等性在原始投递行保留期间有效;清除日志会移除这段本地历史。这不是自动的浏览器端去重:同一个动作的 Pixel 必须使用相同的 eventID 和事件名。Schema migration 52 增加了带索引的查询和内部签名密钥表;它不会恢复或重放历史转化。
事件在 s2s_postbacks_log 里排队,由 postback_queue_cron.php 按指数退避投递 — 与出站 S2S postback 用的是同一个 worker。Meta 响应再慢也不会拖慢对联盟 postback 的应答。发送方超时可以重试;重复的入站请求会复用既有的 CAPI 意图,而不是把同一事件再入队一次。
* * * * * php /var/www/orbitra/postback_queue_cron.php >> /var/log/orbitra_postback_queue.log 2>&1
投递状态、HTTP 码和脱敏后的失败详情在 S2S 日志界面可见。现有的 response 列(logs API 同样返回)现在存储有界、脱敏的 events_received、警告/消息以及 fbtrace_id(如有提供)。它不再保存任意原始响应体或回显的凭据。
对 Meta 而言,delivered 现在要求 HTTP 2xx、无 API 错误的 JSON 对象,以及确认收全请求的 events_received。含糊的响应和瞬时错误沿用现有的有界退避;永久性的认证或校验错误直接失败,不做无谓重试。手动测试按钮使用同样的校验。通用 S2S 和 TikTok 的传输规则不变。
已记录、已入队、Meta 已确认和已归因到广告是不同的阶段。API 确认响应不等于单笔活动归因的证明,也不保证 Ads Manager 立刻出报表。
排错
Events Manager 里什么都没到 — 按顺序检查:点击是否带有 fbclid(⚙ → Logs → Traffic);广告 URL 参数里没有 fbclid={fbclid};状态是否映射到了事件;队列 worker 的 cron 是否在跑;S2S 日志里是否能看到这次尝试。
Meta 返回 "Invalid parameter" — 通常是像素 ID 和 token 属于不同资产,或 token 是为你已不再拥有的像素生成的。
事件到了但匹配质量低 — 检查捕获到的 fbp/fbc、真实访客 IP/User-Agent、同意状态,以及同一外部身份是否到达了浏览器 Pixel。缺 email/电话本身并不意味着事件被拒。跨域 cookie 无法从另一个站点的请求里读到:在那个域名上用外部落地页客户端。立即重定向、没有浏览器代码执行时,只能捕获已经可用的标识符。
文件
| 路径 | 作用 |
|---|---|
aggregator_engines/FacebookAdsEngine.php | Marketing API insights 读取器 |
core/CostImporter.php | upsert + 归因 + 币种 |
core/CurrencyRates.php | 汇率表、缓存、手动覆盖 |
core/ClickParams.php | 点击上捕获哪些参数 |
core/FacebookConversions.php | CAPI 载荷、哈希、入队 |
postback.php | 转化发生时把 CAPI 事件入队 |
postback_queue_cron.php | 带重试地投递它们 |
tests/facebook_integration_test.php | 端到端覆盖,不访问网络 |
快速上手
从裸机服务器到第一条转化的九个步骤:安装、首次登录、域名、联盟与 offer、流量来源、广告系列、验证、消耗与统计。
阅读教程 →文档安装与更新
系统要求、一条命令的安装器、PHP 更新与安全公告、按 IP 访问后台、更新完整性校验,以及本地开发环境。
阅读教程 →文档从 Keitaro 迁移
通过 SQL dump 把设置从 Keitaro 迁到 Orbitra:迁移内容清单、导出脚本、导入步骤,以及导入后要检查的事项。
阅读教程 →文档从 Binom 迁移
通过 Binom v2 Public API 直接导入广告系列、offer、流等设置 — 无需 dump 文件,附字段映射说明。
阅读教程 →文档功能总览
所有功能一览:流量与方案、postback 与消耗、数据分析、基础设施与管理 — 每项都链接到详细页面,并附各版本的新增内容。
阅读教程 →文档广告系列与流
广告系列编辑器详解:设置标签页、计费模式、流类型与全部过滤器、方案、自动优化轮询、测试链接与重复点击防护。
阅读教程 →文档斗篷(参考文档)
斗篷完整参考:流设置、检测层、灵敏度、定向过滤器、JavaScript 验证、全局设置、判定结果与原因代码及诊断方法。
阅读教程 →文档浏览器检查
通过浏览器自报矛盾识别机器人、审核员虚拟机、模拟器和反检测浏览器:四种模式、特征清单、结果查看与安全启用步骤。
阅读教程 →文档落地页(参考文档)
落地页完整参考:本地、跳转、Preload 与 Action 四种类型,{offer} 宏、subid 传递、停留时长、JS adapter、PHP 落地页与故障排查。
阅读教程 →文档PWA 与 Web Push
PWA 落地页与自建 Web Push:构建器、域名绑定、VAPID 密钥、订阅者、消息与发送 cron、转化归因和故障排查。
阅读教程 →文档PWA 漏斗
PWA 落地页内的可配置漏斗:store/screen/instructions/push 步骤类型、逐屏追踪、统计维度与编辑器用法。
阅读教程 →文档转化弹窗(Conversion Popups)
在落地页上展示带 offer 按钮的弹窗:适用场景、Popup 标签页设置、触发条件与统计指标。
阅读教程 →文档会话录制与热力图
像视频一样回放真实访问,配合点击热力图与滚动图;含整站录制、Cookie 同意、存储上限与隐私说明。
阅读教程 →文档素材库完整参考
Gallery 页面、上传与软删除、MediaPicker 的尺寸契约(sizeContract)、格式与大小限制,以及视频支持。
阅读教程 →文档创意库
平台同步的创意与手动上传的草稿统一存放,自动绑定花费/收入/ROI,找出真正赚钱的创意。
阅读教程 →文档外部 PWA 与 Telegram 频道
把第三方 PWA 构建器接入流做 A/B,并把 Telegram 频道当作可归因的 offer 目的地。
阅读教程 →文档Postback 与转化
入站 postback 参数与状态映射、转化类型、出站 S2S postback、投递队列与测试器、转化导入和 Conversions API。
阅读教程 →文档花费(Costs)
从 Facebook、TikTok、Google Ads 和 push/pop 联盟导入花费并分摊到点击;含收入聚合器、代理佣金与排错。
阅读教程 →文档Push 与 Pop 联盟
接入 push/pop 联盟的花费导入与 zone 级优化:支持联盟列表、匹配规则与 Zone Killer 屏蔽烧钱 zone。
阅读教程 →文档Facebook / Meta
两套独立集成:从 Meta 导入广告花费,以及用 Conversions API 服务端发送转化事件,含浏览器匹配与排错。
阅读教程 →文档Dolphin / Fbtool
通过 Dolphin(Fbtool)API 实时接收 Facebook 消耗:兼容 Keitaro 的入站端点、API 密钥与活动参数配置、消耗分摊与验证。
阅读教程 →文档FB 评论清理器
按计划批量审核 Facebook 广告贴下的评论:停用词、正则、链接与联系方式规则,默认 dry-run、默认隐藏、操作可恢复。
阅读教程 →文档流量来源与联盟
配置漏斗两端的两个目录:约 200 个流量来源模板与约 440 个联盟模板,参数三元组、postback URL 与 offer 参数宏。
阅读教程 →文档报表、日志与指标
仪表盘、报表生成器、趋势与群组、流量日志与点击卡片,以及每个指标的计算方式。
阅读教程 →文档域名与 SSL
添加域名、把 DNS 指向服务器、自动签发 Let's Encrypt 证书,以及 Domains 页面上每个开关的作用。
阅读教程 →文档Cloudflare
通过 API 接入 Cloudflare:域名自动停放 A 记录、多账号、代理(橙色云朵)与 Flexible / Full / Strict SSL 模式。
阅读教程 →文档管理
用户、角色与按资源授权、两步验证、API 密钥、安全设置、geo 数据库、面板更新与系统状态。
阅读教程 →文档Telegram 机器人
在 Telegram 里管理追踪器:转化通知、每日摘要、统计命令,以及发到频道/群组的转化提醒。
阅读教程 →文档MCP:追踪器里的 AI 助手
把 Claude 或任何 MCP 客户端连上 Orbitra,用大白话管理广告系列:41 个工具、远程与本地两种连接方式、API 密钥安全。
阅读教程 →