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 — атрибути для сегментації.