Настройка Facebook CAPI в Keitaro: интеграция без потери конверсий

event_id Браузерный пиксель Facebook видит не всё. Часть конверсий срезают блокировщики рекламы, приватные режимы и ограничения ITP в Safari - код на лендинге просто не успевает или не может отправить событие. Conversions API (CAPI) решает это иначе: Keitaro отправляет данные о конверсии напрямую со своего сервера на сервер Meta, в обход браузера. Ниже - как это включить в Keitaro двумя разными способами и не наступить на грабли с дублями и форматом данных.

Зачем нужен Facebook CAPI, если уже стоит пиксель?

Стандартный пиксель зависит от JavaScript в браузере пользователя. Если скрипт заблокирован или браузер режет сторонние cookie, событие просто не долетает до Facebook. CAPI отправляет тот же факт конверсии серверным POST-запросом, независимо от того, что происходит в браузере клиента. Рекомендованная схема - использовать пиксель и CAPI одновременно: Meta дедуплицирует пересечения по event_id, а не отключает один канал в пользу другого.

Какие данные нужны перед началом: Pixel ID и токен доступа

Pixel ID и Access Token - это два значения, без которых не заведётся ни встроенный модуль Keitaro, ни ручная сборка запроса. Как их получить и где именно в интерфейсе Facebook искать - разобрано отдельно, в статье Facebook Pixel ID и Access Token. Токен показывается один раз при создании - сохраните его сразу, повторно посмотреть нельзя.

Как включить встроенную интеграцию Facebook Conversion в Keitaro?

Это основной путь для большинства аккаунтов Keitaro, и он проще, чем сборка запроса вручную.

1. Откройте раздел Third-party Integrations в меню Keitaro и выберите Facebook Conversion.
2. Нажмите Add account, чтобы открыть форму создания интеграции.
3. Заполните поля: Name (произвольное название интеграции), Choose campaigns (какие кампании Keitaro шлют конверсии в этот аккаунт), Pixel ID, Conversions token.
4. При необходимости включите Use proxy - подробнее зачем, в разделе про прокси ниже.
5. Сохраните интеграцию и перейдите к настройке Mapping (следующий раздел) - без него события уходят, но не засчитываются как нужные статусы.

Если на вашем тарифе раздела Facebook Conversion в меню нет - причина в тарифном плане, а не в поломке аккаунта. Ниже - способ, который работает на любом плане.

Что делать, если тарифа с Facebook Conversion нет?

S2S Postback в Keitaro - общий инструмент отправки данных на внешний адрес, доступный на любом тарифе. Это делает его рабочей заменой встроенной интеграции, если её нет на вашем плане.

1. Откройте страницу кампании, вкладку S2S Postbacks, нажмите Add a postback.
2. Укажите метод POST и адрес: graph.facebook.com/{API_VERSION}/{PIXEL_ID}/events?access_token={TOKEN} - подставьте свой Pixel ID, токен и актуальную версию Graph API (смотрите текущую версию в документации Meta - она периодически меняется).
3. В теле запроса передайте JSON с массивом data, где на одно событие обязательны четыре поля: event_name (например, Purchase), event_time (unix-время в секундах, не старше 7 дней от текущего момента - иначе Facebook отклонит весь запрос), action_source со значением website, и user_data с как минимум fbc и fbp.
4. Добавьте event_id в каждое событие - без него дедупликация с браузерным пикселем не сработает (подробнее - в разделе про дубли ниже).

Пример минимального тела запроса:

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1721460000,
      "event_id": "kt_8841203_purchase",
      "action_source": "website",
      "event_source_url": "LANDING_PAGE_URL",
      "user_data": {
        "fbc": "fb.1.1721400000000.PAZXh0bgNhZW0BMABhZGlkAasd123",
        "fbp": "fb.1.1721300000000.1098115397",
        "client_ip_address": "203.0.113.10",
        "client_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
      }
    }
  ]
}

Значения event_time, IP и user agent берутся из макросов вашего источника трафика в Keitaro (полный список макросов - в справочнике «S2S postback placeholders» на docs.keitaro.io); в примере выше они подставлены вручную для наглядности формата.

