Facebook CAPI и TikTok Events¶

Прямая передача конверсий в рекламные платформы, минуя браузерный пиксель. Работает надёжнее пикселя: события уходят с сервера и не режутся блокировщиками и ограничениями трекинга в браузерах.

Настройка: Настройки → Интеграции. Токены хранятся зашифрованными и после сохранения по API не возвращаются.

Facebook Conversions API¶

Что нужно: Pixel ID и Access Token (Events Manager → ваш Pixel → Settings → Conversions API). Необязательно — Test Event Code.

Как это работает:

На клике трекер запоминает fbclid из ссылки (в виде fb.1.<время>.<fbclid>), куку _fbp, IP и User-Agent посетителя.
При конверсии отправляет событие в CAPI: event_id = ID конверсии, value = payout, currency, event_source_url = URL оффера, content_ids = ID кампании.
Результат каждой отправки виден в логе доставок.

Статус конверсии превращается в стандартное событие Facebook:

Статус	`event_name`
`sale`	`Purchase`
`lead`	`Lead`
`registration` · `signup` · `install`	`CompleteRegistration`
`trial`	`StartTrial`
`subscribe`	`Subscribe`

rejected и trash не уходят никогда. Значения для sale, lead и registration переопределяются в форме подключения; пустое значение означает «этот статус не отправлять». Свой статус в форму добавить нельзя — только через API: POST /admin_api/v1/integrations, поле config.status_map. Статус без соответствия просто пропускается — строки в логе доставок для него не будет.

TikTok Events API¶

Что нужно: Pixel Code (он же event_source_id) и Access Token — TikTok Events Manager → ваш Pixel → Settings → Events API. Test Event Code тоже необязателен.

Схема та же: на клике запоминаются ttclid из ссылки, кука _ttp, IP и User-Agent; при конверсии событие уходит в Events API, доставки пишутся в тот же лог.

Статус	Событие
`sale`	`CompletePayment`
`lead`	`SubmitForm`
`registration` · `signup` · `install`	`CompleteRegistration`
`subscribe`	`Subscribe`

TikTok отвечает 200 и на отказ

Events API возвращает HTTP 200, а реальный результат кладёт в поле code тела ответа (0 — успех). Трекер засчитывает доставку только при 200 и code: 0, поэтому в логе бывает «HTTP 200, но fail» — причина в теле ответа.

Персональные данные¶

Чтобы платформа сматчила пользователя точнее, партнёрка может прислать в постбэке em (e-mail) и ph (телефон). Перед отправкой трекер нормализует и хеширует их SHA-256: e-mail — в нижнем регистре и без пробелов, телефон — только цифры. Так же хешируется external_id — им служит txid партнёрки. В сыром виде персональные данные не уходят.

fbc/fbp, ttclid/ttp, IP и User-Agent уходят как есть — это собственные идентификаторы площадок, и они ждут их в сыром виде.

Проверка¶

Кнопка Test event на карточке интеграции (появляется после подключения) отправляет синтетическое событие — Lead для Facebook, SubmitForm для TikTok, payout 1 USD — с уникальным event_id и тут же показывает HTTP-код и ответ платформы. С заполненным Test Event Code событие видно в разделе Test Events рекламного кабинета примерно за полминуты.

Уберите Test Event Code после проверки

Пока он заполнен, события помечены тестовыми и не попадают в основную атрибуцию.

Рядом с кнопкой — сводка за 24 часа (успехи, ошибки, success rate) и раскрывающийся список последних доставок: время, событие, click_id, HTTP-код и длительность запроса.

Доставка и дедупликация¶

Конверсия попадает в устойчивую очередь в Redis, и уже оттуда расходится по подключённым площадкам. Неудачная доставка из очереди не пропадает: повтор не чаще раза в минуту, всего до шести доставок (первая плюс до пяти повторов). После этого событие уходит в DLQ — Настройки → DLQ, блок «Server-side конверсии (CAPI / TikTok)», откуда его можно отправить заново по одному или все сразу.

Если Redis недоступен, доставка переключается на ограниченный пул внутри процесса: она становится best-effort, и всё, что не удалось доставить или что не влезло в пул, складывается в тот же DLQ.

Идентификатор события равен ID конверсии, поэтому повторная отправка после частичного сбоя не создаёт дубль: Facebook и TikTok схлопывают такие события у себя.

Не дублируйте каналы

Если конверсии уходят через CAPI, не настраивайте на ту же кампанию ещё и S2S-постбэк в тот же источник — ни на кампании, ни на источнике. Иначе платформа получит событие двумя путями и статистика разъедется.