花费(Costs)
Orbitra 从广告账户拉取每日花费并分摊到点击上,因此报表里的 ROI 和利润按真实花费计算,而不是手工填的每点击成本。
连接在 ⚙ → Integrations 的广告网络分组里:Facebook Costs、TikTok Costs、Google Ads Costs。活动编辑器的 Integrations 标签页会显示活动的点击是否带有用于匹配的 ID,也可以在那里添加连接。
花费如何落到点击上
aggregator_cron.phpcron(安装器按每 15 分钟添加)遍历到达更新周期的连接。每一轮都重读最近 5 天,首轮读 30 天:广告账户会追溯修订花费,当天的数字要到午夜前一直增长。- 记录写入
cost_records,以(connection_id, external_id)为键做更新。同一天重复同步是安全的:花费重新计算,不会累加。 - 对每条记录,按从最具体到最宽的层级匹配当天的点击:
ad_id(也可写作creative_id、creative);adset_id/adgroup_id(也可写作adgroup、adgroupid、ad_group_id);campaign_id(也可写作campaign、campaignid、ad_campaign_id)。
- 当天的花费在匹配到的点击之间平均分摊。
- 花费换算成追踪器币种(汇率来自
open.er-api.com,缓存 12 小时;自定义汇率通过fx_rates_manual_json设置,取值为每 1 美元兑多少)。
核心要求: 广告链接必须把广告、广告组或广告系列的 ID 传进追踪器。最简单的办法是在活动里选一个模板流量来源(Facebook、TikTok、Google Ads)— 模板会自动加上所需的宏。
没匹配到点击的记录会在每次同步时重试匹配:迟到的点击、修好的链接或新的 adgroup_id 都会把花费拉进来。
"收到 N 条,匹配 0 条"
连接上的 Refresh costs 按钮会给出具体原因:
| 代码 | 含义 |
|---|---|
no_spend | 记录到了,但其中花费为零 |
no_clicks | 那几天 Orbitra 里没有点击 |
no_ids | 点击上没有广告、广告组或广告系列 ID — 链接没有直接指向 Orbitra 活动,或参数在中途丢了 |
macros | 点击里有未解析的宏,如 __CID__ — 来源没有替换值 |
ids_differ | 点击里的 ID 与广告账户报表里的 ID 对不上;两边都会显示 |
点击卡片的 "Parameters" 区块显示所有捕获的参数,广告网络 ID 排在最前面。
Facebook / Meta
需要 ads_read 权限的长期 User Token 或 System User Token,外加广告账户 ID(act_…)。可以指定 API 版本和代理。详情见 Facebook / Meta。
TikTok
三种接入方式:
| 方式 | 所需条件 |
|---|---|
| 通过 TikTok MCP 连接 | 只需一个 TikTok 登录账号。不需要开发者应用或 token — 追踪器通过 TikTok 官方 MCP 服务器自行注册。导入花费;不导入像素。面板必须通过 HTTPS 打开(裸 IP 上用 https:// 也可以) |
| 1-Click(Sign in with TikTok) | 你自己的 TikTok for Business 应用的 App ID 和 App Secret:通过 ORBITRA_TIKTOK_APP_ID / ORBITRA_TIKTOK_APP_SECRET 环境变量,或手动连接字段提供。可发现广告账户和像素,并把像素导入 Pixel Vault |
| 手动 | 免费开发者应用的 Marketing API token(Developer Portal → Apps & Agents → Direct Advertiser,需 Ads Management 和 Reporting 权限)+ Advertiser ID |
Events Manager 的 token 不能用于花费导入 — 它只能发送转化事件。如果无法通过 MCP 读取广告账户列表,可以手动粘贴 Advertiser ID,用逗号分隔。
Google Ads
- 1-Click(Sign in with Google) — 发现直投账户和 MCC 子账户,为每个选中的账户各建一条连接。需要 Developer Token(来自 MCC)和 OAuth Client ID + Secret(Google Cloud Console,类型选 "Web application",重定向 URI 为
https://your-domain/api.php?action=google_ads_oauth_callback)。 - 手动 — Customer ID、Developer Token、Client ID、Client Secret、Refresh Token。
1-Click 的密钥按以下顺序获取:ORBITRA_GOOGLE_CLIENT_ID、ORBITRA_GOOGLE_CLIENT_SECRET、ORBITRA_GOOGLE_DEVELOPER_TOKEN 环境变量 → 设置 → 已保存手动连接的字段。最省事的做法是先保存一次手动连接 — 之后 1-Click 按钮也能直接用。检查服务器配置:php check_google_ads_oauth.php。
环境变量从 PHP-FPM 环境读取(pool 配置里的
env[ORBITRA_GOOGLE_CLIENT_ID] = …),而不是.env文件 — PHP 代码不会加载它。.env.example只是一份变量名清单。
Google 和 TikTok 不接受指向 http:// 的 OAuth 重定向。在没有证书的裸 IP 上,请用手动连接。
花费靠 ValueTrack 参数 {campaignid} 和 {creative} 匹配 — Google Ads 来源模板会自动加上它们。
Push 和 pop 联盟
push/pop 广告主联盟(AdMaven、PropellerAds、Kadam、Galaxion、HilltopAds、Adsterra、Clickadu)的花费通过同一个 cron 导入,落到点击上:按活动,网络有上报时还能按 zone(站点)。烧钱的 zone 靠它来屏蔽 — Zone Killer 就基于这些数据工作。见 Push & pop networks。
Dolphin 与 Fbtool
这些服务只能通过 Keitaro 的 Admin API 发送花费。Orbitra 在 POST /admin_api/v1/campaigns/<ID>/update_costs 接受同样的请求。详情见 Dolphin / Fbtool。
手动花费
活动菜单里的 Refresh costs 按钮可手动设置一段时间的花费(action update_costs)。
收入聚合器
⚙ → Revenue Aggregator — 反过来的任务:从不发 postback 的联盟计划账户拉取收入。引擎:ReferOn、Affilka、Generic API。每条连接要设置网络、合作类型(deal type)、同步间隔,以及联盟计划存放 Orbitra 点击 ID 的参数名。收入和同步日志在同一页面的标签页里。
代理与佣金
租来的广告账户实际成本比后台报表高:代理的百分比会写进每一次导入(cost_records.fee_amount;clicks.cost 携带含手续费的花费,clicks.fee 存手续费份额)— 花费一落地 ROI/CPC 就是真实的,之后改百分比也绝不改写历史。
- 聚合器区块的 Agencies 标签页管理代理(名称、费率 %、联系方式、付款条款、备注),并可按一段时间内的花费、CPC、CPM 和 ROI 对比各家。
- 每条花费连接在编辑器里选择所属代理。
- 报表新增 Spend (cabinet) 和 Agency fee 列;任何分组都会把两者拆开。
广告名称、状态与平台指标
花费同步还会收集平台对广告本身的信息:名称和状态进 ad_entities(状态每小时刷新,在同一轮 cron 里),展示数和平台自己的点击数落到花费行上。在按广告 / 广告组 / 广告系列分组的活动报表里,你看到的是名称而不是裸 id,还有状态芯片和平台侧的列:Impressions、Clicks (platform)、CPM、CTR (platform) 以及 Click loss = 1 − 追踪器访客 / 平台点击 — 这个数字能立刻暴露斗篷或域名问题,adset.pro 没有这一项。
报表顶部的横幅显示无法关联到广告 id 的收入占比(未替换的 __CID__ / {{ad.id}} 宏按缺失计),并可一键跳到问题来源的编辑器。
Cron
*/15 * * * * php /var/www/orbitra/aggregator_cron.php >> /var/www/orbitra/var/logs/aggregator.log 2>&1
更新周期按连接逐个检查,所以 cron 跑得频繁也不费资源;间隔低于 15 分钟时就把 cron 跑得更勤一些。参数:--force(忽略周期)、--connection=5、--days=30。
快速上手
从裸机服务器到第一条转化的九个步骤:安装、首次登录、域名、联盟与 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 密钥安全。
阅读教程 →