Гайд - Постбэки

Постбэки: каждая конверсия - в ваш трекер

Если вы льёте трафик через Keitaro или RedTrack, или работаете по офферам партнёрской сети, клик выпадает из поля зрения трекера в тот момент, когда попадает в Telegram. Регистрации и депозиты происходят там, куда трекер не дотягивается, а без данных о конверсиях незаметно умирают отчёты по расходам, авто-правила и сверка выплат. Постбэки замыкают эту цепочку: на каждую конверсию, которую фиксирует Leadgram, платформа стучится в S2S-URL вашего трекера - и денежная сторона воронки остаётся видна там, где вы реально оптимизируете.

Как работают постбэки

Правило постбэка - это три вещи: событие-триггер, шаблон URL и HTTP-метод. Как только по одному из ваших кликов фиксируется конверсия - через server-to-server вызов events API от рекламодателя или через узел «Триггер события» внутри флоу сообщений, - срабатывают все включённые правила с этим типом события, чья область покрывает кампанию этого клика. Одно событие, одно правило, один HTTP-запрос.

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

Создание правила

  1. Откройте «Постбэки» и нажмите «Добавить постбэк».
  2. Выберите пресет: Keitaro и RedTrack подставят шаблон URL, «Свой» оставит поле пустым.
  3. Назовите правило - чтобы потом узнать его в таблице.
  4. Выберите событие-триггер: «Лид», «Регистрация», «Депозит», FTD, «Покупка», «Старт бота» или «Вступление в канал».
  5. Вставьте URL эндпоинта с макросами (список ниже).
  6. Выберите GET или POST. При POST макросы в URL по-прежнему работают, а те же поля дополнительно уходят JSON-телом.
  7. Выберите режим «Дедупликация» - сколько отправок по этому правилу может получить один пользователь Telegram. По умолчанию стоит «Выкл - отправлять каждое событие»; что делают три остальных, разобрано ниже, в разделе про доставку.
  8. Выберите «Область» - на конверсиях каких кампаний правило вообще стреляет. По умолчанию стоит «Все кампании»: правило срабатывает на конверсиях любой кампании организации, и это полноценный рабочий режим, а не недонастроенное правило. Конкретную кампанию выбирайте тогда, когда этот адрес должен получать только её конверсии, - например, когда в организации два оффера и каждый рекламодатель должен видеть свои конверсии, а не соседские.
  9. Нажмите «Добавить постбэк», чтобы сохранить - правило включается сразу же и появляется в таблице вместе с событием, методом, дедупликацией, областью, временем последнего срабатывания и статусом.

Сохранённое правило дальше правится прямо в таблице: «Изменить» в строке открывает диалог с названием, URL и областью, в меню строки лежат «Отключить» или «Включить» и «Удалить» (удаление спросит подтверждение и отмены не имеет). Событие-триггер, метод и пресет после сохранения неизменяемы: под другое событие заводится отдельное правило. А вот область меняется когда угодно - правило, по ошибке оставленное на всех кампаниях, сужается до нужной прямо в этом диалоге, и точно так же возвращается обратно ко всем; пересоздавать ничего не надо. Режим дедупликации меняется без диалога, селектом прямо в колонке «Дедупликация».

Форма правила постбэка с событием-триггером и шаблоном URLФорма правила постбэка с событием-триггером и шаблоном URL

Макросы URL

Эти плейсхолдеры подставляются при каждом срабатывании:

  • {click_id} - id клика в Leadgram. Подходит, когда принимающая сторона - рекламодатель, который получил этот id от вас; для внешнего трекера он не годится, трекер его никогда не видел (см. раздел про Keitaro ниже)
  • {event_type} - название события (deposit, ftd и так далее)
  • {sub1}-{sub5} - суб-цепочка, пойманная на клике. Именно сюда приходит собственный click id внешнего трекера, и именно по нему трекер матчит постбэк
  • {campaign_id} - кампания, которой принадлежит клик; пусто, если клик пришёл вне кампании
  • {offer_id} - оффер, привязанный к клику; пусто, если клик не проходил через оффер
  • {platform} - рекламная площадка кампании (meta, google, tiktok)
  • {fbclid}, {gclid}, {gbraid}, {wbraid}, {ttclid} - нативные click id рекламных площадок