Коротко, чем два пути отличаются на практике:

Как настроить Mapping статусов Keitaro на события Facebook?

После создания интеграции откройте Mapping внутри неё и для каждого нужного статуса выберите нужное событие Facebook. Если статус не замаплен - событие по нему просто не уйдёт. Готовую интеграцию можно скопировать кнопкой Clone вместе с настройками Mapping - удобно, если заводите вторую кампанию с той же логикой статусов.

Как собрать fbc из fbclid вручную?

Если вы идёте путём S2S Postback (раздел выше), поле fbc придётся собрать самостоятельно. Формула по документации Meta: version.subdomainIndex.creationTime.fbclid, где version всегда fb, subdomainIndex в подавляющем большинстве случаев равен 1, creationTime - unix-время в миллисекундах, а fbclid - значение одноимённого параметра из URL клика, без изменений и с учётом регистра.

Пример: клик пришёл по ссылке example.com/?fbclid=PAZXh0bgNhZW0BMABhZGlkAasd123 в 1721400000000 мс (по unix-времени). Итоговый fbc:

fb.1.1721400000000.PAZXh0bgNhZW0BMABhZGlkAasd123

Встроенный модуль Facebook Conversion (раздел выше) формирует fbc/fbp сам - вручную собирать формулу нужно только при DIY-пути через S2S Postback.

Как не задвоить конверсии между пикселем и CAPI?

Если на лендинге уже стоит код пикселя, Facebook может получить одну конверсию дважды. Чтобы система распознала дубль, оба события - и с браузера, и с сервера - должны нести одинаковый event_id. Механизм и практические примеры разобраны отдельно: event_id и дедупликация.

Что такое Event Match Quality и как его поднять?

Чем больше корректных полей user_data в событии (email, телефон, IP, user agent, fbc/fbp), тем выше EMQ и точнее атрибуция. Смотреть показатель нужно в Events Manager, в карточке источника событий. Если после запуска интеграции EMQ низкий - проверьте в первую очередь, что fbc/fbp вообще доходят до Facebook (раздел выше) и что email/телефон, если они собираются, передаются хешированными по SHA-256, как того требует документация Meta.

Когда включать Use proxy?

Без прокси запросы к Facebook API идут прямо с сервера Keitaro. Это нормально в большинстве случаев, но при высокой частоте запросов или работе из региона, который Facebook временно ограничивает, встроенная опция Use proxy снижает риск блокировки.

Нужно ли прогревать пиксель перед запуском CAPI?

Подключение CAPI не отменяет правило прогрева: на свежий пиксель конверсии заводят постепенно, а не разом всем накопленным объёмом. Как именно это делать по шагам - в статье прогрев пикселя.

Что делать с лидами старше 7 дней (ошибка 2804003)?

Если вы решили загрузить накопленные старые лиды и получили ошибку 2804003 - это ограничение по event_time из документации самого Facebook, а не баг Keitaro. Простая замена времени на текущее сломает дедупликацию из раздела выше. Подробный разбор безопасного обхода - в статье Ошибка CAPI 2804003: как обойти лимит 7 дней в Facebook.

Как проверить, что интеграция реально работает?

1. В Events Manager откройте пиксель, вкладку Test Events, скопируйте test_event_code.
2. Отправьте тестовое событие с этим кодом (через Pixel Activator или прямой запрос).
3. Убедитесь, что событие появилось со значком сервера, а при параллельной отправке с браузера - со статусом Deduplicated.
4. Если событие не пришло вообще - смотрите S2S postback log в Keitaro: Maintenance → Logs → S2S postback log - там виден код ответа Facebook на каждый отправленный запрос, независимо от того, каким путём вы его настроили.

Автоматизация через Most - когда ручная настройка не окупается

Всё, что описано выше - Mapping, формат fbc, дедупликация, слежение за EMQ - требует постоянного внимания: токены протухают, статусы меняются, Facebook время от времени меняет требования к полям. Most забирает конверсии из Keitaro по расписанию, сам собирает user_data в нужном формате и следит, чтобы события не задваивались и не проваливались по лимиту 7 дней.

Источники