В этой статье вы узнаете, как коннектор Telegram Ads выгружает данные в хранилище ROMI center: с какой периодичностью, как устроен обход кабинета и откуда берутся UTM-метки. Полный список полей — в статье Telegram Ads: описание выгружаемых полей.
Главное отличие: у Telegram Ads нет API
Telegram не отдаёт статистику рекламы через API, поэтому коннектор работает как робот в личном кабинете ads.telegram.org: заходит под сохранённой сессией и забирает данные так же, как это делал бы человек — список объявлений аккаунта, CSV-выгрузки показов/кликов/подписок и потраченного бюджета по каждому объявлению, карточку объявления с настройками.
Из этого вытекают все остальные особенности: выгрузка медленная и зависит от вёрстки кабинета.
Важно
Доступ общий, а не клиентский. Сессия берётся из служебного справочника активных доступов Telegram, а конкретный рекламный аккаунт выбирается подстановкой его логина. Если активный доступ протух, перестают выгружаться все подключения Telegram Ads сразу, а не одно.
Периодичность
Выгрузка идёт раз в сутки. Окно урезано до двух дней — «вчера» и «сегодня минус 7», без промежуточных дней (у остальных рекламных коннекторов перезагружаются все 7 дней подряд). Причина — длительность прогона: полный обход кабинета за каждый из семи дней занял бы недопустимо много времени.
Как собираются данные: перебор объявлений
- Из кабинета берётся список объявлений — столько, сколько кабинет отдаёт на странице.
- По каждому объявлению забираются две CSV-выгрузки (статистика и бюджет) и карточка объявления.
- Если в списке оказалось 100 объявлений или больше, включается перебор по идентификаторам вниз: кабинет показывает не всё, поэтому коннектор идёт от минимального известного идентификатора к первому, проверяя каждый.
- Идентификаторы, за которыми уже нет объявления, запоминаются в подключении и в следующие разы не проверяются.
Примечание
Чем дольше живёт рекламный аккаунт, тем дольше идёт выгрузка — список идентификаторов только растёт. Именно поэтому окно и урезано до двух дней.
Гранулярность данных: строка = объявление × день.
Как сохраняет данные
- Куда: хранилище ROMI center на движке ClickHouse.
- Имя таблицы:
telegram_ads_<транслитерированное название аккаунта>_<id подключения>. - Структура таблицы: движок
MergeTree, сортировка поstats_day, разбиение на партиции по дню статистики. - Порядок колонок: общие поля (
stats_day,utm_*,cost) → колонки конвертации валют → выбранные поля → служебныеrc_import_id,rc_created_at. - Структура догоняется, а не пересоздаётся. Недостающие колонки добавляются при очередной выгрузке, существующие не удаляются.
- Типы приводятся при записи: булевы — к «да/нет», дробные — к числу с плавающей точкой, целые — к целому.
Перезапись данных
Каждое задание перезаписывает свой день целиком: если строк нет, день пропускается и прежние данные сохраняются; если строки есть, весь день удаляется и записывается заново. Штатно так перезаписываются только два дня — «вчера» и «сегодня минус 7». Дни между ними остаются такими, какими были выгружены ранее.
Ручная перезагрузка за произвольный период доступна в кабинете и ставит задания на каждый день выбранного интервала — здесь ограничения в два дня нет. Учитывая скорость обхода кабинета, длинный интервал стоит запускать с запасом по времени. При включённой опции «удалить данные» таблица сносится целиком и создаётся заново первой же выгрузкой.
Дополнительные настройки
| Настройка | Что делает |
|---|---|
| Рекламный аккаунт | Аккаунт Telegram Ads, из которого забирается статистика. Его название входит в имя таблицы. |
| Выбор полей | Задаёт набор колонок таблицы. Восемь общих полей выгружаются всегда, остальные 14 включаются по выбору. |
| НДС | При включённой настройке ROMI center добавляет НДС к расходу по указанной ставке. |
| Конвертация валют | На каждую выбранную валюту добавляется колонка cost_converted_<валюта> — расход, пересчитанный по курсу на дату строки. Исходная валюта у Telegram Ads всегда евро. |
| UTM-метки для всех кампаний | Подменяет utm_source, utm_medium, utm_campaign заданными значениями во всех строках. |
| UTM-метки для выбранных объявлений | То же, но для конкретных объявлений: у Telegram Ads роль «кампании» играет объявление, по его идентификатору и идёт сопоставление. |
| Пауза коннектора | Останавливает создание новых заданий. |
Примечание
Настройка «Фильтр объявлений» осталась от старого интерфейса: новый визард её не задаёт и при каждом сохранении обнуляет.
Важно
Доступ перед выгрузкой не проверяется. У остальных площадок серии перед каждым прогоном проверяется живой токен. У Telegram Ads такой проверки нет: прогон стартует всегда, и если общая сессия протухла или аккаунт пропал из кабинета, робот просто не найдёт данных — задание завершится «успешно», но строк за день не будет, а прежние данные останутся нетронутыми (пустой ответ день не очищает). Отслеживать такие случаи нужно по отсутствию свежих строк, а не по статусу подключения.
Откуда берутся UTM-метки
Единственный источник — ссылка продвижения объявления: из неё берутся все параметры, чьё имя содержит utm. Значения по умолчанию, если в ссылке меток нет:
| Метка | Значение по умолчанию |
|---|---|
utm_source | rc-telegram |
utm_medium | rc-cpm |
utm_campaign | rc-(not set) |
utm_term | (not set) |
utm_content | (not set) |
utm_id | идентификатор объявления |
Дальше применяется пользовательская подмена из настроек подключения — она правит только utm_source, utm_medium и utm_campaign; utm_id, utm_term и utm_content остаются такими, какими пришли из ссылки. Макросов, как у других площадок, у Telegram Ads нет — подставлять в ссылку нечего.
Примечание
Предупреждения «данные пришли без UTM-меток» у Telegram Ads не бывает. Судить о качестве меток можно только по самим значениям в таблице: если в колонках стоят rc-telegram, rc-cpm и rc-(not set), значит в ссылке объявления меток не было.
Технические поля
| Поле | Тип | Что означает |
|---|---|---|
rc_import_id | Целое число | Идентификатор прогона выгрузки, которым записана строка. |
rc_created_at | Дата и время | Момент записи строки в хранилище (не время события). При перезаписи дня обновляется у всех строк дня. |
В таблицах Telegram Ads нет rc_updated_at и rc_datasource.
