# TikTok Ads: как работает коннектор

В этой статье вы узнаете, как коннектор TikTok Ads выгружает данные в хранилище ROMI center: с какой периодичностью, какие есть ограничения по объёму и откуда берутся UTM-метки. Полный список полей — в статье [TikTok Ads: описание выгружаемых полей](https://help-ru.romi.center/tiktok-ads-opisanie-vygruzhaemyh-polej).

## Периодичность

Выгрузка идёт раз в сутки. Окно по умолчанию — от «сегодня минус 7 дней» до вчера включительно, по одному заданию на день. Текущий день не выгружается.

> **Примечание**
> В отличие от Яндекс Директа, Google Ads, VK Рекламы и Facebook, у TikTok нет отдельного диспетчера очереди — его задания разбирает общая поминутная команда вместе с остальными типами источников.

Гранулярность данных: строка = объявление × день. Уровни группы, кампании и рекламодателя попадают в ту же строку идентификаторами и названиями.

> **Важно**
> Ограничение TikTok в 10 000 объявлений. Отчёт отдаёт максимум 10 000 объявлений; при превышении коннектор останавливает выгрузку с ошибкой, а не режет данные молча. Автоматического обхода (разбивки по кампаниям), как у Facebook, здесь нет — крупному аккаунту потребуется фильтр кампаний.

## Как сохраняет данные

*   **Куда:** хранилище ROMI center на движке ClickHouse.
*   **Имя таблицы:** `tiktok_<транслитерированное имя рекламодателя>_<id подключения>`. Это единственный коннектор серии, где в имя таблицы попадает имя аккаунта, а не его идентификатор.
*   **Структура таблицы:** движок `MergeTree`, сортировка по `stats_day`, разбиение на партиции по дню статистики.
*   **Порядок колонок:** общие поля (`stats_day`, `utm_*`, `cost`) → колонки конвертации валют → выбранные поля → служебные `rc_import_id`, `rc_created_at`.
*   **Структура догоняется, а не пересоздаётся.** Недостающие колонки добавляются при очередной выгрузке, существующие не удаляются.

> **Примечание**
> Пустых значений в таблице не бывает: все поля, кроме общих, объявлены типом, не допускающим пустоту, поэтому там, где данных нет, окажется ноль или пустая строка. Значения `-`, которыми TikTok заполняет неприменимые поля, в таблицу тоже не попадают — в колонке останется ноль или пустая строка.

## Перезапись за 7 дней

TikTok уточняет статистику задним числом, поэтому каждую ночь перезагружаются последние 7 завершённых дней. Каждый день — отдельное задание: если строк нет, день пропускается и прежние данные сохраняются; если строки есть, весь день удаляется и записывается заново.

Ручная перезагрузка за произвольный период доступна в кабинете и ставит такие же посуточные задания. При включённой опции «удалить данные» таблица сносится целиком и создаётся заново первой же выгрузкой.

## Дополнительные настройки

| Настройка | Что делает |
| --- | --- |
| Рекламодатель | Рекламный аккаунт TikTok, из которого берётся статистика. Его имя входит в имя таблицы. |
| Выбор полей | Задаёт набор колонок таблицы. Показы и клики выгружаются всегда. |
| НДС | Расходы приходят из TikTok без НДС; при включённой настройке ROMI center добавляет его по указанной ставке. |
| Конвертация валют | На каждую выбранную валюту добавляется колонка `cost_converted_<валюта>` — расход, пересчитанный по курсу на дату строки. Исходная валюта — валюта рекламного аккаунта TikTok. |
| UTM-метки для всех кампаний | Подменяет `utm_source`, `utm_medium`, `utm_campaign` заданными значениями во всех строках. |
| UTM-метки для выбранных кампаний | То же, но покампанийно; индивидуальное значение приоритетнее общего. |
| Пауза коннектора | Останавливает создание новых заданий. |

> **Примечание**
> Настройка «Фильтр кампаний» осталась от старого интерфейса: новый визард её не задаёт и при каждом сохранении обнуляет. Для крупных аккаунтов это единственный способ уложиться в лимит 10 000 объявлений.

Истёкший или отозванный доступ переводит подключение в состояние ошибки; до починки выгрузка не идёт.

## Откуда берутся UTM-метки

Порядок сборки для одной строки:

1.  **Значения по умолчанию:** `rc-tiktok` (`utm_source`), `rc-cpc` (`utm_medium`), название кампании (`utm_campaign`; если названия нет — `rc-tiktok`), `term` (`utm_term`), `content` (`utm_content`), идентификатор кампании (`utm_id`).
2.  **Метки из адреса объявления** — разбирается строка запроса, найденные параметры перекрывают значения по умолчанию.
3.  **Пользовательские метки** из настроек подключения — общие или покампанийные.
4.  **Подстановка макросов TikTok** (`__CAMPAIGN_NAME__`, `_CAMPAIGN_ID_`, `_AID_` / `_AID_NAME_`, `_CID_` / `_CID_NAME_`, `_PLACEMENT_`) в получившихся значениях.

Метки проверяются по трём параметрам — `utm_source`, `utm_medium`, `utm_campaign`: не найден в адресе объявления или пуст — считается отсутствующим.

> **Примечание**
> Список кампаний с неполной разметкой у TikTok — накопительный и достоверный: в нём собраны все кампании, где меток не хватило, с указанием, каких именно. Предупреждение в кабинете по TikTok можно читать буквально — в отличие от некоторых других площадок серии.

## Технические поля

| Поле | Тип | Что означает |
| --- | --- | --- |
| `rc_import_id` | Целое число | Идентификатор прогона выгрузки, которым записана строка. |
| `rc_created_at` | Дата и время | Момент записи строки в хранилище (не время события). При перезаписи дня обновляется у всех строк дня. |

В таблицах TikTok нет `rc_updated_at` и `rc_datasource` — строки не обновляются точечно, а у каждого подключения своя таблица.