TikTok CAPI: серверные конверсии и сквозной ttclid

Этот раздел описывает серверную передачу конверсий в TikTok (Events API) —
как её подключить к сайту, какие события уходят и как проверить, что всё
работает.

Что это и зачемЧто это и зачем

Обычный браузерный пиксель фиксирует события на странице. Но ключевые точки
воронки происходят после ухода с сайта — подписка в Telegram-боте, заявка,
оплата в CRM. Серверный API конверсий (CAPI) передаёт эти события напрямую с
нашего сервера в TikTok, «прошивая» по всему пути уникальный идентификатор
клика TikTok — ttclid.

Это даёт:

• корректную атрибуцию продажи к рекламному клику TikTok;
• кастомные отчёты и оптимизацию рекламы под реальные события (подписка,
  покупка), а не только клики;
• ретаргетинг по сегментам (подписался, но не купил и т. п.).

Как устроен путьКак устроен путь

1. Человек кликает по рекламной ссылке-воронке. TikTok дописывает ?ttclid=…
   к ссылке — мы захватываем этот ttclid в момент клика.
2. Идентификатор клика прошивается по всей воронке: лендинг → старт
   Telegram-бота → атрибуция контакта в CRM.
3. На важных точках сервер отправляет событие в TikTok Events API:
   • подписка в воронке → CompleteRegistration;
   • подтверждённая оплата в CRM → Purchase с суммой выручки и валютой.
4. Каждая доставка (успех/пропуск/ошибка) фиксируется в журнале и видна в
   интерфейсе.

Шаг 1. Создать пиксель в TikTok Events ManagerШаг 1. Создать пиксель в TikTok Events Manager

Для подключения нужны две вещи из TikTok: Pixel Code (идентификатор
пикселя) и Access Token (ключ Events API).

1. Войдите в TikTok Ads Manager → Tools (Инструменты) → Events
   Manager.
2. Нажмите Connect Data Source → выберите Web.
3. Выберите Manual Setup → TikTok Pixel + Events API → Next.
4. Задайте имя пикселя (удобно называть по домену/проекту). Создастся Pixel
   Code — например DA1ENRRC77UDVMNGCPG0.
5. В настройках пикселя откройте раздел Events API → Generate Access
   Token и скопируйте токен.

Шаг 2. Подключить пиксель к сайтуШаг 2. Подключить пиксель к сайту

Трекеры привязываются к конкретному сайту. К одному сайту можно привязать
несколько трекеров (Meta, TikTok, VK, Google) — TikTok лишь один из них.

1. Откройте Технический блок → Сайты и откройте нужный сайт.
2. Перейдите на шаг «Роботы и трекеры».
3. В блоке «Pixel Connections» → «Создать трекер для подписной»:
   • Провайдер — TikTok (Pixel + Events API);
   • включите «Server-side events / CAPI» (серверная отправка, нужен Access
     Token);
   • заполните TikTok Pixel Code и Access Token (из шага 1). У обоих
     полей есть подсказка ⓘ — где взять значение, со ссылкой на TikTok
     Events Manager;
   • нажмите «Создать и привязать».

Трекер привяжется к этому сайту. Для page-less воронок (прямая ссылка Telegram /
business_dm) привязка идёт к самому сайту-подписной — отдельная страница не
требуется.

В карточке трекера виден индикатор состояния: «CAPI активен» — серверная
отправка работает; «CAPI: токен не задан» — доставки не пойдут, добавьте
Access Token; «CAPI выкл.» — работает только браузерный пиксель.

Какие события уходятКакие события уходят

Активные маппинги видны прямо в карточке трекера — списком вида «Подписка →
CompleteRegistration», «Оплата → Purchase». Каждый маппинг можно включить
или выключить галочкой, не уходя из редактора сайта.

Точка воронки	Внутреннее событие	Событие TikTok	Данные
Подписка в Telegram-воронке	telegram_subscribe	CompleteRegistration	ttclid, идентификаторы пользователя
Подтверждённая оплата в CRM	payment_success	Purchase	ttclid, value (выручка), currency

• Purchase формируется, когда платёж по сделке переводится в статус
  confirmed (реализованная выручка). Событие идемпотентно по идентификатору
  платежа — повторное подтверждение не отправляет дубль.
• Если у контакта нет происхождения в рекламной воронке (пришёл не по
  ссылке-воронке), событие покупки не отправляется — атрибутировать его к клику
  TikTok нельзя.

Шаг 3. Проверить, что события уходятШаг 3. Проверить, что события уходят

Самый быстрый способ — кнопка «Тест» в карточке трекера: она отправляет
тестовый PageView через тот же серверный канал, что и реальные доставки
(для TikTok — Events API business-api.tiktok.com), и показывает ответ или
текст ошибки TikTok прямо в карточке. Кнопка активна, когда включён CAPI и
задан Access Token.

Последние доставки трекера доступны там же — ссылка «Последние доставки»
в карточке. Полный журнал событий и их доставок — в разделе «Реклама и
пиксели» сайта. Статусы доставки:

• sent — событие принято TikTok;
• skipped — событие не отправлено. Для TikTok частая причина —
  missing_ttclid: у события нет идентификатора клика, атрибутировать нечего;
• failed — TikTok отклонил запрос; в строке доставки виден код и текст ошибки
  TikTok (например, неверный токен → TikTok 401: … (code 40105)).

Официальная документация TikTokОфициальная документация TikTok

• Set up and Verify Pixel (создание пикселя)
• Get Started with Events API (создание Access Token)
• About Events API (Help Center)
• Standard Events and Parameters
• Events API 2.0 — обзор (API reference)
• Портал документации TikTok API for Business

В разделах Events API 2.0 ищите подстраницы «Send TikTok Click ID (ttclid)»,
«Events API for CRM» и «Event Deduplication» — они соответствуют тому,
что описано выше (проброс ttclid, серверные события от CRM и дедупликация по
event_id).

Связанные разделыСвязанные разделы

• Сайты
• Аналитика