Що таке Measurement Protocol GA4 і як його налаштувати

Measurement Protocol GA4 — це HTTP API від Google, що дозволяє надсилати події в Analytics безпосередньо з сервера, офлайн-систем або IoT-пристроїв, минаючи браузер. Якщо ваш бізнес має офлайн-конверсії, серверні події або дані з CRM — без Measurement Protocol ви втрачаєте частину картини аналітики.

Що таке Measurement Protocol

Measurement Protocol — це API Google Analytics, що дозволяє надсилати дані про події безпосередньо до Google Analytics без участі браузера або JavaScript-тегу. Замість того щоб чекати, поки gtag.js або GTM спрацює на сторінці, ви формуєте HTTP POST-запит і надсилаєте його прямо на сервер GA4.

Існує два покоління Measurement Protocol: v1 для Universal Analytics і v2 для Google Analytics 4. Ключова різниця — в архітектурі даних. В UA Measurement Protocol будував хіти з фіксованими полями (pageview, event, ecommerce). В GA4 Measurement Protocol будується навколо моделі подій — ви надсилаєте масив об’єктів подій з довільними параметрами, що відповідає загальній концепції GA4.

Universal Analytics офіційно відключений з липня 2024 року. Якщо ви досі використовуєте v1 Measurement Protocol — це критичний технічний борг. Потрібен перехід на GA4 Measurement Protocol v2.

Два базових сценарії використання: (1) інтернет-магазин надсилає подію purchase з сервера після підтвердження оплати, щоб уникнути дублювань від браузерного тегу; (2) кол-центр записує факт продажу по телефону і надсилає офлайн-конверсію в GA4 для відображення в звітах.

Коли потрібен Measurement Protocol

Measurement Protocol не замінює стандартну реалізацію GA4 через gtag.js або Google Tag Manager. Він закриває специфічні сценарії, де JavaScript недоступний або ненадійний:

1. Серверні події. Підтвердження замовлення, зміна статусу платежу, активація підписки — всі ці події відбуваються на сервері без участі браузера. Measurement Protocol дозволяє надсилати їх в GA4 безпосередньо.
2. Офлайн-конверсії. Продажі по телефону, конверсії в офісі, угоди з CRM, що закриваються поза сайтом — Measurement Protocol дозволяє «підтягнути» ці дані до GA4 і зв’язати їх з відповідними сеансами.
3. IoT-пристрої. Термінали самообслуговування, розумні прилади, мобільні застосунки на embedded-системах — будь-який пристрій, який може надіслати HTTP-запит, може надсилати події в GA4.
4. Ігрові події. Мобільні або desktop-ігри можуть надсилати події (початок рівня, покупка в грі, ачівки) напряму з сервера гри, без браузерного тегу.
5. Імпорт даних з CRM. Якщо угода в CRM закрилася через тиждень після першого контакту, можна надіслати подію з параметром timestamp_micros, прив’язавши конверсію до правильного сеансу.

Як працює Measurement Protocol GA4

Архітектура проста: ваш сервер або застосунок формує HTTP POST-запит і надсилає його на endpoint GA4. Google обробляє запит і дані з’являються у звітах Google Analytics 4.

Endpoint для відправки даних:

POST https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXX&api_secret=XXXXXXXXXX

Для відладки використовується окремий endpoint:

POST https://www.google-analytics.com/debug/mp/collect?measurement_id=G-XXXXXXXX&api_secret=XXXXXXXXXX

Тіло запиту — JSON з обов’язковими полями:

• client_id — унікальний ідентифікатор клієнта (браузера або пристрою). Для зв’язку з браузерними даними має збігатися з GA-ідентифікатором в cookie _ga.
• events — масив об’єктів подій. Кожен об’єкт має обов’язкове поле name і необов’язковий params.

В параметрах URL запиту обов’язкові: measurement_id (G-XXXXXXXX з адмін-панелі GA4) і api_secret (генерується в налаштуваннях GA4).

Покрокове налаштування Measurement Protocol GA4

Крок 1. Отримання Measurement ID та API Secret

