Гайд - TikTok

TikTok Events API: серверні конверсії з Telegram-лійки

Браузерний піксель TikTok бачить клік і більше нічого. Старт бота, вступ у канал, депозит - усе це відбувається всередині Telegram, де піксель не працює, тож оптимізатор TikTok закуповує схожих на тих, хто тапнув, а не на тих, хто заплатив. Leadgram замикає петлю на сервері через Events API 2.0: кожна конверсія йде з нашого бекенду просто у ваш піксель, разом із TikTok Click ID.

Як це влаштовано

Leadgram надсилає по одній події на конверсію на https://business-api.tiktok.com/open_api/v1.3/event/track/ і авторизує запит токеном вашого акаунта в заголовку Access-Token. Піксель адресується своїм Pixel Code; поля рекламодавця в запиті немає взагалі.

Одна деталь визначає, як читати будь-яку звітність на цій сторінці: у TikTok HTTP 200 не означає, що подію прийнято. Вердикт лежить у тілі відповіді, у полі code, і в додатку самого TikTok сказано, що код повернення важливіший за HTTP-статус - відповідь 200 із code: 40002 це невдалий виклик. Leadgram розбирає тіло, тож відхилена конверсія записується як помилка, а не як відправлення. Відмови, яких повтор не виправить (відкликаний токен, чужий піксель, відхилений пейлоад), зупиняються після першої спроби, а не випалюють усі п'ять.

Що підготувати в TikTok

  1. Відкрийте піксель в Events Manager (Assets → Events → Web Events). Візьміть наявний або створіть новий і виберіть спосіб підключення Events API.
  2. Скопіюйте Pixel Code. Саме цей ідентифікатор Leadgram надсилає як event_source_id - не ID рекламодавця і не ID кампанії.
  3. Випустіть access token із правами на цей піксель за інструкцією TikTok щодо автентифікації Events API 2.0. Токен прив'язаний до пікселя, тож у кожного пікселя він свій.
  4. Перевірте вікно атрибуції. TikTok прирівнює строк життя ttclid до CTA-вікна, яке ви задали в Attribution Manager. Leadgram сам клік не «протерміновує», тож діє лише вікно з вашого рекламного кабінету.

Заведіть акаунт у Leadgram

  1. На сторінці TikTok у розділі рекламних платформ натисніть Додати акаунт.
  2. Назва акаунта - внутрішня мітка, за якою ви його впізнаєте.
  3. ID пікселя - той самий Pixel Code із кроку 2 вище.
  4. Advertiser ID - необов'язковий і потрібен лише вам для обліку. Events API адресує піксель за Pixel Code, тож у запит це значення не потрапляє ніколи.
  5. Access token - зберігається зашифрованим; інтерфейс показує лише останні 4 символи.

Це вся форма: чотири поля, більше нічого. Тестового коду події та кнопки тестової конверсії в TikTok немає - ця пара існує лише для Meta. Перший доказ, що зв'язка працює, - справжня конверсія на сторінці Доставка конверсій, тож проженіть одну самі до того, як увімкнете трафік.

Прив'яжіть до кампанії

На сторінці Кампанії виберіть майданчик TikTok і впишіть той самий Pixel Code у поле TikTok у кампанії. Збіг має бути точним - саме за цим значенням Leadgram у момент надсилання знаходить потрібні облікові дані. Живий індикатор під полем підтверджує збіг просто під час введення, а банер після збереження повторює вердикт, тож одруківка не пройде мовчки.

