Миграция TikTok Events API: с шести эндпоинтов на один
Нейминг распутан: 2.0 - это продукт, v1.3 - версия API
Разговор о миграции TikTok Events API спотыкается о нейминг раньше, чем о код. "Events API 2.0" - имя TikTok для единого эндпоинта - /event/track/, - который передаёт события всех источников: web, app, offline и CRM. А v1.3 в URL документации и путях эндпоинтов - другая ось вообще: версия Marketing API, которую несёт путь. Собственная овервью-страница TikTok живёт по URL с обеими цифрами, а её curl-пример постит на https://business-api.tiktok.com/open_api/v1.3/event/track/ - эндпоинт 2.0, чей путь содержит v1.3. Читать "2.0" и "v1.3" как конкурирующие версии - самый быстрый способ сломать план миграции: одно - поколение продукта, другое - строка версии API.
Для арбитражной воронки различие практичное: ваша интеграция целится в эндпоинт 2.0 (один маршрут, единый payload), а префикс пути, где он живёт, - просто адресация, которая переедет с будущими версиями Marketing API.
Что заменяет единый эндпоинт
Events API 1.0 делил доставку по источникам: одна пара эндпоинтов для пиксельных событий, другая для офлайна, третья для app - каждая со своим диалектом payload. Овервью TikTok перечисляет все шесть как закрываемые в H2 2024: /pixel/track/ и /pixel/batch/, /offline/track/ и /offline/batch/, /app/track/ и /app/batch/. Рекомендация прямая - новым интеграциям стартовать на едином эндпоинте, а существующим пользователям 1.0 апгрейдиться как можно скорее.
Унификация важнее косметики. Воронка с трекером, которая отправляет веб-конверсии с лендинга и офлайн-подобные обновления статусов постбеком, раньше держала две интеграции с двумя схемами; на 2.0 обе едут через один маршрут events API, различаясь только полем event_source и своими обязательными объектами. Меньше поверхность схем - меньше классов интеграционных ошибок в учёте.
Схема payload 2.0
Конверт - структурное изменение против 1.0: три поля сидят над событиями. event_source принимает enum web, app, offline или crm; event_source_id несёт ID источника событий для измерения (пиксельный код для web); data - массив событий, по объекту на событие.
Внутри события: event называет конверсию (стандартную или кастомную), event_time - Unix-таймстамп, event_id настраивает дедупликацию с пикселем - дисциплина общего ключа из дедупликации пикселя и CAPI. Объект user несёт идентификаторы (примеры TikTok показывают хэшированные email и телефон рядом с сырыми ip и user agent - точные правила хэширования живут в спеке user parameters, а общая логика нормализации - в хэшировании CAPI user data), а properties описывает продукт или заказ.
Объекты под источники условные, но принудительные: page обязателен для web-событий, app - для app-событий, ad только для app, lead обязателен для CRM-событий. Булев limited_data_use существует только для источников web и app - флаг limited data processing в этой схеме.
Эндпоинт, авторизация и лимиты
URL - https://business-api.tiktok.com/open_api/v1.3/event/track/, авторизация - через заголовок Access-Token. TikTok рекомендует генерировать access token прямо в Events Manager вместо содержания developer app - тот же источник креденшела, что в гайде по pixel ID и access token. Успешный вызов возвращает HTTP 200 с кодом ответа API 0; ошибки приезжают как 4XX или 5XX с деталями в теле.
Ёмкость для воронки щедрая: эндпоинт принимает до 1,000 событий в одном запросе, rate limit - 1,000 QPS на рекламный аккаунт (или developer app, если токен оттуда). TikTok всё равно рекомендует одиночную отправку, как только сервер получил событие, - батчинг инструмент восстановления, а не дефолтная поза: свежие события кормят оптимизацию лучше всего.
Шаги миграции существующей воронки
Механический путь для интеграции, которая сегодня шлёт пиксельные события: направьте доставку на /event/track/, оберните payload в конверт с event_source: web и пиксельным кодом в event_source_id, разложите поля по объектам user, properties и page. Интеграция, которая также отправляла офлайн-обновления через /offline/track/, сворачивается на тот же маршрут с event_source: offline - один отправитель, одна схема. Передавайте клик-ID ttclid и значение куки _ttp ровно так, как предписывают гайды TikTok по клик-ID и куке, - пиксельный матчинг зависит от них.
Затем проверяйте до переключения трафика: отправьте одиночные тестовые события, подтвердите ответ code: 0 и проверьте в Events Manager прибытие событий под нужным пикселем. Если не хотите держать миграцию на себе вообще, MOST доставляет постбеки трекера в Events API TikTok вместе с Meta, Reddit, Pinterest, Snapchat и OpenAI на актуальной схеме, а бесплатный Pixel Activator закрывает доставку в TikTok для одного лендинга - или путь Events API Gateway, если вы оперируете многими аккаунтами.