🏷️ Метаданные событий

Добавьте бизнес-логику к вашим событиям — отмечайте заказы, стройте воронки, настраивайте отображение

🎯 Для чего это нужно?

Метаданные событий позволяют InstantBase понимать, какие события важны для бизнеса. Без них мы видим просто поток действий. С ними мы знаем, что является заказом, что активацией, как выглядит воронка продаж.

Синтаксис

Метаданные передаются в поле _metadata при отправке события:

json 
{
  "event": "purchase",
  "user_id": "user_123",
  "properties": {
    "revenue": 1499.99
  },
  "_metadata": {
    "is_order": true,
    "funnel_sales_step": 4,
    "funnel_sales_name": "Покупка",
    "event_display_name": "Завершенный заказ",
    "event_color": "#28a745",
    "event_description": "Пользователь совершил покупку"
  }
}

Полный список метаданных событий

is_order Флаг заказа boolean

Описание: Помечает событие как заказ. Это ключевая метаинформация для аналитики выручки, среднего чека и количества заказов.

Применение:

  • События покупки в интернет-магазине
  • Оплата подписки в SaaS
  • Внутриигровые покупки
  • Любые транзакции, приносящие доход
Пример: 
{
  "event": "purchase",
  "_metadata": {
    "is_order": true
  }
}
📌 Важно: Без этого флага события не будут учитываться в выручке и заказах, даже если они называются "purchase".
is_activation Флаг активации boolean

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

Применение:

  • Завершение регистрации
  • Первая покупка
  • Создание первого проекта
  • Загрузка первых данных
  • Прохождение туториала
Пример: 
{
  "event": "signup_completed",
  "_metadata": {
    "is_activation": true
  }
}

Влияние на метрики: Используется для расчета процента активации новых клиентов (CR activation) и сегментации пользователей.

funnel_sales_step Шаг воронки продаж integer

Описание: Номер шага в воронке продаж. Позволяет построить воронку и увидеть конверсию между шагами.

Применение:

  • Шаг 1: Просмотр товара
  • Шаг 2: Добавление в корзину
  • Шаг 3: Оформление заказа
  • Шаг 4: Покупка
Пример воронки интернет-магазина: 
// Просмотр товара
{
  "event": "product_view",
  "_metadata": {
    "funnel_sales_step": 1,
    "funnel_sales_name": "Просмотр товара"
  }
}

// Добавление в корзину
{
  "event": "add_to_cart",
  "_metadata": {
    "funnel_sales_step": 2,
    "funnel_sales_name": "Корзина"
  }
}

// Покупка
{
  "event": "purchase",
  "_metadata": {
    "funnel_sales_step": 3,
    "funnel_sales_name": "Покупка",
    "is_order": true
  }
}
funnel_sales_name Название шага воронки string

Описание: Человеко-читаемое название шага воронки. Отображается в интерфейсе вместо технического имени события.

Пример: 
{
  "event": "add_to_cart",
  "_metadata": {
    "funnel_sales_step": 2,
    "funnel_sales_name": "Добавление в корзину"
  }
}

Рекомендация: Используйте короткие, понятные названия (2-3 слова), которые будут хорошо смотреться в воронке.

event_display_name Отображаемое имя string

Описание: Имя события, которое будет отображаться в интерфейсе вместо технического названия.

Пример: 
{
  "event": "purchase",
  "_metadata": {
    "event_display_name": "Покупка товара"
  }
}

Где используется:

  • В таблице событий
  • На графиках и в легендах
  • В списке топ-событий
  • В настройках воронок
event_color Цвет события color

Описание: Цвет, которым событие будет отображаться на графиках и в визуализациях.

Пример: 
{
  "event": "purchase",
  "_metadata": {
    "event_color": "#28a745"
  }
}

