Гайд - 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 страницы взять неоткуда. Если ваш пиксель всё же его требует, отказ будет виден в строке доставки, а не молча - пришлите нам текст ошибки.