Measurement Protocol GA4: что это и как настроить

TL;DR. GA4 Measurement Protocol — это HTTP API от Google, которое позволяет отправлять события аналитики напрямую с сервера, офлайн-систем или IoT-устройств, минуя браузер. Если ваш бизнес обрабатывает офлайн-конверсии, серверные подтверждения заказов или данные из CRM — Measurement Protocol закрывает пробелы, которые браузерный тег покрыть не может.

Что такое Measurement Protocol

Measurement Protocol — это API Google Analytics, позволяющее отправлять данные о событиях напрямую в GA4 без участия браузера или JavaScript-тега. Вместо того чтобы ждать срабатывания gtag.js или GTM на странице, вы формируете HTTP POST-запрос и отправляете его прямо на сервер GA4.

Существует два поколения Measurement Protocol: v1 для Universal Analytics и v2 для Google Analytics 4. Ключевое различие — в модели данных. Measurement Protocol для UA строил хиты вокруг фиксированных типов — pageview, event, ecommerce-транзакция. Measurement Protocol GA4 построен целиком на модели событий: вы отправляете массив объектов событий с произвольными параметрами, что соответствует общей архитектуре GA4.

Universal Analytics был официально отключён в июле 2024 года. Если вы по-прежнему отправляете данные через endpoint Measurement Protocol v1 — это критический технический долг. Необходима миграция на GA4 Measurement Protocol v2.

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

Когда нужен Measurement Protocol

Measurement Protocol не заменяет стандартную реализацию GA4 через gtag.js или Google Tag Manager. Он закрывает специфические сценарии, где JavaScript недоступен или ненадёжен:

1. Серверные события. Подтверждения заказов, изменения статуса платежа, активации подписок — все эти события происходят на сервере без участия браузера. Measurement Protocol позволяет отправлять их напрямую в GA4.
2. Офлайн-конверсии. Продажи по телефону, конверсии в офисе, сделки из CRM, закрытые вне сайта — Measurement Protocol позволяет «подтянуть» эти данные в GA4 и привязать их к соответствующей сессии.
3. Киоски и IoT-устройства. Терминалы самообслуживания, умные устройства, мобильные приложения на встроенных системах — любое устройство, способное отправить HTTP-запрос, может отправлять события в GA4.
4. Игровые события. Мобильные или десктопные игры могут отправлять события (начало уровня, покупка в игре, достижение) напрямую с сервера игры, без браузерного тега.
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

Debug-endpoint (валидирует без записи в GA4):

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 Admin) и api_secret (генерируется в настройках GA4 Admin).

Пошаговая настройка Measurement Protocol GA4

Шаг 1. Получение Measurement ID и API Secret

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

Никогда не публикуйте API Secret в коде фронтенда или публичных репозиториях. Это серверный секрет — храните его в переменных окружения (.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 — debug-endpoint возвращает JSON с описанием ошибок валидации и не отправляет данные в GA4.

Шаг 3. Пример на Python

import requests

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

def send_ga4_event(client_id, event_name, params=None):
    url = "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 = принято

status = send_ga4_event(
    client_id="user_12345",
    event_name="purchase",
    params={
        "transaction_id": "T_12345",
        "value": 4500.00,
        "currency": "UAH"
    }
)
print(f"Status: {status}")

Шаг 4. Проверка в GA4 DebugView

Для мониторинга живых событий: GA4 → Настроить → DebugView. Чтобы события Measurement Protocol отображались в DebugView, добавьте в params события "debug_mode": 1 и отправляйте на продакшн-endpoint (/mp/collect). События появляются в течение нескольких секунд.

Обязательные и необязательные параметры

Примеры событий: 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": 35000,
        "currency": "UAH",
        "sales_manager": "ivan_petrenko"
      }
    }]
  }'

Measurement Protocol для ecommerce

Наиболее распространённый сценарий — серверная отправка события 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-режим и проверка событий

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 попадёт в фронтенд JS или публичный репозиторий, злоумышленник сможет отправлять фейковые события в ваш GA4. Храните ключ только на сервере.
7. Дублирование событий. Если и браузерный тег (gtag.js/GTM), и серверный Measurement Protocol отправляют одно и то же событие purchase — конверсия считается дважды. Выберите один источник истины для каждого типа события или дедуплицируйте по transaction_id.

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-запросе к GA4 Measurement Protocol можно передать максимум 25 событий. Каждое событие может иметь до 25 параметров. Для больших объёмов отправляйте несколько пакетных запросов.

Есть ли rate limit на запросы?

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