События (Events)

События — это основа аналитики в Metriox. Каждое действие пользователя в вашем Telegram-боте может быть записано как событие.

Что такое событие?

Событие — это любое действие или взаимодействие пользователя с вашим ботом:

• Нажатие на кнопку
• Отправка команды
• Просмотр экрана
• Завершение покупки
• Любое кастомное действие

Структура события

События в Metriox платформо-агностичны и состоят из:

Базовые поля

Поле	Тип	Описание
event_id	UUID	Уникальный идентификатор события
event_name	String	Название события (например, button_click)
platform_user_id	String	ID пользователя в Telegram
session_id	UUID	ID сессии пользователя
tenant_id	UUID	ID вашего проекта в Metriox
received_at	DateTime	Время получения события сервером
created_at	DateTime	Время создания события

Дополнительные поля

• body (String, nullable) — текстовое содержимое события
• props (JSON) — произвольные свойства события в формате JSON

Свойства события (Properties)

Свойства — это дополнительная информация о событии, которая позволяет более детально анализировать поведение пользователей.

Примеры свойств:

{
  "button_name": "купить_подписку",
  "plan": "premium",
  "price": 299,
  "currency": "RUB",
  "screen_name": "pricing"
}

Типы свойств

Metriox поддерживает следующие терминальные типы данных:

• String — текстовые значения
• Number — числовые значения (integer, float)
• DateTime — дата и время
• Boolean — true/false

Совет

Используйте понятные названия для событий и свойств. Например, вместо btn_1_click используйте subscription_button_click.

Примеры событий

Простое событие

{
  "event_name": "bot_started",
  "platform_user_id": "123456789",
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Событие со свойствами

{
  "event_name": "purchase_completed",
  "platform_user_id": "123456789",
  "props": {
    "product_id": "premium_month",
    "amount": 299,
    "currency": "RUB",
    "payment_method": "telegram_stars"
  }
}

Событие с телом

{
  "event_name": "message_sent",
  "platform_user_id": "123456789",
  "body": "/start premium",
  "props": {
    "command": "/start",
    "parameter": "premium"
  }
}

Отправка событий

События можно отправлять несколькими способами:

1. SDK — используйте официальные SDK для Python, Node.js и других языков
2. API — отправляйте события через REST API
3. Автоматически — некоторые события собираются автоматически при подключении бота

Лучшие практики

✅ Рекомендуется

• Используйте snake_case для названий событий: button_click, purchase_completed
• Добавляйте контекстные свойства: screen_name, source, category
• Группируйте похожие события: button_click, link_click, card_click

❌ Не рекомендуется

• Слишком общие названия: click, action, event
• Отправка персональных данных в открытом виде
• Слишком много уникальных событий (лучше использовать свойства)

Что дальше?

• Типы данных — подробнее о поддерживаемых типах данных
• Дашборд — как визуализировать события
• Фильтры — как фильтровать события для анализа