1. Відкрийте GA4 → Адміністратор → Потоки даних.
2. Виберіть веб-потік і скопіюйте Measurement ID (формат G-XXXXXXXX).
3. Прокрутіть вниз до розділу «Measurement Protocol API secrets» → натисніть «Create».
4. Задайте назву (наприклад, «server-events») і скопіюйте згенерований API Secret.

Ніколи не публікуйте API Secret у відкритому коді (frontend, публічні репозиторії). Це серверний секрет — зберігайте його в змінних середовища (.env) або секрет-менеджері.

Крок 2. Перший запит через curl

Надішліть тестову подію через термінал:

curl -X POST \
  "https://www.google-analytics.com/debug/mp/collect?measurement_id=G-XXXXXXXX&api_secret=YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "test-client-123",
    "events": [{
      "name": "test_event",
      "params": {
        "custom_param": "hello_from_server"
      }
    }]
  }'

Зверніть увагу: використовуємо /debug/mp/collect — це відладочний endpoint. Він повертає JSON з описом валідаційних помилок і не надсилає дані в GA4.

Крок 3. Приклад на Python

import requests
import json

MEASUREMENT_ID = "G-XXXXXXXX"
API_SECRET = "your_api_secret_here"

def send_ga4_event(client_id, event_name, params=None):
    url = f"https://www.google-analytics.com/mp/collect"
    payload = {
        "client_id": client_id,
        "events": [{
            "name": event_name,
            "params": params or {}
        }]
    }
    response = requests.post(
        url,
        params={"measurement_id": MEASUREMENT_ID, "api_secret": API_SECRET},
        json=payload
    )
    return response.status_code  # 204 = success

# Приклад виклику
status = send_ga4_event(
    client_id="user_12345",
    event_name="purchase",
    params={
        "transaction_id": "T_12345",
        "value": 1500.00,
        "currency": "UAH"
    }
)
print(f"Status: {status}")

Крок 4. Перевірка в GA4 DebugView

Для перевірки живих подій (не через debug endpoint) перейдіть в GA4 → Налаштувати → DebugView. Щоб події відображалися в DebugView, додайте в params події параметр "debug_mode": true або "debug_mode": 1.

Обов’язкові та необов’язкові параметри

Повна структура запиту до Measurement Protocol GA4:

Приклади подій: curl-запити

Подія page_view

curl -X POST \
  "https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXX&api_secret=YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "user_abc123",
    "events": [{
      "name": "page_view",
      "params": {
        "page_location": "https://example.com.ua/product/shoes/",
        "page_title": "Кросівки Nike — купити",
        "engagement_time_msec": 100
      }
    }]
  }'

Кастомна подія

curl -X POST \
  "https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXX&api_secret=YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "user_abc123",
    "user_id": "crm_user_987",
    "timestamp_micros": 1716285600000000,
    "events": [{
      "name": "crm_deal_closed",
      "params": {
        "deal_id": "CRM-456",
        "deal_value": 25000,
        "currency": "UAH",
        "sales_manager": "ivan_petrenko"
      }
    }]
  }'

Measurement Protocol для ecommerce

Найпоширеніший use case — серверна відправка події purchase після підтвердження оплати. Це усуває дублювання, що виникає, коли покупець оновлює сторінку підтвердження.

Подія purchase з масивом items

curl -X POST \
  "https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXX&api_secret=YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "user_abc123",
    "events": [{
      "name": "purchase",
      "params": {
        "transaction_id": "ORDER-78901",
        "value": 3200.00,
        "tax": 533.33,
        "shipping": 99.00,
        "currency": "UAH",
        "coupon": "SUMMER10",
        "items": [
          {
            "item_id": "SKU_001",
            "item_name": "Кросівки Nike Air Max",
            "item_category": "Взуття",
            "price": 2800.00,
            "quantity": 1
          },
          {
            "item_id": "SKU_002",
            "item_name": "Шкарпетки спортивні",
            "item_category": "Аксесуари",
            "price": 200.00,
            "quantity": 2
          }
        ]
      }
    }]
  }'

Подія refund

