Гайд - Трекинг

События и конверсии: денежный слой воронки

Клик - это расход, пока событие не докажет, что он окупился. В Leadgram каждая конверсия - старт бота, регистрация, депозит - это событие, привязанное к конкретному клику, и именно эта связка кормит всё, что происходит дальше: выручку в Отчётах, постбэки в партнёрские трекеры, серверные конверсии, которые уходят обратно в Meta и Google, и пуш подписчику, который сконвертился - если это прописано в вашем Флоу. Наладите события правильно - и трекер начнёт показывать правду о вашем спенде.

Типы событий

  • Воронка - click, land, bot_start, channel_join, join_request, first_dm, miniapp_launch. Показывают, как пользователь движется по вашей Telegram-воронке.
  • Конверсии - lead, registration, deposit, ftd, purchase. За них платит рекламодатель.
  • Кастомные - custom_1-custom_8 под любую специфику оффера.

Большинство конверсионных событий также двигают статус клика на странице Клики: Клик → Лендинг → Старт → Регистрация → Лид → Депозит → FTD. Статус двигается только вперёд - если registration придёт уже после ftd, клик назад не откатится. Исключение - purchase: он биллится и попадает в отчётность как любая другая конверсия, но статус клика не трогает. Так же ведут себя channel_join и события custom_* - все три записываются в базу, просто не участвуют в лестнице статусов воронки.

Как события попадают в систему

  1. S2S / API. Ваш бэкенд (или постбэк-скрипт рекламодателя) шлёт POST /api/events с clickId, типом события и опциональными payout и nonce. API-ключ для внешних инструментов вроде Keitaro или собственных скриптов создаётся в Настройках → API ключи. Забрать события обратно можно через GET /api/events (с пагинацией, с фильтром по type) - удобно, когда нужно сверить, что реально сработало, с вашими собственными записями.
  2. Флоу. Поставьте узел «Триггер события» в нужный шаг Флоу - событие сработает автоматически, когда подписчик до него дойдёт. Регистрации и депозиты прямо из Telegram-воронки, без единой строчки кода.

Дедупликация детерминированная: повторная отправка того же clickId + типа без nonce считается ретраем той же конверсии и никогда не создаёт вторую строку, второе списание или дубль Purchase в Meta. Настоящая повторная конверсия (второй депозит с того же клика) обязана идти с уникальным nonce.

Биллинг-гейт

Записать событие и доставить его дальше - две разные вещи. У каждой строки события есть billing_status: пока идёт списание, он pending, затем становится charged или free. Отправка в CAPI, постбэки и пуш подписчику по событию срабатывают только после того, как этот статус разрешится в charged или free - у приостановленной организации или при пустом балансе строка остаётся blocked (при сбое списания - error), и событие лежит в базе, так и не дойдя ни до Meta, ни до Google, ни до вашего постбэк-эндпоинта, ни до подписчика.

Если конверсия появилась в списке событий, а на другом конце ничего не сработало - сначала проверьте биллинг, а не интеграцию. Событие в статусе blocked не сломано, оно ведёт себя ровно так, как задумано.

Поле payout

Передавайте payout (USD, до двух знаков после запятой) с каждой платящей конверсией. Оно попадает в два места:

  • Выручка в Отчётах - колонка выручки складывается из payout всех подтверждённых событий.
  • Google Ads - payout становится conversionValue серверной конверсии, и Smart Bidding оптимизируется на реальные деньги.

Постбэки payout не передают. Партнёрским трекерам доступны плейсхолдеры {click_id}, {event_type}, sub-цепочка и нативные click id рекламных площадок - полный список смотрите в Постбэках. Если вашему трекеру нужна сумма конверсии, передавайте её через собственную интеграцию.

Что значит колонка CAPI

В таблице «Последние события» на Дашборде у каждого события есть статус CAPI: Отправлено означает, что все рекламные площадки, привязанные к кампании, приняли конверсию; В ожидании означает, что хотя бы одна доставка ещё в очереди или падает. Детали по площадкам - попытки, последняя ошибка, повторная отправка в один клик - на странице Доставка конверсий.

Безопасное тест-событие

На странице Facebook у каждого CAPI-аккаунта Meta есть кнопка «Отправить тест-событие». Она шлёт синтетический Purchase с вашим кодом Test Events из Meta Events Manager, поэтому событие появляется во вкладке Test Events и никогда не затрагивает оптимизацию рекламы, атрибуцию или списания. Это самый быстрый способ убедиться, что пиксель и токен работают, ещё до того, как потрачен первый доллар. Без кода кнопка не сработает - событие без кода Meta засчитала бы как настоящее.

Частые грабли

  • Пропустить nonce на повторной конверсии - второй депозит молча посчитается ретраем и будет отброшен.
  • Отправлять события без payout - выручка в Отчётах останется нулевой, а Google получит конверсии без ценности.
  • Отправить registration для клика, который уже дошёл до ftd, и ждать, что статус изменится - не изменится, так задумано.
  • Ждать, что purchase сдвинет статус клика по воронке - никогда не сдвинет, хотя биллится как любая другая конверсия.
  • Читать «В ожидании» в колонке CAPI как баг - сначала загляните в Доставку конверсий, там обычно названа конкретная ошибка площадки.
  • Считать, что записанное событие уже доставлено - статусы биллинга blocked, error и pending означают, что оно так и не дошло ни до CAPI, ни до постбэков, ни до пушей.