Пустые значения превращаются в пустую строку, так что &fbclid={fbclid} не сломает постбэк на Google-трафике. Токен, которого нет в этом списке, остаётся в URL как обычный текст: постбэк подставляет ровно то, что перечислено выше, и ничего больше.

Связка с внешним трекером: Keitaro

Правило, на котором ломается большинство интеграций: внешний трекер должен быть первым хопом, до трекинг-ссылки Leadgram. Постбэк матчится в трекере по ЕГО click id, а вернуть этот id Leadgram может только в том случае, если трекер отдал его на входе. Если Keitaro стоит после Leadgram или его в цепочке нет вовсе, возвращать нечего, и постбэк будет уходить с пустым или чужим идентификатором.

Связка собирается из двух половин, и обе обязательны:

  1. На входе. Кампания Keitaro редиректит на вашу трекинг-ссылку Leadgram и кладёт свой click id в sub-параметр: ?sub1={subid}. Здесь {subid} - макрос Keitaro; Leadgram примет его значение как обычный query-параметр и запишет в sub1 клика (до 255 символов, длиннее обрезается).
  2. На выходе. В правиле постбэка вы отдаёте этот же id обратно: https://your-keitaro.com/postback?subid={sub1}&status=lead. Здесь {sub1} - уже макрос Leadgram, и подставится ровно то, что пришло на клике.

Именно это подставляет пресет Keitaro в диалоге создания правила. Соблазн взять {click_id} понятен, но он не сработает: это внутренний id клика Leadgram, Keitaro его никогда не видел и сопоставить со своей сессией не может. {click_id} уместен, когда принимающая сторона - рекламодатель, который сам получил этот id от вас, а не трекер, стоявший в цепочке раньше.

status зашивается в URL правила константой, а не макросом. Keitaro понимает свой набор статусов (lead, sale, rejected), а триггерные события Leadgram называются иначе - {event_type} отдал бы туда строку вроде ftd, которую Keitaro не разберёт. Поэтому на каждый статус заводится своё правило со своим событием-триггером:

  • «Лид», «Регистрация» - status=lead
  • «Старт бота», «Вступление в канал» - status=lead, если считаете эти шаги лидом
  • «Депозит», FTD, «Покупка» - status=sale

Отдельного триггерного события под возврат или отклонённую конверсию у Leadgram нет, так что rejected проставляйте в Keitaro своими средствами.

Выплата постбэком не передаётся вообще: суммы нет ни в списке макросов, ни в JSON-теле POST-запроса. Деньги считайте на стороне Leadgram - передавайте payout в событии через API событий либо задайте «Выплату» на оффере, и конверсия унаследует её по офферу, привязанному к клику. Дальше эта сумма попадает в колонку «Доход» на странице Отчёты.

Доставка, ретраи и повторная отправка

На каждое срабатывание даётся 10 секунд; доставленным считается любой HTTP-статус от 200 до 399. Неудачное срабатывание повторяется ещё до 2 раз с нарастающей паузой (всего 3 попытки), и каждое срабатывание зеркалится в надёжный журнал на странице «Доставка конверсий»:

  • «В очереди» - поставлено, ещё не доставлено
  • «Отправлено» - эндпоинт ответил 200-399
  • «Сбой» - последняя попытка завершилась ошибкой, повторы ещё возможны
  • «Мёртвая» - все попытки исчерпаны; оживить может только ручная повторная отправка

«Доставка конверсий» открывается сводкой ещё до всех таблиц: по карточке на каждое правило и на каждое подключение к рекламной площадке, с бейджем статуса («Без проблем», «Есть сбои» или «Есть мёртвые») и счётчиками отправленных, сбойных, мёртвых и ожидающих доставок за последние 24 часа и за последние 7 дней. Это самый быстрый способ заметить, что правило сбоит, не читая таблицу построчно.