Формат: HEX-код цвета (например, #2A6DF4, #FF5733, #28a745)

Рекомендация: Используйте разные цвета для разных типов событий, чтобы графики были нагляднее:

  • 🔵 Синий — просмотры, навигация
  • 🟢 Зеленый — позитивные действия (покупки, регистрации)
  • 🟠 Оранжевый — важные события
  • 🔴 Красный — ошибки, отмены
event_description Описание события string

Описание: Подробное описание события, что оно означает и когда отправляется. Используется для документации и подсказок.

Пример: 
{
  "event": "purchase",
  "_metadata": {
    "event_description": "Отправляется после успешной оплаты заказа. Содержит информацию о товарах и сумме."
  }
}
order_revenue_field Поле с суммой заказа string

Описание: Указывает, в каком поле properties содержится сумма заказа. По умолчанию система ищет поле revenue.

Пример: 
{
  "event": "purchase",
  "properties": {
    "total_amount": 1499.99,
    "order_total": 1499.99
  },
  "_metadata": {
    "is_order": true,
    "order_revenue_field": "total_amount"
  }
}

Полезно, если: В вашей системе сумма хранится под другим именем (например, total, amount, price).

order_id_field Поле с ID заказа string

Описание: Указывает, в каком поле properties содержится уникальный идентификатор заказа. По умолчанию — order_id.

Пример: 
{
  "event": "purchase",
  "properties": {
    "order_number": "ORD-2025-001"
  },
  "_metadata": {
    "is_order": true,
    "order_id_field": "order_number"
  }
}
order_items_field Поле с товарами string

Описание: Указывает, в каком поле properties содержится массив товаров. По умолчанию — items.

Пример: 
{
  "event": "purchase",
  "properties": {
    "products": [
      {
        "id": "prod_1",
        "name": "Футболка",
        "price": 1999,
        "quantity": 2
      }
    ]
  },
  "_metadata": {
    "is_order": true,
    "order_items_field": "products"
  }
}

Результат: После указания этого поля товары попадут в таблицу order_items и будут доступны в блоке "Популярные товары".

order_status_field Поле со статусом заказа string

Описание: Указывает, в каком поле properties содержится статус заказа. По умолчанию — status.

Пример: 
{
  "event": "purchase",
  "properties": {
    "payment_status": "completed"
  },
  "_metadata": {
    "is_order": true,
    "order_status_field": "payment_status"
  }
}

Возможные статусы: Система автоматически распознает статусы completed, pending, cancelled, refunded и отображает их соответствующим цветом.

Таблица всех метаданных

Акроним Тип Описание По умолчанию
is_order boolean Флаг заказа false
is_activation boolean Флаг активации false
funnel_sales_step integer Номер шага в воронке —
funnel_sales_name string Название шага воронки —
event_display_name string Отображаемое имя —
event_color color Цвет на графиках —
event_description string Описание события —
order_revenue_field string Поле с суммой "revenue"
order_id_field string Поле с ID заказа "order_id"
order_items_field string Поле с товарами "items"
order_status_field string Поле со статусом "status"

Примеры для разных типов бизнеса

🛍️ Интернет-магазин

// Просмотр товара
{
  "event": "product_view",
  "_metadata": {
    "funnel_sales_step": 1,
    "funnel_sales_name": "Просмотр товара",
    "event_display_name": "Просмотр товара",
    "event_color": "#2A6DF4"
  }
}

// Добавление в корзину
{
  "event": "add_to_cart",
  "_metadata": {
    "funnel_sales_step": 2,
    "funnel_sales_name": "Корзина",
    "event_display_name": "Добавление в корзину",
    "event_color": "#fd7e14"
  }
}

// Покупка
{
  "event": "purchase",
  "properties": {
    "order_id": "ORD-001",
    "total": 5499,
    "items": [...]
  },
  "_metadata": {
    "funnel_sales_step": 3,
    "funnel_sales_name": "Покупка",
    "event_display_name": "Покупка",
    "event_color": "#28a745",
    "is_order": true,
    "order_revenue_field": "total"
  }
}

☁️ SaaS-сервис

// Регистрация
{
  "event": "signup",
  "_metadata": {
    "is_activation": true,
    "event_display_name": "Регистрация",
    "event_color": "#28a745"
  }
}

// Создание проекта (ключевое действие)
{
  "event": "project_created",
  "_metadata": {
    "funnel_sales_step": 1,
    "funnel_sales_name": "Создание проекта",
    "event_display_name": "Создание проекта",
    "event_color": "#2A6DF4"
  }
}

// Апгрейд подписки
{
  "event": "subscription_upgraded",
  "properties": {
    "plan": "pro",
    "amount": 9900
  },
  "_metadata": {
    "event_display_name": "Апгрейд тарифа",
    "event_color": "#fd7e14",
    "is_order": true,
    "order_revenue_field": "amount"
  }
}

🎮 Игры

// Начало уровня
{
  "event": "level_start",
  "_metadata": {
    "funnel_sales_step": 1,
    "funnel_sales_name": "Начало уровня",
    "event_display_name": "Начало уровня",
    "event_color": "#2A6DF4"
  }
}

// Прохождение уровня
{
  "event": "level_complete",
  "_metadata": {
    "funnel_sales_step": 2,
    "funnel_sales_name": "Прохождение уровня",
    "event_display_name": "Уровень пройден",
    "event_color": "#28a745"
  }
}

// Покупка в игре
{
  "event": "game_purchase",
  "properties": {
    "item": "gold_pack",
    "price": 299
  },
  "_metadata": {
    "event_display_name": "Покупка игровой валюты",
    "event_color": "#fd7e14",
    "is_order": true,
    "order_revenue_field": "price"
  }
}

Проверка метаданных

Вы можете проверить, правильно ли настроены метаданные, в разделе "События":

  1. Найдите событие в ленте
  2. Кликните на него, чтобы открыть детали
  3. В разделе "Метаданные" вы увидите все примененные метаданные
💡 Совет: Используйте тестовый ключ для экспериментов с метаданными. Так вы не испортите реальную статистику и сможете проверить все варианты.

Рекомендации

Что дальше?

🔖 Метаданные атрибутов

Настройка отображения атрибутов клиентов

Перейти →

🎯 Настройка воронок

Построение воронок продаж с помощью метаданных

Перейти →

Нужна помощь с настройкой метаданных?

Напишите нам, и мы поможем настроить метаданные под ваш бизнес

support@instantbase.online Telegram