События и сессии

Как отправлять события, что SDK делает автоматически и почему данные не теряются при перезагрузке страницы. Подключение и настройка — на странице Web SDK: установка и инициализация.

Сессии

Отдельного API для сессий нет: SDK сам отправляет первый запрос сессии при инициализации и дальше ведёт учёт сессий автоматически.

Идентификатор web_uuid

web_uuid — идентификатор, который SDK генерирует при первом запуске и хранит в браузерном хранилище. Он идентифицирует конкретный браузер на конкретном устройстве: один и тот же человек в другом браузере или после очистки данных сайта получит новый web_uuid.

const uuid = Tracehub.getWebUUID();           // string | null | undefined
const uuid = await Tracehub.waitForWebUUID(); // дождаться генерации

Если у вас есть собственный идентификатор пользователя, передайте его в externalDeviceId при инициализации — он будет отправляться вместе с данными SDK.

События

Каждому событию нужен токен (eventToken) — идентификатор, который вы задаёте сами в коде. Карточка события появляется в каталоге сама — обычно через несколько секунд после первой отправки из SDK, в разделе События (колонка «Токен»); завести событие заранее нельзя. Если карточки нет, обновите страницу; иногда она появляется только после следующей отправки того же события. В карточке событию можно задать читаемое название. Держите токены в коде стабильными: событие с изменённым токеном считается новым, история старого не переедет.

Tracehub.trackEvent({
  eventToken: "abc123",
  deduplicationId: "order-99",
  revenue: 9.99,
  currency: "USD",
  callbackParams: [{ key: "level", value: "5" }],
  partnerParams:  [{ key: "segment", value: "vip" }],
});

Параметр	Тип	Обязателен	Описание
eventToken	string	да	Токен события — идентификатор, который вы задаёте сами (см. выше).
revenue	number	нет	Сумма дохода.
currency	string	нет	Код валюты, например "USD".
deduplicationId	string	нет	Идентификатор для защиты от дублей (см. ниже).
callbackParams	{ key, value }[]	нет	Дополнительные пары ключ-значение при событии (см. ниже).
partnerParams	{ key, value }[]	нет	Дополнительные пары ключ-значение при событии (см. ниже).

trackEvent возвращает Promise: он резолвится, когда событие добавлено в очередь (не когда доставлено на сервер), и реджектится, если SDK не инициализирован или отключён. Вызывать trackEvent сразу после initSdk можно — вызов дождётся готовности SDK.

Доход

Чтобы событие учитывалось как доход, передайте revenue и currency. Такое событие попадёт в метрики дохода в кабинете. Сумма и валюта передаются только вместе: без валюты доход не будет учтён — всегда заполняйте оба поля.

Дедупликация

Если одно и то же событие может отправиться дважды (повторный клик, перезагрузка страницы на «спасибо за заказ»), передавайте deduplicationId — например, номер заказа. SDK помнит последние 10 идентификаторов (лимит настраивается параметром eventDeduplicationListLimit) и пропускает событие с повторным deduplicationId.

Лимит скользящий

Дубликат распознаётся, только пока его deduplicationId ещё в списке последних. Если между дублями прошло больше событий, чем помещается в лимит, второе событие будет засчитано.

Дополнительные параметры события

callbackParams и partnerParams — произвольные пары ключ-значение, которые вы прикладываете к событию. Куда они попадают:

Куда попадают	Ответ
Постбэки рекламным сетям	Нет
Выгрузка из кабинета	Нет
Фильтр и разбивка в отчётах	Да, после включения индексации

Чтобы параметр стал доступен в отчётах, откройте карточку события в разделе События и включите для него переключатель «Индексировать». История до включения не покрывается: в отчётах будут видны только значения, пришедшие после.

Глобальные параметры

Глобальные параметры прикрепляются к каждому отправляемому событию и переживают перезапуски SDK. Ведут они себя так же, как callbackParams и partnerParams при отдельном событии (см. выше):

Tracehub.addGlobalCallbackParameters([{ key: "env", value: "prod" }]);
Tracehub.removeGlobalCallbackParameter("env");
Tracehub.clearGlobalCallbackParameters();

Tracehub.addGlobalPartnerParameters([{ key: "segment", value: "vip" }]);
Tracehub.removeGlobalPartnerParameter("segment");
Tracehub.clearGlobalPartnerParameters();

Очередь запросов

Все запросы SDK проходят через очередь в браузерном хранилище (IndexedDB, при недоступности — LocalStorage). Поэтому:

• перезагрузка или закрытие вкладки не теряет неотправленные события — они уйдут при следующем запуске SDK;
• при сетевых ошибках SDK повторяет отправку с экспоненциально растущими паузами.

Что SDK хранит в браузере:

Данные	Назначение
Очередь запросов	Неотправленные HTTP-запросы — переживают перезагрузку страницы
Состояние активности	Метрики сессии, web_uuid, атрибуция
Глобальные параметры	Callback- и партнёрские параметры
Список дедупликации	Последние deduplicationId
Настройки	Состояние включения SDK, флаги передачи данных третьим сторонам

Очистка данных сайта обнуляет SDK

Вместе с очередью удаляется и web_uuid — после очистки посетитель будет считаться новым.

Офлайн-режим и управление состоянием

Метод	Что делает
Tracehub.stop()	Отключает SDK, дождавшись очистки очереди.
Tracehub.restart()	Включает SDK после stop().
Tracehub.switchToOfflineMode()	Копит запросы в очереди, не отправляя их (независимо от реального подключения).
Tracehub.switchBackToOnlineMode()	Отправляет накопленную очередь и возвращает обычный режим.

Атрибуция

Данные атрибуции доступны из SDK:

// синхронно — null, если атрибуция ещё не получена
const attr = Tracehub.getAttribution();

// асинхронно — резолвится, когда атрибуция получена
const attr = await Tracehub.waitForAttribution();

Поля объекта атрибуции:

Поле	Описание
thid	Идентификатор устройства в Tracehub
tracker_token	Токен трекинг-ссылки
tracker_name	Название трекинг-ссылки
network	Источник (рекламный кабинет), которому атрибутирован пользователь
campaign	Кампания
adgroup	Группа объявлений
creative	Объявление
click_label	Метка клика
state	Состояние атрибуции: installed, reattributed или organic

Чтобы реагировать на изменение атрибуции без опроса, передайте attributionCallback в initSdk (см. страницу Web SDK: установка и инициализация).

Реферер и клик по диплинку

Если посетитель пришёл на страницу по ссылке, которую нужно засчитать как клик (например, по диплинку), передайте её SDK:

// можно вызвать до initSdk — SDK отложит выполнение до готовности
Tracehub.setReferrer("https://app.tracehub.ru/deep?token=XYZ");

Где в кабинете видны данные с сайта

Веб-трафик попадает в то же приложение, чей appToken указан в initSdk, и помечается платформой «web».

Где	Что доступно
Отчёты	Срез и группировка «Платформа» со значением «web»
Когорты	То же: срез и группировка по платформе
События	Карточки событий и счётчики — вместе с мобильными
Экспорт	Выгрузка с колонкой платформы
Антифрод	Готовый фильтр «Веб»

Веб-трафик отбирается разрезом «Платформа»

На дашборде, в отчётах и когортах отдельного фильтра «Веб» нет: выберите разрез или группировку «Платформа» и смотрите строку со значением «web». Готовый фильтр «Веб» есть в разделе Антифрод.

---