OneTrace.pro Справка

Импорт файлов и источники данных

Если покупатели уже есть в другой системе — CRM, учётной программе, таблице, — их не нужно ждать на сайте: загрузите файл. Разовую загрузку профилей из CSV или Excel делает импорт, а регулярную подгрузку профилей и событий из файла по ссылке, S3, Google Таблицы или вашего хранилища данных — источники данных.

Оба инструмента доступны «Владельцу», «Администратору» и «Менеджеру».

Импорт профилей из CSV и Excel

Откройте Данные → Импорт профилей в меню или нажмите Импорт профилей в шапке страницы Профили.

Требования к файлу

  • CSV или Excel (.xlsx, .xls — первый лист) с заголовками колонок в первой строке.
  • Разделитель — запятая, точка с запятой или табуляция: определяется сам.
  • Размер — CSV до 20 МБ, Excel до 10 МБ.
  • Хотя бы одна колонка с идентификатором: id клиента в вашей системе, email, телефон.
  • В Excel ячейки с форматом даты загружаются как 2026-10-28 18:42:00, формулы — своим значением. Файлы Excel 95 и файлы с паролем не подходят: сохраните их как .xlsx или CSV.

Пример:

email;phone;Имя;Город;customer_id;bonus
[email protected];+7 999 123-45-67;Анна;Казань;1001;350

Как загрузить

  1. Нажмите Выбрать файл и выберите файл.
  2. В таблице появятся колонки файла, примеры значений и поле Куда. Укажите для каждой колонки:
    • Идентификатор: User ID, Email, Телефон или Anonymous ID — по нему профиль найдётся или создастся. Каждый тип можно выбрать один раз.
    • Трейт — свойство профиля; рядом введите ключ латиницей, например city или bonus_balance.
    • Пропустить — колонка не загружается.
  3. Нажмите Запустить импорт.

OneTrace.pro сам подсказывает назначение по заголовкам: email и «почта» — email, phone и «телефон» — телефон, customer_id и user_id — User ID, «Имя», «Фамилия», «Город», «Страна» — трейты first_name, last_name, city, country. Остальные заголовки становятся ключами трейтов транслитом. Проверьте подсказки перед запуском.

Импорт профилей: соответствие колонок файла

Ход импорта

Импорт идёт в фоне: на странице видны полоса прогресса, статус и счётчик «обработано N из M, ошибок: K». Страницу можно закрыть — импорт продолжится. Строки с ошибками перечислены с номерами. Когда импорт закончится, кнопка Открыть профили ведёт к списку профилей.

Справа, в блоке История, — последние 20 импортов: файл, кто и когда загружал, статус («Загружен», «В очереди», «Обрабатывается», «Готово», «Ошибка») и итог.

Страница импорта с историей загрузок

Как обрабатываются строки

  • Если профиль с таким идентификатором уже есть, он обновляется: новые трейты добавляются, совпадающие перезаписываются. Если в строке встретились идентификаторы двух разных профилей, профили склеиваются — см. Профили.
  • Пустые ячейки пропускаются и не стирают уже известные значения.
  • Числа и true/false сохраняются как числа и логические значения.
  • Email и телефон из файла становятся и идентификаторами, и трейтами профиля.
  • Телефон очищается от пробелов, скобок и дефисов. Указывайте его с кодом страны: +7 999 123-45-67. Номер вроде 8 999… будет сохранён с неверным кодом.
  • Строка, где нет ни одного правильного идентификатора, пропускается с ошибкой.

Импорт создаёт для каждой строки событие $identify, поэтому изменения трейтов могут запустить цепочки с триггером на изменение трейта. Если этого не нужно, поставьте такие цепочки на паузу на время импорта.

Источники данных

Источник — регулярный импорт по расписанию. Подходит, когда CRM или склад каждую ночь выкладывает свежую выгрузку: OneTrace.pro сам заберёт её и обновит профили или добавит события.

Подготовка

Сначала создайте подключение в разделе Интеграции (нужна роль «Администратор» или «Владелец»):

  • Файл по ссылке — файл по адресу HTTP(S). Если файл закрыт, укажите заголовок авторизации, например Bearer и токен.
  • Файл из S3 — бакет AWS, Yandex Object Storage, MinIO и других совместимых хранилищ.
  • Google Таблица — по ключу сервисного аккаунта Google. Откройте этому аккаунту доступ к таблице на чтение.
  • PostgreSQL, ClickHouse, BigQuery или Snowflake — таблица или запрос в вашем хранилище данных, см. Хранилище данных.

Форматы файлов: CSV, JSON (массив объектов, до 50 МБ) и JSON Lines.

Как создать источник

  1. Откройте Данные → Источники данных и нажмите Новый источник.
  2. Введите Название и выберите Подключение.
  3. Заполните настройки подключения: Адрес файла и Формат, Путь к файлу в бакете или ID таблицы и Диапазон (например, Лист1!A:F).
  4. Нажмите Загрузить колонки — OneTrace.pro прочитает первые строки.
  5. В поле Что импортировать выберите Профили (каждая строка обновляет трейты) или События (каждая строка — событие).
  6. Выберите Расписание: от каждых 15 минут до раза в сутки.
  7. В таблице Колонки укажите назначение каждой колонки, как при импорте CSV.
  8. Нажмите Сохранить.

