TikTok Events API и пиксель: настройка и диагностика

TikTok Events API передаёт конверсии напрямую с сервера, пиксель собирает события в браузере. Каждый канал закрывает слабые места второго: блокировщики рекламы, ограничения cookies, потерянные идентификаторы. Этот гайд - вход в кластер измерения TikTok: что делает каждый канал, как их подключить, как дедупликация держит счётчики честными и куда смотреть, когда цифры расходятся.

Что такое пиксель TikTok и TikTok Events API

Пиксель TikTok - это JavaScript-фрагмент на сайте. Он отправляет веб-события в TikTok и питает соседние инструменты: оптимизацию кампаний, аудитории, измерение.

TikTok Events API решает ту же задачу на уровне server-to-server. Данные идут по трём каналам: web, app и offline (магазин, CRM), а состав передаваемых событий и полей вы определяете сами.

Совет самой платформы - держать Events API рядом с существующим пикселем, чтобы выжать максимум производительности. В типичной веб-воронке TikTok Events API не заменяет пиксель - он добавляет вторую, труднопотеряемую копию каждой конверсии.

Standalone или второй канал: какой режим выбрать

Standalone-интеграция шлёт события только через API, без браузерного пикселя. Схема второго канала оставляет пиксель в браузере и добавляет API сверху. Оба варианта описаны в документации; для веб-воронок рекомендован второй.

Проверить серверный конвейер до полного подключения можно через Pixel Activator: тестовые события в TikTok Events API без кода.

Пререквизиты: Pixel ID и access token для Events API

Два реквизита открывают всю настройку:

1. Код пикселя (Pixel ID) из TikTok Events Manager - идентификатор вашего веб-источника.
2. Access token - вызовы TikTok Events API 2.0 проходят аутентификацию по нему.

TikTok описывает два способа генерации токена; экраны в интерфейсе периодически переезжают, поэтому ориентируйтесь на текущий Events Manager, а не на старые скриншоты. Токен - секрет: кто его держит, тот может писать события в ваш источник данных.

Пошаговый разбор обоих значений - в гайде как найти TikTok Pixel ID и сгенерировать access token.

Настройка пикселя TikTok

Базовый путь подключения: Ads Manager, Tools, Events Manager, Connect Data Source, Web, URL сайта, выбор между Partner Integration и Manual Setup. Имя пикселя ограничено 128 символами с пробелами; TikTok советует привязывать имя к домену, чтобы аккаунт оставался читаемым.

Ставьте события всего пути клиента - просмотр товара, корзина, покупка - а не только финальную продажу. Оптимизация работает с тем, что видит.

Верификация - три инструмента: расширение Pixel Helper для Chrome, экран Test Events и вкладка Diagnostics внутри пикселя. Все три разобраны ниже, в разделе диагностики.

Настройка Events API

TikTok перечисляет три способа подключить TikTok Events API:

1. Commerce-партнёр - Shopify, WooCommerce и другие платформы с нативной связкой.
2. Data-партнёр - CDP, tag manager или CRM шлют события за вас.
3. Прямая интеграция - ваш бэкенд вызывает API сам; максимум контроля над payload.

После имплементации TikTok рекомендует провалидировать настройку через Web Diagnostics в Events Manager, прежде чем доверять данным.

Для третьего пути типовой транспорт - server container в GTM; пошаговая настройка - в гайде TikTok Events API через Google Tag Manager server-side. Если конверсии регистрирует трекер, а не сайт, смотрите TikTok Events API для аффилейт-трекеров.

Дедупликация событий: правило 5 минут и event_id

Дедупликация нужна, когда одно и то же событие идёт через оба канала. Если AddToCart стреляет в пикселе, а Purchase приходит через API, дедупить нечего. Как только вы запускаете схему второго канала с пересекающимися событиями, общий event_id становится обязательным: TikTok засчитывает первое пришедшее событие и игнорирует двойника.

Ключ сопоставления между каналами - связка event_id, имени события и pixel code. Дальше решает время:

• Копия, пришедшая в течение 5 минут от первой, мержится с ней: позднее событие дополняет первое недостающими полями.
• Копия, пришедшая позже 5 минут, но в пределах 48 часов от первой, дропается.
• Внутри одного канала (пиксель-пиксель или API-API) дедуплицируются пары с идентичными событием и event_id в том же окне 48 часов.

Значение event_id выбираете вы. Берите уникальное на конверсию - номер заказа подходит - и следите, чтобы оба канала отправили идентичную строку:

// Пиксель: номер заказа как event_id
ttq.track('Purchase', { value: 49.90, currency: 'USD', event_id: 'order-10247' });

