Keitaro
July 3

Facebook Conversion API Gate для Keitaro

Бесплатный и мощный S2S-обработчик Facebook CAPI для Keitaro: с логами, переотправкой и всем необходимым

Привет, коллеги! Каждый, кто льет трафик с Facebook, знает, какая головная боль — это трекинг. iOS 14.5+ выкосил пиксель, события теряются, статистика в Ads Manager не сходится с трекером, а оптимизация кампаний летит в трубу. Решение одно — переходить на серверную передачу событий через Conversions API (CAPI).

Шаг первый и самый простой - настроить интеграцию напрямую в Keitaro. Но это если у вас лицензия старше Starter, поставщик аккаунтов выдал соц с подтвержденным номером телефона и т.д. и т.п. А если всего этого нет, но заливать трафик хочется по-взрослому? Да, есть ребята, продающие решение, скрытое Zend за $200 (на момент написания данной статьи), но это лишние траты на старте, сложно в настройке, и не даёт никакой информации о том, что и как отправляется. Хватит это терпеть!

Сегодня я делюсь полностью готовым, бесплатным и мощным скриптом-обработчиком для интеграции Keitaro и Facebook CAPI. Это не просто скрипт, а целый мини-инструмент с визуальным логгером, функцией повторной отправки и гибкими настройками.

🔥 Что умеет этот скрипт?

Это не просто очередной handler.php. Это ваш личный центр управления CAPI-событиями (мощно загнул, да?).

Интерактивный лог-вьюер. Вы в реальном времени видите КАЖДОЕ событие, которое ушло в Facebook. Больше никаких "слепых" отправок. Вы видите статус (SUCCESS/ERROR), что именно было отправлено и какой ответ пришел от FB.

Повторная отправка событий в один клик. Увидел в логе ошибку? Сервер Facebook лагнул? Не проблема. Просто нажимаете кнопку "Переотправить" прямо в интерфейсе, и скрипт повторит запрос. Статус тут же обновится. Больше ни одного потерянного лида!

Максимальный Match Rate. Скрипт автоматически хеширует и отправляет все важные данные для Advanced Matching: ip, user-agent, fbc, fbp (при наличии преленда, естественно), город, регион, страну и даже номер телефона. Чем больше данных, тем точнее Facebook найдет пользователя и засчитает конверсию.

Гибкая настройка. Вся конфигурация — в одном файле config.php. Легко указать свой пиксель, токен, сопоставить статусы (например, lead в Keitaro = Lead в FB) и добавить любые кастомные параметры (sub_id, cost, utm_source и т.д.).

Поддержка актуального API. Работает с последней версией (на момент написания сего опуса) Facebook Graph API v23.0.

Никаких зависимостей. Чистый PHP, не требует Composer или установки сторонних библиотек. Скачал ZIP с Git как есть, загрузил в Keitaro -> Laning page -> Local Landing — и все работает.

🛠️ Как это все настроить? Пошаговая инструкция

Настройка займет не больше 10 минут.

Шаг 1: Загружаем файлы

  1. Скачайте архив со скриптами с моего GitHub-репозитория
  2. Загружаем zip в локальный лендинг
  3. Сохраняем.
  4. Вы проделали половину работы, Вы восхитительны!

Шаг 2: Настраиваем config.php

Это самый важный шаг. Откройте config.php в любом текстовом редакторе.

// --- Конфигурация Facebook ---
define('FB_PIXEL_ID', 'XXXXXXXXXXX'); // 👈 ВАШ ID ПИКСЕЛЯ
define('FB_ACCESS_TOKEN', 'YYYYYYYYYYYYYY'); // 👈 ВАШ ТОКЕН (МАРКЕР) ДОСТУПА CAPI
define('FB_GRAPH_API_VERSION', 'v23.0');

// --- Сопоставление статусов ---
define('STATUS_TO_EVENT_MAP', [
    'lead' => 'Lead',     // Статус "lead" из постбэка станет событием "Lead"
    'sale' => 'Purchase', // Статус "sale" станет событием "Purchase"
]);

// --- Сопоставление данных для Advanced Matching (автоматически хешируются) ---
define('KEITARO_TO_FB_ADVANCED_MATCHING_MAP', [
    'city'         => 'ct',
    'region'       => 'st',
    'country_code' => 'country',
    'lang'         => 'lc',
    'sub_id_15'    => 'ph',      // Пример: передаем номер телефона из sub_id_15
]);

// --- Другие параметры для отправки ---
define('KEITARO_CUSTOM_DATA_PARAMS', [
    'utm_source', 'utm_campaign', 'creative_id', 'cost', 'sub_id_12' // и т.д.
]);

  • FB_PIXEL_ID: Впишите ID вашего пикселя.
  • FB_ACCESS_TOKEN: Вставьте ваш токен доступа. Где его взять? Events Manager -> Settings -> раздел Conversions API -> Generate access token.
  • STATUS_TO_EVENT_MAP: Настройте, какие статусы из Keitaro в какие события FB превращать.
  • KEITARO_TO_FB_ADVANCED_MATCHING_MAP: Укажите, какие параметры из постбэка (ключ) соответствуют полям FB (значение). Например, если CPA-сеть отдает телефон (или вы его забрали с лендинга) в параметре phone, можно написать 'phone' => 'ph'.
  • KEITARO_CUSTOM_DATA_PARAMS: Просто перечислите все дополнительные параметры, которые хотите видеть в статистике.

