Документация

Facebook / Meta integration

Orbitra has two independent Facebook integrations. They solve opposite halves of the same loop and are configured in different places:

What it doesDirectionWhere
Facebook CostsImports ad spend from Meta into the trackerMeta → OrbitraIntegrations → Facebook Costs
Facebook Conversions APISends conversions from the tracker to MetaOrbitra → MetaIntegrations → Facebook Conversions

Both are also reachable from where the underlying records live: cost connections appear on the Aggregators page (they are aggregator_connections rows with engine facebook), and a campaign's pixel can be edited from the campaign's own Integrations tab. Same data either way — the Integrations page is the entry point, the other two are the context-specific views.

Neither depends on the other. Cost import gives you real ROI; the Conversions API gives Meta's optimiser the events the browser pixel loses.


1. Campaign setup (required by both)

Both integrations key off the parameters the ad carries into the tracker. Set the campaign up once and both work.

Create the campaign, pick the Facebook traffic-source template, and use the generated URL parameters in the ad's URL parameters field:

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}}

Rules that matter:

ad ID is not on the click — for example when creatives rotate under Advantage+.

a macro produces an empty value that overwrites the real one, and the Conversions API then has nothing to match on.

them as sub_id_N and tell the cost connection where they landed — see Traffic through an app.

Orbitra captures these through the shared core/ClickParams.php collector. It captures fbclid and available _fbp / _fbc values; browser tracking also collects cookies created after the initial request. Ad URL macros do not create an fbp browser identifier. See browser matching for external landings, consent and cross-channel identity.


2. Facebook Costs

Getting an access token

A long-lived User Access Token or a System User Token with ads_read works. The System User token is the one to use in production — it does not expire with a person's session.

  1. <https://business.facebook.com/settings/system-users> → add a system user
  2. Assign the ad account to it with View performance (or full control)
  3. Generate token → select your app → tick ads_read → copy it

The token is shown once. Store it before closing the dialog.

Ad account ID

From Ads Manager — the act_1234567890 value. Orbitra accepts it with or without the act_ prefix.

Creating the connection

Integrations → Facebook Costs → Add account:

FieldNotes
Access Tokenlong-lived or system user token
Ad Account IDact_1234567890
Facebook API versiondefaults to the newest supported; older accounts can pin an older one
Proxyoptional, scheme://user:pass@host:port, also accepts socks5://
Update spend everyhow often the cron re-reads spend
Advanced: parameter mappingonly for traffic through an app — see below

Each account row shows its status and next update, and carries Update spend (one manual sync now), Pause/Resume, Clone and Delete.

Test connection reads the ad account itself (name, currency, timezone, status), not an insights report — an empty report is a valid answer and would otherwise hide a dead token.

What gets synced, and when

run, and 30 days on a connection's first sync.

a running total that grows all day. Records are therefore upserted on (connection_id, external_id) and attribution is recomputed, never accumulated — re-syncing the same day is safe and idempotent.

ad on one day.

Cron — sub-hour sync intervals (20/30 min) need the cron itself to run every few minutes; due-checking is per connection, so frequent runs are cheap:

*/5 * * * * php /var/www/orbitra/aggregator_cron.php >> /var/log/orbitra_aggregator.log 2>&1

Useful flags: --force (ignore the interval), --connection=5, --days=30.

How spend reaches a click

For each imported record Orbitra resolves the clicks it belongs to, most specific level first:

  1. ad_id (also creative_id, creative)
  2. adset_id (also adgroup, adgroupid, ad_group_id)
  3. campaign_id (also campaign, campaignid, ad_campaign_id)

The day's spend is then split evenly across that day's matching clicks — the same flat-CPC model manual cost entry uses.

Currency

Meta reports in the ad account's currency. Orbitra converts to the tracker currency (Settings → currency) before storing, so cost and revenue are always in the same unit. Rates are fetched from open.er-api.com and cached for 12 hours.

