Как устроена миграция TikTok Events API на единый эндпоинт

С чего начинается миграция TikTok Events API

Миграция TikTok Events API начинается с выбора документированного /event/track/. Events API 2.0 поддерживает источники web, app, offline и CRM. В адресе https://business-api.tiktok.com/open_api/v1.3/event/track/ строка v1.3 относится к версии Marketing API, а 2.0 к поколению продукта. Эти обозначения не противоречат друг другу.

Используйте адрес из документации выбранного метода. Будущий путь эндпоинта нельзя выводить из номера поколения продукта.

Как читать список старых эндпоинтов

В обзоре перечислены /pixel/track/, /pixel/batch/, /offline/track/, /offline/batch/, /app/track/ и /app/batch/. Упоминание H2 2024 относится к прежнему плану перехода. Оно не является новым сроком отключения и само по себе не устанавливает, работает ли старый маршрут сейчас.

Единый маршрут API событий различает источники через event_source, но требования к остальным полям зависят от источника. Постбэк не становится офлайн-событием только из-за серверной отправки. Определите реальное действие и сверьте его спецификацию; при отказе поможет разбор ошибок интеграции.

Проверьте верхний уровень и поля источника

event_source принимает web, app, offline или crm. Поле event_source_id указывает источник, а data содержит события. Обязательные и рекомендованные поля внутри события проверяйте по спецификации этого источника. Общий пример не заменяет её.

В примере обзора используются user.email, user.phone, user.ip и user.user_agent: email и телефон показаны хешированными, IP и user agent без хеша. Точные правила нормализации и хеширования задаёт описание поля. Общий принцип разобран в хешировании данных пользователя для CAPI, но названия полей Meta переносить нельзя.

Для веб-действия, отправляемого через Pixel и API, проверьте идентичность события и условия дедупликации. Сам event_id не доказывает сопоставление или атрибуцию. В статье о дедупликации пикселя и CAPI Meta описан отдельный контракт. Объекты источника, сумму, валюту и поля приватности сверяйте непосредственно с нужной спецификацией TikTok.

Адрес, токен и частота запросов

Адрес метода: https://business-api.tiktok.com/open_api/v1.3/event/track/, заголовок авторизации: Access-Token. Токен можно получить в Events Manager или через приложение разработчика. Подробнее в руководстве по идентификатору пикселя и токену.

Обзор задаёт 1 000 QPS на рекламный аккаунт при токене Events Manager либо на приложение разработчика при его токене. Рекомендована отправка по одному событию сразу после получения. Максимальный размер пакета из QPS не следует: прежде чем использовать пакетную отправку, проверьте её спецификацию.

Минимальный запрос веб-события содержит поля верхнего уровня и одно событие:

{
  "event_source": "web",
  "event_source_id": "<pixel-code>",
  "data": [
    {
      "event": "Purchase",
      "event_time": 1769000000,
      "event_id": "Purchase_1769000000_a1b2c3d4",
      "user": { "ip": "<visitor-ip>", "user_agent": "<visitor-ua>" },
      "properties": { "value": 12.5, "currency": "USD" }
    }
  ]
}

Форма соответствует документированной структуре запроса; значения здесь заполнители. Поле page.url опущено: сайт не входит в сам запрос, а event_time передаётся в Unix-секундах. Успешный ответ выглядит так: {"code": 0, "message": "OK", "request_id": "…"}.

HTTP 200 вместе с code: 0 в теле означает успешное получение API-запроса. Проверяйте и HTTP-статус, и тело ответа. Получение не подтверждает сопоставление, дедупликацию, атрибуцию или появление в отчёте кампании.

Перенесите существующую интеграцию

Опишите каждую старую интеграцию перед переходом на /event/track/. Выберите документированное значение event_source для фактического действия, сохраните нужный event_source_id и соберите data по обязательным и рекомендованным полям этого источника. Серверное происхождение постбэка само по себе не делает событие офлайн-событием.

TikTok допускает самостоятельную настройку Events API или связку с Pixel. Для сайта рекомендованы два канала, Pixel и API; это не общее требование пикселя для приложений, офлайна и CRM. При отправке двух копий веб-действия сохраняйте идентичность события и соблюдайте контракт дедупликации TikTok.

Отправьте контролируемый тест, изучите HTTP-ответ и code: 0, затем диагностику нужного источника. Рабочее получение, сопоставление, дедупликацию и отчётность проверяйте отдельно перед завершением миграции. Связанные инструкции: отправка событий TikTok и Events API Gateway.

Источники