Вообще все параметры, что может принять Meta

Основные параметры тела

  • data
  • test_event_code

Параметры информации о клиентах

  • em: электронный адрес — требуется хэширование
  • ph: номер телефона — требуется хэширование
  • fn: имя — требуется хэширование
  • ln: фамилия — требуется хэширование
  • ge: пол — требуется хэширование
  • db: дата рождения — требуется хэширование
  • ct: город — требуется хэширование
  • st: штат, провинция или область — требуется хэширование
  • zp: индекс — требуется хэширование
  • country: страна — требуется хэширование
  • external_id: внешний ID — рекомендуется хэширование
  • client_ip_address: IP-адрес клиента — не хэшируйте
  • client_user_agent: пользовательский агент клиента — не хэшируйте
  • fbc: ID клика — не хэшируйте
  • fbp: ID браузера — не хэшируйте
  • subscription_id: ID подписки — не хэшируйте
  • fb_login_id: ID входа через Facebook — не хэшируйте
  • lead_id: ID лида — не хэшируйте
  • anon_id: ID установки — не хэшируйте (Примечание. Этот параметр относится только к событиям в приложении)
  • madid: ID рекламодателя на мобильном устройстве — не хэшируйте (Примечание. Этот параметр относится только к событиям в приложении.)
  • page_id: ID страницы — не хэшируйте
  • page_scoped_user_id: ID пользователя в пределах страницы — не хэшируйте
  • ctwa_clid: ID клика с переходом в WhatsApp — не хэшируйте
  • ig_account_id: ID аккаунта Instagram — не хэшируйте
  • ig_sid: ID клика с переходом в Instagram — не хэшируйте

Параметры серверных событий

  • event_name
  • event_time
  • user_data
  • custom_data
  • event_source_url
  • opt_out
  • event_id
  • action_source
  • data_processing_options
  • data_processing_options_country
  • data_processing_options_state
  • referrer_url
  • customer_segmentation

Параметры данных приложения

  • advertiser_tracking_enabled
  • application_tracking_enabled
  • extinfo
  • campaign_ids
  • install_referrer
  • installer_package
  • url_schemes
  • windows_attribution_id
  • anon_id
  • madid
  • vendor_id

Примечание. Руководство по интеграции событий в приложении см. в документации по Conversions API для событий в приложении.

Стандартные параметры

Ознакомьтесь со списком всех стандартных параметров, которые пользователи могут отправлять в Meta.

Исходные параметры данных событий

  • event_name
  • event_time
  • order_id
  • event_id

Шаг 3: Настраиваем Keitaro

  1. Зайдите в Keitaro в раздел Лендинги -> Создать.
  2. Выберите действие Локальный файл и загрузите наш handler.php.
  3. Сохраните лендинг, например, с названием CAPI Handler.

Шаг 4: Настраиваем Postback URL

Теперь самое главное — сформировать правильный URL для S2S-постбэка, который прописывается в Кампании -> s2s postback ->Add Postback.
Правильно вешаем галки на Lead и Sale

Шаблон URL:
https://127.0.0.1/lander/CAPI_Handler/handler.php?parameters

Пример готового Postback URL:

Generated code

http://127.0.0.1/lander/capi_handler/handler.php?status=lead&fbclid={fbclid}&ip={ip}&user_agent={user_agent}&payout={payout}¤cy=USD&sub_id_15={phone}&country_code={country_code}&city={city}®ion={region}&lang={lang}&campaign_id={campaign_id}&ad_id={ad_id}&cost={cost}

Обязательные параметры:

  • status=lead (или sale, в зависимости от события)
  • fbclid={fbclid} (или _fbc из куки, если Keitaro передает его так)

Все остальные параметры (ip, user_agent, payout, sub_id_...) опциональны, но чем их больше, тем лучше. Замените макросы типа {phone} на те, что использует ваша партнерка.

🚀 Как этим пользоваться?

  1. Настроили и забыли. После настройки постбэков события начнут отправляться автоматически.
  2. Проверяем логи. Периодически залетаем в Landing Pages -> LP Name -> Preview
  1. Вы увидите красивый лог всех отправок.
  1. Увидели ошибку?
    • Посмотрите на Ответ от Facebook. Там будет написана причина (неверный токен, кривой параметр и т.д.).
    • Нажмите кнопку "Переотправить событие". Если проблема была временной, событие уйдет, а статус в логе обновится на SUCCESS.

Заключение

Это решение закрывает 99% потребностей арбитражника в серверной отправке событий, когда прямая интеграция невозможна и приходится костылить что-то свое.

Качество сопоставления обычно не очень, но если смогли собрать телефон, почту и имя с фамилией - может быть и десяточка из десяти, да и в любом случае - лучше, чем ничего.

Вы получаете полный контроль, наглядную статистику отправок и инструмент для "починки" неудачных запросов. Больше не нужно гадать, "стучат" лиды или нет.

Забирайте, пользуйтесь и лейте в плюс!

➡️ Ссылка на GitHub: https://github.com/Dimkox/Facebook_Graph_API_Converion_Tracking

Если есть вопросы или предложения — пишите в комментариях