Отслеживание событий

Имя события — это ключ, по которому вы его найдёте в отчётах через полгода. Договоритесь с командой об одной схеме и придерживайтесь её.

• snake_case — легче читать и писать, устойчиво к опечаткам
• Прошедшее время глагола — событие уже произошло
• Короткие имена — 2-3 слова достаточно
• Никогда не префикс $ — он зарезервирован для системных событий SDK

Любое событие содержит два типа свойств:

• Свойства события (передаются в track()) — относятся к конкретному действию: plan, amount, product_id. Меняются от события к событию.
• Свойства пользователя (передаются в identify() или setUserProperties()) — относятся ко всему пользователю: email, current_plan, registration_date. Изменяются по мере эволюции пользователя, последнее значение перезаписывает старое.

// Свойства конкретной покупки — в свойствах события
trektik.track('purchase_completed', {
  amount: 4990,
  currency: 'RUB',
  product_id: 'pro-month',
  discount_code: 'NEWYEAR',
});

// Атрибуты пользователя — в identify / setUserProperties
trektik.setUserProperties({
  current_plan: 'pro',
  total_spent: 24950,
});

Трекер автоматически делит свойства на строковые (str_properties в ClickHouse) и числовые (num_properties) — по числовым можно агрегировать без явных кастов.

Ограничение на размер одного события — 64 KB. Если в плане трекинга включён строгий режим и событие не описано в плане, сбор данных вернёт 400.

До логина пользователь анонимен — SDK генерирует device_id (UUID, хранится в localStorage). После регистрации или логина нужно вызвать identify() с внутренним user_id:

// В обработчике успешного логина
trektik.identify('user-123', {
  email: 'ivan@example.com',
  plan: 'pro',
  created_at: '2024-06-15',
});

Что произойдёт на бэкенде:

1. Создастся связь device_id → user_id в таблице identity_mappings
2. Все прошлые анонимные события этого устройства ретроспективно свяжутся с user-123
3. В отчётах новый пользователь не считается дважды (до и после identify)

SDK сам группирует события в сессии:

• Таймаут неактивности — 30 минут по умолчанию (настраивается через sessionTimeout)
• Каждое событие обновляет «последняя активность»; если прошло больше таймаута — начинается новая сессия
• При открытии новой вкладки/дня — $session_start, при истечении — $session_end
• session_id — это UTC-время старта сессии, уникальное для каждого устройства

В отчётах это даёт вам: сессии на пользователя, длительность сессии, страницы за сессию, показатель отказов. Воронки с окном «1 сессия» тоже используют этот механизм.

При autocapture: true SDK сам собирает четыре типа событий без вашего кода:

• $pageview — смена пути URL, включая SPA (React Router, Next.js App Router)
• $click — клики по кнопкам, ссылкам, контролам
• $form_submit — отправка форм
• $scroll_depth — глубина 25/50/75/100% на странице

init({
  apiKey: 'pk_...',
  // Вариант 1: всё включено
  autocapture: true,

  // Вариант 2: выборочно
  // autocapture: {
  //   pageViews: true,
  //   clicks: true,
  //   forms: false,
  //   scroll: false,
  // }
});

Когда полагаться на автозахват: для общей картины трафика (DAU, популярные страницы, точки входа/выхода).

Когда писать свои события: для ключевых бизнес-действий (signup_completed, purchase_completed, feature_used). Они выживают редизайны, в то время как $click на кнопке ломается при смене её селектора.

Отдельный метод revenue() формирует специальное событие $revenue с нужными полями для расчёта Ценность клиента, регулярная месячная выручка, выручка на пользователя и выручка на платящего пользователя:

trektik.revenue({
  amount: 4990,           // сумма
  currency: 'RUB',        // ISO-код
  productId: 'pro-month', // опционально
});

Для возвратов — отправьте revenue() с отрицательным amount или свойством revenue_type: 'refund'.

Чтобы не плодить мусор (опечатки, дубликаты вроде Signup и sign_up, события от разработчиков в проде) — заведите план трекинга в разделе Данные → Схема событий.

Для каждого события описываете: имя, описание, категорию, обязательные свойства. Два режима:

• Обычный режим — принимаются любые события, неописанные помечаются как незапланированные в разделе качества данных
• Строгий режим — сбор данных отклоняет неописанные события с кодом 400

В разделе качества данных автоматически подсвечиваются аномалии — неизвестные события и падение объёма трекаемых событий больше чем на 50%.

События, которые SDK отправляет автоматически. Все имена начинаются с $; это зарезервированный префикс.

Веб SDK (браузер)

Отслеживание фрустрации (если включено)

Гайды и опросы

Мобильные SDK

Каждое событие автоматически обогащается общими полями: идентификаторы (project_id, user_id, device_id, session_id), время, география (страна, город из IP), устройство (OS, browser, device_type), UTM-параметры, страница, версия SDK, хэш IP для приватности.