文档

Facebook / Meta

Orbitra 有两套相互独立的 Facebook 集成。它们解决同一个闭环中相反的两半,配置位置也不同:

作用方向位置
Facebook Costs把 Meta 的广告花费导入追踪器Meta → OrbitraIntegrations → Facebook Costs
Facebook Conversions API把追踪器的转化发送给 MetaOrbitra → MetaIntegrations → 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}}

关键规则:

Orbitra 通过共享的 core/ClickParams.php 采集器捕获这些参数。它捕获 fbclid 和可用的 _fbp / _fbc 值;浏览器追踪还会收集初始请求之后创建的 cookie。广告 URL 宏不会创建 fbp 浏览器标识。外部落地页、同意与跨渠道身份见浏览器匹配与同意。


2. Facebook Costs

获取访问令牌

带 ads_read 权限的长期 User Access Token 或 System User Token 都可以。生产环境应当用 System User token — 它不会随个人会话过期。

  1. <https://business.facebook.com/settings/system-users> → 添加一个系统用户
  2. 把广告账户分配给它,权限选 View performance(或完全控制)
  3. 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 IDact_1234567890
Facebook API version默认为支持的最新版本;老账户可以固定用旧版本
Proxy可选,格式 scheme://user:pass@host:port,也接受 socks5://
Update spend everycron 每隔多久重读一次花费
Advanced: parameter mapping仅用于经 App 中转的流量 — 见下文

每个账户行显示状态和下次更新时间,并带有 Update spend(立即手动同步一次)、Pause/Resume、Clone 和 Delete。

Test connection 读取的是广告账户本身(名称、币种、时区、状态),而不是 insights 报表 — 空报表也是有效答案,否则一个失效的 token 会被掩盖。

同步什么,什么时候同步

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 按从最具体到最宽的层级找出它所属的点击:

  1. ad_id(也可写作 creative_id、creative)
  2. adset_id(也可写作 adgroup、adgroupid、ad_group_id)
  3. 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 转发:

  1. 在 Facebook:sub_id_3={{adset.id}}
  2. 从应用传给 Orbitra:sub_id_3={sub_id_3}
  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 原样返回的。常见的有:

日期边界看起来错位 — 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 事件
leadLead
salePurchase
depositPurchase
registrationCompleteRegistration
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.phpMarketing API insights 读取器
core/CostImporter.phpupsert + 归因 + 币种
core/CurrencyRates.php汇率表、缓存、手动覆盖
core/ClickParams.php点击上捕获哪些参数
core/FacebookConversions.phpCAPI 载荷、哈希、入队
postback.php转化发生时把 CAPI 事件入队
postback_queue_cron.php带重试地投递它们
tests/facebook_integration_test.php端到端覆盖,不访问网络
← 上一篇
Push 与 Pop 联盟
下一篇 →
Dolphin / Fbtool
在 GitHub 上查看源码: github.com/fenjo26/Orbitra.link/wiki
全部教程
文档

快速上手

从裸机服务器到第一条转化的九个步骤:安装、首次登录、域名、联盟与 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 密钥安全。

阅读教程 →