// Events API: то же имя события, тот же event_id, ваш pixel code
{
  "event": "Purchase",
  "event_id": "order-10247",
  "pixel_code": "YOUR_PIXEL_CODE"
}

Проверка результата: на странице пикселя метрика Server & Browser показывает дедуплицированный счёт, где пара браузер-плюс-сервер считается за единицу. Значение выглядит заниженным - обычно виноват event_id, разный между каналами.

Advanced Matching: ручной или автоматический

Advanced Matching прикрепляет к событиям идентификаторы вроде email и телефона - неважно, пришли они через пиксель, Events API или партнёрскую платформу. Режима два, Manual и Automatic; TikTok рекомендует включать оба сразу, а для регулируемых отраслей (финансы, здоровье) оставлять только Manual.

Автоматический режим собирает то, что уже лежит на странице: email, телефон, имя, адрес до города, штата, индекса и страны, плюс external_id вроде клиентского номера или карты лояльности. Он читает поля ввода, статический текст и переменные сайта (window.dataLayer, window.utag), проверяет формат, хэширует SHA-256 в браузере посетителя и отправляет по HTTPS. Работает только на страницах с установленным пикселем и лучше всего там, где есть first-party данные: логин, регистрация, чекаут, подписки.

Ручной режим закрывает остальное: iFrame-окружения, сторонние логины и оплаты вроде PayPal или ShopPay, IMG-пиксели - там автоматике нечего читать.

Две привычки поднимают match rate: слать все поддерживаемые параметры клиента в каждом событии и забирать данные как можно раньше в воронке. First-party cookies должны быть включены - переключатель в настройках пикселя. Через API ключи матчинга - email, телефон и external_id, и все они должны приходить хэшированными.

Влияние на match rate разобрано в гайде по enhanced matching и match rate.

ttclid: как TikTok Click ID связывает события с рекламой

При клике по рекламе TikTok дописывает в URL лендинга tracking-параметр:

your-source.example/landing?utm_campaign=spring&ttclid=_CLICKID_

Каждый Click ID уникален и живёт согласно CTA window из Attribution Manager. Если событие из пикселя или API несёт Click ID, TikTok связывает его с действиями пользователя и использует связку для атрибуции, аудиторий, оптимизации доставки и измерения.

Авто-добавление не трогает ваши кастомные tracking-параметры; сам параметр убирается программно, как любой query-аргумент; финальный URL валидируется кнопкой Preview при создании объявления.

Если воронка живёт в постбек-трекере, ttclid обычно служит ключом стыковки; схема сборки показана в гайде по Keitaro postback для Facebook и TikTok.

Тестирование и диагностика: Test Events, Web Diagnostics, Pixel Helper

Три инструмента закрывают цикл проверки:

1. Pixel Helper - расширение Chrome, подтверждающее наличие и работу пикселя на странице.
2. Test Events - живая тестовая среда, имитирующая сайт внутри приложения TikTok; сайт открывается прямо в браузере, QR-код не нужен. Лента разделяет browser-side и server-side тестовые события; Events Manager добавляет инструкции для Pixel и API-тестов и Payload Helper для структурной проверки payload. Время показывается в local time или UTC.
3. Diagnostics - вкладка, ищущая проблемы интеграции, например отсутствующий content ID. Карточка содержит issue, severity, затронутый dataset, затронутые объявления и action item вроде "Enable first-party cookies". Путь: Ads Manager, Tools, Events, Diagnostics (все пиксели) или внутрь конкретного пикселя. Клик по issue раскрывает инструкции и сэмпл данных затронутых событий.

Change Log в Events Manager ведёт историю изменений конфигурации с пагинацией; его диапазон не привязан к reporting window.

Когда цифры расходятся: короткий путь диагностики

Когда Ads Manager, трекер и бэкенд рассказывают три разные истории, идите по списку:

1. Дедупликация - оба канала шлют то же событие с идентичным event_id? Низкий Server & Browser указывает на несовпадение.
2. Данные матчинга - email, телефон и external_id на месте и хэшированы? Потерянные идентификаторы топят атрибуцию.
3. ttclid - пережил ли лендинг редиректы с Click ID в строке?
4. Окно атрибуции - совпадает ли CTA window из Attribution Manager с тем, что считает трекер?
5. Здоровье каналов - Test Events показывает и browser-, и server-копии?

Если после этого прохода цифры всё ещё разъезжаются, разбор TikTok conversion discrepancy раскладывает каждый источник дрейфа по полкам.

миграция Events API 2.0.

Sources