curl -X POST \
  "https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXX&api_secret=YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "user_abc123",
    "events": [{
      "name": "refund",
      "params": {
        "transaction_id": "ORDER-78901",
        "value": 2800.00,
        "currency": "UAH",
        "items": [
          {
            "item_id": "SKU_001",
            "quantity": 1
          }
        ]
      }
    }]
  }'

Debug режим і перевірка подій

GA4 надає два інструменти для відладки Measurement Protocol:

Debug endpoint /debug/mp/collect

Надсилайте запити на https://www.google-analytics.com/debug/mp/collect замість /mp/collect. Debug endpoint повертає JSON з детальним описом помилок валідації і не записує дані в GA4. Приклад відповіді з помилкою:

{
  "validationMessages": [
    {
      "fieldPath": "events[0].name",
      "description": "Event name must match the pattern '^(?!ga_)(?!_)[A-Za-z][A-Za-z0-9_]{0,39}$'",
      "validationCode": "NAME_INVALID"
    }
  ]
}

Якщо запит коректний — відповідь буде {"validationMessages": []}.

DebugView в GA4

Для живого моніторингу подій: GA4 → Налаштувати → DebugView. Щоб Measurement Protocol події відображалися тут, додайте в params: "debug_mode": 1. Надсилайте запити на основний endpoint (/mp/collect), і події з’являться в DebugView в режимі реального часу.

Типові помилки при роботі з Measurement Protocol

1. Неправильний endpoint. Використання UA endpoint www.google-analytics.com/collect замість GA4 endpoint www.google-analytics.com/mp/collect. Дані просто не потраплять в GA4.
2. Відсутній або неправильний client_id. Якщо client_id не відповідає значенню в cookie _ga браузера, серверна і браузерна сесії не зв’яжуться. Завжди передавайте реальний GA client_id з браузера.
3. Неправильні назви подій. GA4 вимагає: латинські літери, цифри і підкреслення; починатися з літери; не починатися з ga_; максимум 40 символів. Назви на кирилиці або з пробілами не проходять валідацію.
4. Неправильна інтерпретація 204 No Content. Відповідь 204 означає, що запит прийнятий технічно, але не гарантує, що дані коректні або з’явились у звітах. Завжди валідуйте через debug endpoint першим.
5. timestamp_micros поза межами 72 годин. GA4 відхиляє події, час яких старіший за 72 години. Якщо потрібно імпортувати старіші дані — використовуйте Data Import в GA4 Admin.
6. API Secret у відкритому коді. Якщо api_secret потрапить у frontend JS або публічний репозиторій, зловмисник може відправляти фальшиві події у ваш GA4. Зберігайте ключ тільки на сервері.
7. Дублювання подій. Якщо браузерний тег (gtag.js/GTM) і серверний Measurement Protocol надсилають ту саму подію purchase — конверсія рахується двічі. Або вимикайте серверну подію після браузерної, або навпаки.

FAQ: Часті запитання про Measurement Protocol

Чи замінює Measurement Protocol gtag.js або GTM?

Ні. Measurement Protocol — це доповнення, а не заміна. GTM і gtag.js відслідковують поведінку на сайті через JavaScript у браузері. Measurement Protocol використовується для серверних подій, офлайн-конверсій і сценаріїв, де JavaScript недоступний. В ecommerce-проектах обидва інструменти часто використовуються паралельно.

Чи можна відправляти події з датою в минулому?

Так, за допомогою параметра timestamp_micros можна вказати час події в мікросекундах Unix-epoch. Але GA4 приймає події не старіші за 72 години. Події старіші за 72 години будуть відхилені і не з’являться у звітах.

Скільки подій можна відправити в одному запиті?

В одному HTTP-запиті до Measurement Protocol GA4 можна передати максимум 25 подій. Кожна подія може мати до 25 параметрів. Якщо потрібно відправити більше — надсилайте декілька запитів.

Чи є rate limit на запити?

GA4 офіційно не публікує жорсткий rate limit для Measurement Protocol. На практиці рекомендується не перевищувати кілька тисяч запитів на секунду з одного джерела. Для великих обсягів даних краще використовувати пакетну відправку (до 25 подій у запиті) та черги повідомлень.