Настройки источника данных с соответствием колонок

Для событий в таблице колонок есть ещё Имя события, Свойство события и Время события. Колонка со временем обязательна. Имя события задайте одно для всех строк в поле Имя события (например, order_completed) или выберите колонку, в которой оно записано.

Для чеков из магазинов есть шаблон Офлайн-чеки с примером файла: он заполняет событие покупки, свойство офлайн-покупки и подсказки колонок — телефон, карта лояльности, магазин, номер чека, сумма и товары. См. Магазины и офлайн-продажи.

Работа источника

В карточке источника видны статус («Работает», «На паузе», «Ошибка»), расписание, время последнего запуска и итог: строк, принято, пропущено, с ошибкой.

  • Запустить — внеочередной запуск. Он же возвращает источник из паузы и ошибки.
  • Пауза / Возобновить — остановить и продолжить запуски по расписанию.
  • История — список запусков: начало, как запущен («По расписанию» или «Вручную»), статус и первые ошибки строк с номерами.

Источники данных: карточки со статусом и итогом запусков

Что важно знать

  • Если файл не изменился с прошлого раза, запуск завершается со статусом «Без изменений» и строки не читаются.
  • Повтор той же строки в течение суток не создаёт дублей.
  • Для событий запоминается время последнего загруженного события: следующие запуски пропускают строки не новее него. Поэтому файл с историей можно просто дописывать.
  • Источник с ошибкой повторяется по расписанию, текст ошибки виден в карточке.
  • Загруженные события учитываются в месячной квоте тарифа.
  • При удалении источника уже загруженные данные остаются.

Хранилище данных

Если профили и заказы уже собраны в вашем хранилище — PostgreSQL, ClickHouse, BigQuery или Snowflake, — источник читает их прямо оттуда. Каждый запуск забирает только строки, изменённые с прошлого раза, поэтому даже большую таблицу не нужно выгружать в файл. Изменения попадают в профили и события, а по ним срабатывают цепочки и пересчитываются сегменты. Обратное направление — выгрузка в хранилища.

Чтение из хранилищ доступно на тарифе «Корпоративный», см. Тарифы.

Подключение

Создайте подключение в разделе Интеграции, в группе Источники данных. Поля те же, что у выгрузки в это хранилище, но лучше завести отдельного пользователя только для чтения:

  • PostgreSQL — хост, порт, база, пользователь с правом SELECT на нужные таблицы.
  • ClickHouse — адрес HTTP-интерфейса, пользователь с правом чтения.
  • BigQuery — ключ сервисного аккаунта с ролями BigQuery Data Viewer и BigQuery Job User, проект и расположение данных.
  • Snowflake — аккаунт, пользователь с ключевой парой, роль с правом SELECT и вычислительный кластер (warehouse). Бакет S3 для чтения не нужен.

Хранилище должно быть доступно из интернета: адреса внутренних сетей OneTrace.pro не открывает.

Настройки источника

Создайте источник, как описано выше, и выберите подключение к хранилищу. Его настройки:

  • Что читать — Таблица (например, public.customers или shop_dwh.customers) или Свой запрос — SELECT или WITH одной командой без ;. OneTrace.pro добавляет к запросу условие, порядок и предел строк, поэтому изменить данные через него нельзя.
  • Колонка курсора — время изменения строки, например updated_at. Каждый запуск читает строки, у которых оно позже прошлого. Строки без этого времени не читаются.
  • Ключ строки — уникальная колонка, например id или customer_id. По ней различаются строки с одинаковым временем изменения.
  • Колонка признака удаления — необязательно, например is_deleted. См. Удаление.

Источник из хранилища BigQuery: таблица, курсор, ключ строки и колонки

Дальше всё как у файла: Загрузить колонки, назначение колонок, профили или события, расписание.

Как читаются изменения

  • Первый запуск читает всю таблицу, следующие — только строки, изменённые после последней прочитанной.
  • За один запуск читается не больше 1 млн строк. Если строк больше, следующий запуск начинается сразу, не дожидаясь расписания, — так первая загрузка большой таблицы идёт подряд несколькими запусками.
  • Если запуск прервался, те же строки прочитаются заново: профили просто обновятся ещё раз, а повторные события не задвоятся.
  • Смена таблицы, запроса, колонки курсора или ключа начинает чтение сначала.
  • Колонку времени изменения должно обновлять ваше хранилище: строку, у которой время не сдвинулось, OneTrace.pro не перечитает.
  • Запрос выполняется только на чтение и с ограничением времени — 10 минут в PostgreSQL, ClickHouse и Snowflake, 15 минут в BigQuery.

Удаление

Если в строке источника профилей в Колонке признака удаления стоит true или 1, OneTrace.pro удаляет профиль с идентификаторами этой строки, как по запросу GDPR: вместе с историей, склеенными профилями и данными в выгрузках. Удаление записывается в журнал действий, а в итоге запуска видно, сколько профилей удалено. В источнике событий строки с признаком просто пропускаются.

Для разового переезда с Mindbox и других платформ вместе с историей есть отдельный инструмент — см. Переезд с других платформ.