GA4 Event Builder — генератор gtag, dataLayer, Measurement Protocol

Event-model GA4: фундаментальная разница от Universal Analytics

До июля 2023 года Universal Analytics (UA) использовала модель сессия → просмотры → события. Каждое действие имело category/action/label. GA4 выбросил всю эту иерархию и объявил: всё есть событие. Просмотр страницы — событие page_view. Сессия — событие session_start. Покупка — событие purchase. Даже user_engagement (активность на странице ≥10 секунд) — событие.

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

{
  event_name: 'purchase',          // название события
  parameters: {                    // параметры (до 25)
    transaction_id: 'T_12345',
    currency: 'UAH',
    value: 1299.00,
    tax: 216.50,
    shipping: 50.00,
    coupon: 'SPRING10',
    items: [                       // массив товаров для e-commerce
      { item_id: 'SKU_001', item_name: 'Футболка', price: 599, quantity: 2 }
    ]
  },
  user_properties: {               // атрибуты пользователя
    customer_tier: 'gold',
    first_visit_source: 'organic'
  }
}

GA4 обрабатывает это событие в 3 типа сущностей:

1. Event scope (событие) — большинство параметров
2. User scope (пользователь) — user_properties, user_id
3. Item scope (товар) — поля внутри items[]

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

1. gtag.js — прямой вызов

<script>
gtag('event', 'purchase', {
  transaction_id: 'T_12345',
  currency: 'UAH',
  value: 1299.00,
  items: [...]
});
</script>

Когда использовать: малые сайты без GTM, landing pages, MVP. Минусы: (1) нельзя A/B тестировать без изменения кода, (2) нет удобного интерфейса для менеджеров, (3) дублирование тегов (Facebook Pixel, LinkedIn) — отдельно вставлять каждый.

2. dataLayer.push — через Google Tag Manager

<script>
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({ ecommerce: null });
window.dataLayer.push({
  event: 'purchase',
  ecommerce: {
    transaction_id: 'T_12345',
    currency: 'UAH',
    value: 1299.00,
    items: [...]
  }
});
</script>

Когда использовать: средние+ сайты, e-commerce, медиа. Преимущества: (1) GTM ловит событие через Custom Event триггер, запускает тег GA4, (2) легко добавить параллельные теги (Pixel, TikTok), (3) дебаггинг через GTM Preview Mode, (4) версионирование и ролбек изменений.

Важно: window.dataLayer.push({ ecommerce: null }) перед основным push — очищает предыдущий e-commerce контекст. Без этого товары предыдущего события могут «протечь» в следующее.

3. Measurement Protocol — серверная отправка

curl -X POST "https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXXXX&api_secret=YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "XXXXXXXXXX.YYYYYYYYYY",
    "events": [{
      "name": "purchase",
      "params": {
        "transaction_id": "T_12345",
        "currency": "UAH",
        "value": 1299.00
      }
    }]
  }'

Когда использовать: серверные webhooks (Stripe, LiqPay), офлайн-атрибуция с CRM, мобильные приложения, антифрод-фильтрация (отправлять purchase только после ручной проверки). API Secret создаётся в GA4 Admin → Data Streams → Measurement Protocol API secrets.

Обязательные параметры для e-commerce

GA4 считает монетизацию только для событий с определённым набором параметров:

Частый факап: currency пропущено → GA4 НЕ считает purchase как монетизацию, в отчётах Revenue = 0, хотя события приходят. Наш генератор предупреждает об этом inline.

Структура items[] — массив товаров

Каждый товар в items[] — отдельный JSON-объект. GA4 поддерживает ~20 полей, самые важные:

items: [{
  item_id: 'SKU_001',          // обязательно (или item_name)
  item_name: 'Футболка красная',
  item_brand: 'Nike',
  item_category: 'apparel',     // до 5 уровней: item_category, item_category2, ...
  item_variant: 'M',
  price: 599.00,
  quantity: 2,
  currency: 'UAH',              // если отличается от основного
  discount: 50,
  coupon: 'SPRING10',
  affiliation: 'Online Store',
  index: 0                      // позиция в списке
}]

Минимум — item_id ИЛИ item_name (хотя бы одно из двух). Остальное — опционально, но чем больше, тем детальнее отчёты Purchase journey и Product performance в GA4.

Типичные ошибки

1. event_name с большими буквами. PurchaseCompleted — GA4 отклонит. Правильно: purchase_completed, идеально — стандартное purchase.
2. Значение как строка. value: "1299" в отчётах покажется как String, не засчитывается в Revenue. Правильно: value: 1299.00 (число).
3. Дублированные purchase. Без transaction_id GA4 не дедуплицирует, каждое обновление thank-you page = новая покупка. Всегда указывайте уникальный ID заказа.
4. Кириллические ключи. { категория: "одежда" } — GA4 отклонит. Только латиница для keys: { category: "одежда" }.
5. Отправка зарезервированных имён. page_view через кастомный код — GA4 отклонит, так как генерирует сам. Используйте кастомные названия.
6. Путаница gtag + GTM. Если у вас установлен GTM, НЕ надо одновременно вызывать gtag напрямую — будет дублирование. Только dataLayer.push, GTM сам преобразует в правильный GA4-вызов.

Debugging: как проверить, что событие дошло

1. GA4 DebugView (Admin → DebugView) — показывает события в реальном времени. Включите Debug Mode: Chrome extension «GA Debugger» или параметр ?debug_mode=1 в gtag.
2. GTM Preview Mode — если через dataLayer, GTM показывает все push и какие теги сработали.
3. Chrome DevTools → Network → Fetch/XHR — фильтр collect, ищите запросы к google-analytics.com/g/collect или /mp/collect.
4. GA4 Realtime — события последних 30 минут, с задержкой до 60 сек.

Частые вопросы (FAQ)

gtag vs dataLayer.push — что выбирать?

gtag для сайтов БЕЗ GTM. dataLayer.push — если у вас GTM (рекомендовано). Не комбинируйте.

Measurement Protocol — когда?

Серверные webhooks, офлайн-атрибуция, мобильные приложения. Нужен API Secret из GA4 admin.

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

25 в бесплатном GA4, 100 в GA4 360. Плюс лимиты на уникальные параметры в ресурсе.

Какие event_name зарезервированы?

page_view, session_start, scroll, click, form_submit и ещё ~15. Наш генератор предупреждает inline.

purchase не считается как Revenue?

Проверьте: currency (обязательно), value (число), transaction_id (уникальный), items[] (массив), Enhanced E-commerce включено.

Поддерживает ли GA4 кириллицу в параметрах?

В значениях — да. В ключах — только латиница, 0-9, _.

Как работает дедупликация purchase?

По transaction_id в течение 30 дней. Та же транзакция не учтётся дважды.

Enhanced Measurement vs кастомные события?

Enhanced — базовый трекинг автоматически. Кастомные — для специфических бизнес-действий.

Event в DebugView, но не в отчётах?

Задержка 24-48 ч для стандартных отчётов. Проверьте Internal Traffic фильтры и Custom Dimensions.

user_id vs client_id vs user_properties?

client_id — анонимный ID браузера. user_id — ваш логин. user_properties — атрибуты для сегментации.