Що саме надсилається

  • Ім'я події - виводиться з внутрішнього типу: registration → CompleteRegistration, deposit/ftd/purchase → Purchase, bot_start/lead → Lead, channel_join → Subscribe, join_request → SubmitApplication, first_dm → Contact, land/miniapp_launch → ViewContent, click → ClickButton. Заявка і вступ несуть різні імена навмисно: людина, яка подала заявку і потім була схвалена, рухає дві сходинки лійки, а не подвоює одну. Усе, чого в списку немає, у TikTok не йде взагалі: subscription_renewed, subscription_cancelled і custom_*. Така подія не створює доставки і не дає помилки - вона потрапляє в лічильник «Подія без маппінгу» на картці TikTok.
  • ClickButton - кастомна подія. Її немає в таблиці Web Standard Events, тож сирі кліки видно в Events Manager для звітності та аудиторій, але оптимізувати кампанію за ними TikTok не вміє. Усі інші імена вище - стандартні події.
  • ttclid - TikTok Click ID, спійманий вашим трекінговим посиланням, надсилається без хешування. Це єдиний ідентифікатор, за яким TikTok може нас зіставити, тож клік без нього пропускається, а не надсилається наосліп; пропуск видно на картці майданчика, а не як помилку.
  • external_id - SHA-256 від внутрішнього ID кліку Leadgram: хешування цього поля TikTok вимагає обов'язково. Само по собі воно користувача не зіставляє, а пов'язує події одного відвідувача.
  • Сума і валюта - лише на Purchase і лише у валюті зі списку, який TikTok підтримує. Невідома валюта змусила б TikTok відхилити всю подію цілком, тож Leadgram надсилає конверсію без суми, а не втрачає її.
  • Детермінований ID події дає дедуплікацію на боці TikTok: за збігу event_source_id, імені події та ID події протягом 48 годин лишається перша копія, решта відкидається. Усі ретраї Leadgram вкладаються в це вікно, тож повтор не може подвоїти конверсію.
  • Не надсилається: e-mail, телефон та IP. Перші два продукт не збирає, а TikTok чекає сиру публічну IP-адресу, тоді як ми зберігаємо лише її хеш. Надіслати хеш у поле, що чекає адресу, означає погіршити матчинг і збрехати про те, що ми маємо.

Як перевірити

Сторінка «Доставка конверсій» показує доставку в TikTok за секунди після події. На боці TikTok відкрийте вкладку Overview пікселя в Events Manager: щойно доїде перша серверна подія, у Connection Method з'явиться «Server».

Якщо доставок підозріло мало, спершу прочитайте на картці майданчика блок «Пропущено (не надіслано)». Він розбиває пропуски за причинами - немає click ID, подія без маппінгу, майданчик не підключено, - і за ним видно, де справжня діра, а де клік, який і не міг принести ttclid.

Часті граблі

  • У полі ID пікселя вставлено ID рекламодавця. Запит адресується за Pixel Code; ID рекламодавця в цьому полі не збігається ні з акаунтом, ні з кампанією.
  • Токен відкликано або протерміновано. TikTok відповідає кодом авторизації, і Leadgram позначає доставку невдалою з першої спроби, а не ретраїть хвилинами. Причина видна в рядку доставки: перевипустіть токен і надішліть повторно.
  • Meta і TikTok на одній кампанії. Клік, який приніс лише fbclid, на боці TikTok пропускається за задумом. Це не помилка, а клік, який TikTok і не зміг би зіставити, і він видно в тій самій розбивці пропусків.
  • Перевизначення імені події в кампанії. Поле Назва події TikTok у діалозі кампанії надсилає рівно те, що ви напишете, - і не для одного типу події, а одразу для всіх подій цієї кампанії, включно з click і land, тож уся воронка схлопується в один рядок в Events Manager. Ім'я поза стандартним списком TikTok прийме як кастомну подію: звітність і аудиторії за нею працюють, оптимізація - ні. Це єдине місце, де можна назвати типи custom_*, і братися за нього варто лише коли кампанія й так звітує про один вид конверсії.
  • Конверсії відхиляються з помилкою параметра. У таблиці параметрів TikTok об'єкт page позначено як обов'язковий для веб-подій, при цьому три з чотирьох офіційних прикладів веб-пейлоада його не містять. Leadgram page не надсилає: конверсія відбувається в Telegram, і URL сторінки взяти нізвідки. Якщо ваш піксель усе ж його вимагає, відмова буде видна в рядку доставки, а не мовчки - надішліть нам текст помилки.