To pin rates yourself (air-gapped install, or you want your bank's rate), set the fx_rates_manual_json setting — values are units per 1 USD:

{"EUR": 0.92, "RUB": 92.5}

Manual rates always win over the fetched table. The platform's original amount and currency are kept in cost_records.raw_json under _orbitra, so a wrong rate can be reconstructed after the fact.

Traffic through an app

If the macros arrive repacked — Facebook → app → Orbitra — forward them as sub IDs:

  1. In Facebook: sub_id_3={{adset.id}}
  2. From the app to Orbitra: sub_id_3={sub_id_3}
  3. In the account's Advanced: parameter mapping, set *Adset ID arrives in

parameter* to sub_id_3

ad_id_param and campaign_id_param work the same way. Overrides are tried first and the standard keys stay as a fallback, so a partial mapping degrades instead of matching nothing.

Troubleshooting

"Fetched N, matched 0" — spend arrived but nothing could be attached to a click. The cron log says this explicitly. Almost always the campaign URL is missing ad_id / adset_id / campaign_id. Check a recent click's parameters in ⚙ → Logs → Traffic.

Update spend on the account row names the exact reason (no_spend, no_clicks, no_ids, macros, ids_differ) with the date and the IDs on both sides — see Costs (Russian). Unmatched rows retry on every sync.

Sync reports an error with a Meta message — the message is Meta's own, verbatim. Common ones:

Move the connection to a newer version.

Set a proxy on the connection.

Day boundaries look shifted — Meta reports days in the ad account's timezone, the tracker stores clicks in server time. If the two differ, spend near midnight lands on the neighbouring day. Align the ad account timezone with the server, or accept the edge.


3. Facebook Conversions API

The browser pixel is blocked for a meaningful share of traffic — ad blockers, ITP, iOS. Orbitra knows about every conversion the moment the affiliate network posts back, and it knows the click's IP, user agent, fbclid and _fbp. Sending the event server-side recovers what the pixel loses.

Getting a Conversions API token

Events Manager → your pixel → Settings → Conversions API → Generate access token. Copy it immediately; it is shown once.

The Pixel ID is on the same page (Events Manager → Data sources).

Setting it up

Integrations → Facebook Conversions → Add account (or, from inside a campaign, its own Integrations tab → Facebook Pixel — the same record):

FieldNotes
Campaignwhich campaign's conversions this pixel receives
Pixel IDfrom Events Manager
Conversions API tokenthis is what turns server-side sending on
Status → Meta eventwhich tracker status produces which Meta event
Test event codeoptional, from Events Manager → Test events
Proxyoptional, same format as the cost connection
Event source URLactual page where the event happens; required by Meta for website events

A pixel row without a token stays browser-only — the list marks it Browser pixel only rather than showing it as a working integration. Nothing is sent server-side until a token is present.

Default mapping:

Tracker statusMeta event
leadLead
salePurchase
depositPurchase
registrationCompleteRegistration
rejectednot sent
trashnot sent

rejected and trash are deliberately unmapped: feeding a rejected lead back as a conversion teaches the optimiser to buy more of exactly the wrong traffic.

Send test event posts one event immediately, using your most recent real click with an fbclid when there is one. Check it under Events Manager → Test events.

What gets sent

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 and fbp are sent unhashed. Personal matching fields and the visitor's Meta external ID are hashed. The legacy external_id tracking parameter remains unchanged: for other traffic sources it can mean an ad click, so it is not automatically reused as a Meta visitor identity.

The event URL is not the acquisition referrer

Configure the real checkout/thank-you URL on the integration, or have the partner include an URL-encoded event_source_url in the postback. An explicit configured URL wins. The configured macros {campaign_url}, {landing_url} and {clickid} remain available, but use them only when they describe the page of this event. {landing_url} uses captured landing context (or the saved landing URL), never the click's Facebook/Google acquisition referrer.

For events that happen on different pages, the campaign's Event source URL text field also accepts an advanced JSON map keyed by the final Meta event name:

{"InitiateCheckout":"{campaign_url}","Purchase":"{offer_url}"}

This is an explicit configuration, not a default inference about your funnel. Use this example only when checkout initiation happens on the campaign page and the purchase is completed at the selected offer's URL. A missing map key allows an explicit URL from the integration; a present but empty/invalid entry does not substitute another page. URL selection never disables the event itself. Plain URL settings and existing macros retain their behavior.

{offer_url} resolves the persisted click's selected offer through the existing offer/network parameter and click-macro rules. It does not pick the first offer in a campaign, follow redirects or discover a third party's confirmation page. It uses the offer configuration at postback time, not a historical snapshot: keep it stable while conversions are pending, or leave that event unconfigured and supply its actual URL through the integration instead. Do not use it when the offer redirects to a different page where the event occurs.

This advanced map is a campaign-level setting; the Pixel Vault's URL field still accepts a plain URL. Saving a linked central profile overwrites campaign URL overrides under the existing profile-sync behavior, so review those overrides after profile edits. The manual test endpoint does not supply campaign/offer macro context; use an explicit real URL for a representative manual test rather than expecting it to discover a checkout.

Orbitra does not infer a producer's checkout URL from your landing page. If no valid URL is known, it logs a configuration warning and omits the field, retaining the queued intent and Meta's delivery result. Before upgrading, integrations that relied on the old referrer fallback need a real event URL: Meta requires it for website events and may reject requests without it. Do not substitute a page the visitor never used. Browser reportConversion() includes the current page; a supplied event_source_url can override that when the integration knows better.

The native landing/offer path and the current tracking.js, kclient.js and PHP KClient support the shared meta-matching.js collector. It preserves opaque cookie values, including Parameter Builder suffixes. A new fbclid replaces a stale fbc; repeated observations of the same click preserve its timestamp. Identifiers are not shortened to the general 512-byte tracking-parameter limit.

New matching cookies/identity are limited to visits with an active Facebook campaign pixel, existing fbclid/fbc/fbp context, or explicit meta_matching=1. Unrelated campaigns do not acquire Meta cookies merely by updating Orbitra. On an eligible saved browser visit, when cookies are enabled, the collector reuses _fbp or creates a first-party browser cookie once if absent. It also keeps an anonymous orbitra_visitor identity for 90 days. Neither is generated at conversion time. Cookie capture runs early and again after page load, on outbound interaction and page exit. A signed, click-scoped POST can update only fbp, fbc and the first observed landing URL, not the visitor identity, IP, User-Agent or conversion. These updates affect future payloads, not events already queued.

External landings must update their copied client files too. PHP KClient forwards the visitor IP/User-Agent and browser cookies, not the hosting server's identity; place echo $client->matchingScript(); early in the landing's <head> for late cookie capture (timerScript() also includes it). Keep trusted-proxy handling on the landing server configured correctly; do not trust arbitrary forwarded IPs.

This is a focused implementation of Meta's documented parameter rules, not an installation of the official Parameter Builder SDK or all its optional browser-enrichment features. See Meta's Parameter Builder guidance and fbp/fbc specification.

The collector is not a consent-management platform. Operators must gate tracking according to their consent policy. use_cookies=0 disables the matching collector; meta_matching=0 on an incoming visit disables it for that click. On external JavaScript integrations, set window.orbitra_meta_matching = false before loading the clients to opt out; PHP clients can use ->param('meta_matching', '0'). Native HTML injection uses a deferred script: an inline consent flag set in the landing before deferred scripts run can disable browser collection. It cannot undo server-side capture/cookies already set in the HTTP response. Use the server-side controls before serving that visit when collection is not permitted.

Reusing the visitor ID in the browser Pixel

The collector does not install or fire a Meta Pixel. In your existing, consented Pixel setup, pass the same raw identity before the first real browser event:

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.

Use this after the client/collector is ready, including deferred loading on native landings. PHP integrations can obtain the same raw value using $client->getExternalId() (use json_encode when embedding it in JavaScript). Orbitra hashes it once for CAPI. Do not replace it with an order ID, hash it again, or create another ID in the postback. The existing click/subid relationship carries it through the affiliate conversion; email and phone are not needed to maintain that relationship. It still needs a real Pixel/CAPI association to help Meta matching; creating an ID alone cannot guarantee a match. Meta external ID guidance.

To send PII, include it in the incoming postback:

https://tracker.example/<postback_key>/postback?subid=3sh8so4er3&status=sale&payout=2.61&[email protected]&fn=John&ln=Snow&ph=+71234567890

Values are normalised the way Meta requires (email lowercased, phone reduced to digits) before hashing — an unnormalised hash simply never matches.

Delivery and retries

The conversion, click totals and eligible CAPI intents commit in one short SQLite transaction. A queue-write failure rolls back that unit and returns an error (503 for exhausted lock contention), so the sender can retry. The browser conversion GIF preserves these server errors instead of masking them as HTTP 200. Notifications and outbound S2S preparation stay outside the write transaction.

Repeated postbacks reuse the existing intent for the same conversion, pixel, event name and event ID, including failed/delivered rows. A different status/event or transaction ID can create a distinct event. Queue idempotency lasts while the original delivery row is retained; purging logs removes that local history. This is not automatic browser deduplication: the Pixel must use the same eventID and event name for the same action. Schema migration 52 adds an indexed lookup and an internal signing-key table; it does not recover or replay historical conversions.

Events are queued in s2s_postbacks_log and delivered by postback_queue_cron.php with exponential backoff, the same worker that delivers outbound S2S postbacks. A slow response from Meta never delays the answer to the affiliate network's postback. A sender that times out may retry; repeated intake reuses the existing CAPI intent rather than queueing the same event again.

* * * * * php /var/www/orbitra/postback_queue_cron.php >> /var/log/orbitra_postback_queue.log 2>&1

Delivery status, HTTP code and sanitized failure details are visible in the S2S logs UI. The existing response column, also returned by the logs API, now stores bounded, sanitized events_received, warnings/messages and fbtrace_id when provided. It does not keep the arbitrary raw response body or echoed credentials.

For Meta, delivered now requires HTTP 2xx, a JSON object without an API error, and events_received confirming the full request. Ambiguous responses and transient errors follow the existing bounded backoff; permanent authentication or validation errors fail without useless retries. The manual test button uses the same validation. Generic S2S and TikTok transport rules are unchanged.

Recorded, queued, confirmed by Meta, and attributed to an ad are different stages. A confirmed API response is not proof of individual campaign attribution and does not guarantee immediate Ads Manager reporting.

Troubleshooting

Nothing arrives in Events Manager — check, in order: the click has fbclid (⚙ → Logs → Traffic); fbclid={fbclid} is not in the ad's URL parameters; the status is mapped to an event; the queue worker cron is running; the S2S log shows the attempt.

"Invalid parameter" from Meta — usually the pixel ID and token belong to different assets, or the token was generated for a pixel you no longer own.

Events arrive but match quality is low — check captured fbp/fbc, the actual visitor IP/User-Agent, consent and whether the same external identity reaches the browser Pixel. Missing email/phone does not by itself mean an event is rejected. Cross-domain cookies cannot be read from another site's request: use the external landing client on that domain. On an immediate redirect without browser code, only already available identifiers can be captured.


Files

PathRole
aggregator_engines/FacebookAdsEngine.phpMarketing API insights reader
core/CostImporter.phpupsert + attribution + currency
core/CurrencyRates.phpFX table, cache, manual overrides
core/ClickParams.phpwhat gets captured on a click
core/FacebookConversions.phpCAPI payload, hashing, queueing
postback.phpenqueues CAPI events on conversion
postback_queue_cron.phpdelivers them with retries
tests/facebook_integration_test.phpend-to-end coverage, no network
← Назад
Push и pop сети
Вперёд →
Dolphin / Fbtool — приём расходов (Keitaro Admin API)
Исходник на GitHub: github.com/fenjo26/Orbitra.link/wiki
Все гайды
Документация

Быстрый старт: первая кампания

Короткий путь: установите трекер, создайте кампанию и получите первые клики и конверсии меньше чем за час.

Читать гайд →
Документация

Установка и обновление

Установите Orbitra на чистый сервер Ubuntu или Debian одной командой и безопасно обновляйтесь до новых версий.

Читать гайд →
Документация

Миграция из Keitaro

Перенесите кампании, офферы, источники и домены из Keitaro в Orbitra в один клик — что переносится и что проверить.

Читать гайд →
Документация

Миграция из Binom

Перенесите кампании и потоки из Binom в Orbitra: что переносится автоматически, а что настроить вручную.

Читать гайд →
Документация

Возможности Orbitra

Всё, что умеет Orbitra: кампании и потоки, клоакинг, лендинги, PWA, постбеки, расходы, отчёты и интеграции.

Читать гайд →
Документация

Кампании и потоки

Полный справочник: настройки кампаний, типы потоков, схемы, ротация, фильтры, тестовые ссылки и каждый параметр.

Читать гайд →
Документация

Клоакинг

Полный справочник по клоакингу: уровни детекции, глобальные настройки, фильтры потоков, вердикты и отчёты.

Читать гайд →
Документация

Проверка браузера

Как JS-проверка ловит ботов, виртуальные машины и эмуляторы через противоречия в окружении браузера.

Читать гайд →
Документация

Лендинги

Типы лендингов, макрос {offer}, JS-адаптер, LeadForge и мульти-оффер лендинги — полный справочник.

Читать гайд →
Документация

PWA-лендинги и Web Push

Собирайте устанавливаемые PWA-приложения и собирайте push-подписчиков: настройки, иконки, события и уведомления.

Читать гайд →
Документация

PWA-воронка

Многошаговая PWA-воронка: приглашения к установке, отслеживание событий и возвратные уведомления.

Читать гайд →
Документация

Конверсионные попапы

Показывайте реальные конверсии как попапы на странице: настройка, триггеры и размещение.

Читать гайд →
Документация

Записи сессий и карта кликов

Воспроизводите реальные визиты, смотрите карты кликов и скроллов. Лимиты хранения и приватность.

Читать гайд →
Документация

Галерея контента

Центральное хранилище иконок, скриншотов и креативов для PWA и лендингов.

Читать гайд →
Документация

Библиотека креативов

Храните креативы с отслеживанием по subid и тестируйте их в разных кампаниях.

Читать гайд →
Документация

Внешние PWA и Telegram-каналы

Публикуйте PWA на внешних доменах и используйте Telegram-каналы как источник трафика.

Читать гайд →
Документация

Постбеки и конверсии

Входящие постбеки, статусы и типы конверсий, исходящие S2S-постбеки в источник трафика.

Читать гайд →
Документация

Расходы: импорт из рекламных кабинетов

Импорт расходов из Facebook, TikTok и Google Ads, обновление через API и крон — и как работает агрегатор доходов.

Читать гайд →
Документация

Push и pop сети

Работа с пуш и поп источниками трафика: фиды, оптимизация зон и zone killer.

Читать гайд →
Документация

Facebook / Meta integration

Импорт расходов из Meta Ads и Conversions API: серверные события с дедупликацией.

Читать гайд →
Документация

Dolphin / Fbtool — приём расходов (Keitaro Admin API)

Получайте расходы Facebook через API Dolphin (Fbtool) в реальном времени.

Читать гайд →
Документация

Чистилка комментариев FB

Массовая модерация комментариев под рекламой Meta: скрывать, удалять и фильтровать по ключевым словам.

Читать гайд →
Документация

Источники трафика и партнёрские сети

Каталог 50+ источников трафика и 440+ сетей: шаблоны, параметры и адреса постбеков.

Читать гайд →
Документация

Отчёты, логи и метрики

Конструктор отчётов, сохранённые отчёты, логи кликов и каждая метрика с пояснением.

Читать гайд →
Документация

Домены и SSL

Добавление доменов, DNS, бесплатные сертификаты Let's Encrypt, редиректы, парковка и каждый переключатель на странице.

Читать гайд →
Документация

Cloudflare — DNS и SSL доменов

Как запускать домены кампаний через Cloudflare: DNS, режимы SSL и что отключить.

Читать гайд →
Документация

Администрирование

Пользователи, роли и права, настройки безопасности, гео-базы, обновления и состояние системы.

Читать гайд →
Документация

Telegram-бот

Управляйте трекером из Telegram: статистика, конверсии и алерты в чате.

Читать гайд →
Документация

MCP-сервер: работа с трекером через нейросеть

Подключите Claude или любой MCP-клиент к Orbitra и управляйте кампаниями обычными словами.

Читать гайд →