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

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

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

Як це працює

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

Постбеки спрацьовують лише для подій, які пройшли білінг. Конверсія отримує статус charged або free ще до того, як до неї дістаються ваші правила: платно проходить лише перша білінг-подія підписника, усі наступні події від нього безкоштовні. Якщо в момент цього першого списання організація на паузі або без балансу, подія натомість падає в статус blocked, і постбек по ній не спрацьовує; події від підписників, за яких ви вже платили, лишаються безкоштовними й продовжують спрацьовувати. Окремого статусу для цього на самому правилі немає, тож якщо правило, яке мало б стріляти, раптом замовкло - спершу перевірте баланс організації, а вже потім розбирайтеся з 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
  • «Збій» - остання спроба впала, ретраї ще можливі
  • «Мертва» - усі спроби вичерпано; оживить лише ручне повторне відправлення

Сторінка «Доставка конверсій» показує зведення про стан ще до того, як ви дістанетесь до будь-якої таблиці: одна картка на кожне правило й на кожне підключення до рекламного майданчика, зі статус-беджем («Без проблем», «Є збої» або «Є мертві») плюс лічильники sent/failed/dead/pending за останні 24 години та за останні 7 днів. Це найшвидший спосіб помітити, що з правилом щось не так, не перечитуючи кожен рядок окремо.

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

Гарантія дедуплікації: одна й та сама логічна конверсія ніколи не піде у ваш ендпоінт двічі. Дедуплікація тримається крізь ретраї черги, краші й повторну обробку подій. Справжня нова повторна конверсія (наприклад, другий депозит, зафіксований як нова подія) відпрацює знову, як і має.

Ця гарантія вбудована й працює завжди. Поверх неї лежить необов'язкова політика - селект «Дедуплікація»: у діалозі створення він стоїть між методом і охопленням, а в збереженого правила міняється просто в однойменній колонці таблиці, без діалогу. За замовчуванням вибрано «Вимк - надсилати кожну подію». Три інших режими - «Один раз на користувача», «Один раз на користувача на джерело» і «Будь-який тип події - один раз на користувача» - для постбека означають одне й те саме: одне надсилання на користувача Telegram за все життя правила. Розходяться вони лише на боці CAPI, де в однієї кампанії багато підключень і багато типів подій. У правила ключ завжди той самий: воно саме собі джерело даних і спрацьовує рівно на одному типі події, тож схлопувати в ньому нема чого.

Увімкнений режим скасовує застереження абзацом вище: другий депозит тієї самої людини за цим правилом уже не піде. Терміну придатності в зайнятого слота немає, добового скидання теж; звільняється він єдиним способом - коли надсилання померло остаточно, тож збій чужу конверсію не з'їдає. Подію, за якою не стоїть користувач Telegram, дедуплікація пропускає: ключ для неї нема з чого побудувати. Утримане надсилання - не помилка: у журналі воно отримує статус «Придушено», не ретраїться і в таблицю проблемних доставок не потрапляє.

Часті граблі

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