Ниже - таблица «Проблемные доставки» (вкладки CAPI | Постбэки): в ней перечислена каждая сбойная или мёртвая доставка с точным текстом ошибки, по 20 строк на страницу. Временным окном она не ограничена - это свойство только сводки выше; доставка, упавшая месяцы назад, будет висеть здесь, пока вы её не переотправите или она не пройдёт сама. «Переотправить» ставит доставку в очередь заново с тем же payload. Сначала почините эндпоинт, потом переотправляйте - ничего не теряется.

Гарантия дедупликации: одна и та же логическая конверсия никогда не уйдёт на ваш эндпоинт дважды. Дедупликация держится через ретраи очереди, краши и повторную обработку событий. Настоящая повторная конверсия (второй депозит, пришедший новым событием) сработает отдельно - как и должна.

Эта гарантия встроенная и работает всегда. Поверх неё лежит необязательная политика - селект «Дедупликация»: в диалоге создания он стоит между методом и областью, а у сохранённого правила меняется прямо в одноимённой колонке таблицы, без диалога. По умолчанию выбрано «Выкл - отправлять каждое событие». Три остальных режима - «Один раз на пользователя», «Один раз на пользователя на источник» и «Любой тип события - один раз на пользователя» - у постбэка означают одно и то же: одна отправка на пользователя Telegram за всю жизнь правила. Расходятся они только на стороне CAPI, где у одной кампании много подключений и много типов событий. У правила ключ всегда один и тот же: оно само себе источник данных и срабатывает ровно на одном типе события, так что схлопывать в нём нечего.

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

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

  • Правило показывает статус «Отключён» и не стреляет. Новые правила всегда создаются включёнными, так что отключил его кто-то осознанно - вернуть в строй можно тем же пунктом «Включить» в меню строки. Текущее состояние удобно смотреть фильтрами «Все / Активные / Отключённые».
  • Правило сузили не на ту кампанию. Оно включено, эндпоинт исправен, конверсии идут - а рекламодателю не приходит ничего: ни одна из них не попадает в область правила. Отказ молчит целиком. Правило, не совпавшее по области, не создаёт доставку вообще, поэтому в журнале нет ни сбоя, ни мёртвой строки, а на «Доставке конверсий» нет даже карточки - она появляется только у правила, по которому за 7 дней прошла хотя бы одна доставка. Кнопка «Тестовый запрос» в меню строки тоже промолчит: она дёргает ваш URL напрямую, мимо отбора правил по области, и отвечает зелёным независимо от того, стреляет правило на живом трафике или нет. Проверка одна - колонка «Область» в таблице постбэков: сверьте кампанию в ней с той, которой принадлежат клики, и поправьте область в «Изменить». Та же ошибка с другой стороны: конверсии кликов, пришедших вне кампании, видят только правила со значением «Все кампании».
  • Кампанию удалили - вместе с ней пропали правила, суженные на неё. Это не сбой, а осознанное решение: правило, привязанное к удалённой кампании, потеряло смысл, а сброс области во «Все кампании» тихо расширил бы его на весь остальной трафик организации, то есть вернул бы ровно ту ошибку, ради которой область и заводилась. Если адрес рекламодателя должен пережить кампанию, держите правило на «Все кампании» или заведите его заново под новую кампанию.
  • Внешний трекер стоит после Leadgram. Тогда его click id на клике не появится, {sub1} уедет пустым, и трекер не сопоставит конверсию. Порядок хопов правится только на стороне трекера, никакой настройкой правила это не лечится.
  • Имена макросов точные: {clickid} (без подчёркивания) не подставится и уйдёт в трекер как есть.
  • Только публичные http(s)-адреса: localhost и адреса приватных сетей отклоняются по соображениям безопасности. Эта проверка срабатывает при редактировании URL и при срабатывании правила, но не при первом создании - так что неверный URL может сохраниться и споткнуться только на реальном срабатывании.
  • Если ваш эндпоинт отвечает 4xx/5xx, срабатывание становится «Сбоем», а затем «Мёртвой». Проблема на принимающей стороне: почините её, потом переотправьте со страницы «Доставка конверсий».
  • Лимит - 50 правил постбэков на организацию.