Measurement Protocol GA4: czym jest i jak go skonfigurować

GA4 Measurement Protocol to API HTTP od Google, które umożliwia wysyłanie zdarzeń analitycznych bezpośrednio z serwera, systemów offline lub urządzeń IoT — z pominięciem przeglądarki. Jeśli Twój biznes w Polsce obsługuje konwersje offline, potwierdzenia zamówień po stronie serwera lub dane z CRM — Measurement Protocol uzupełnia luki, których nie pokrywa tag przeglądarkowy.

Czym jest Measurement Protocol

Measurement Protocol to API Google Analytics umożliwiające wysyłanie danych o zdarzeniach bezpośrednio do GA4 bez udziału przeglądarki ani tagu JavaScript. Zamiast czekać, aż gtag.js lub GTM uruchomi się na stronie, tworzysz żądanie HTTP POST i wysyłasz je bezpośrednio na serwer GA4.

Istnieją dwie generacje Measurement Protocol: v1 dla Universal Analytics i v2 dla Google Analytics 4. Kluczowa różnica leży w modelu danych. Measurement Protocol dla UA budował hity wokół stałych typów — pageview, event, transakcja ecommerce. Measurement Protocol GA4 oparty jest całkowicie na modelu zdarzeń: wysyłasz tablicę obiektów zdarzeń z dowolnymi parametrami, co odpowiada ogólnej architekturze GA4.

Universal Analytics został oficjalnie wyłączony w lipcu 2024 roku. Jeśli nadal wysyłasz dane za pomocą endpointu Measurement Protocol v1 — to krytyczny dług techniczny. Konieczna jest migracja do GA4 Measurement Protocol v2.

Dwa podstawowe scenariusze użycia: (1) polski sklep internetowy wysyła zdarzenie purchase z serwera po potwierdzeniu płatności, aby zapobiec duplikatom konwersji z tagu przeglądarkowego; (2) dział sprzedaży rejestruje sprzedaż telefoniczną w CRM i wysyła konwersję offline do GA4, powiązaną z oryginalną sesją za pomocą client_id.

Kiedy potrzebujesz Measurement Protocol

Measurement Protocol nie zastępuje standardowej implementacji GA4 przez gtag.js lub Google Tag Manager. Rozwiązuje specyficzne scenariusze, w których JavaScript jest niedostępny lub zawodny:

1. Zdarzenia po stronie serwera. Potwierdzenia zamówień, zmiany statusu płatności, aktywacje subskrypcji — wszystkie te zdarzenia zachodzą na serwerze bez udziału przeglądarki. Measurement Protocol pozwala wysyłać je bezpośrednio do GA4.
2. Konwersje offline. Sprzedaż telefoniczna, konwersje w biurze, transakcje z CRM zamknięte poza witryną — Measurement Protocol pozwala wprowadzić te dane do GA4 i powiązać je z odpowiednią sesją.
3. Urządzenia IoT. Terminale samoobsługowe, inteligentne urządzenia, aplikacje mobilne na systemach wbudowanych — każde urządzenie mogące wysłać żądanie HTTP może wysyłać zdarzenia do GA4.
4. Zdarzenia w grach. Gry mobilne lub desktopowe mogą wysyłać zdarzenia (start poziomu, zakup w grze, osiągnięcie) bezpośrednio z serwera gry, bez tagu przeglądarkowego.
5. Import danych z CRM. Jeśli transakcja w CRM zamknęła się tydzień po pierwszym kontakcie, możesz wysłać zdarzenie z parametrem timestamp_micros, przypisując konwersję do właściwej sesji i źródła ruchu.

Jak działa GA4 Measurement Protocol

Architektura jest prosta: Twój serwer lub aplikacja tworzy żądanie HTTP POST i wysyła je na endpoint GA4. Google przetwarza żądanie, a dane pojawiają się w raportach Google Analytics 4.

Endpoint produkcyjny:

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

Endpoint debugowania (waliduje bez zapisu do GA4):

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

Ciało żądania to JSON z następującymi wymaganymi polami:

• client_id — unikalny identyfikator klienta (przeglądarki lub urządzenia). Aby połączyć dane serwerowe z danymi z przeglądarki, musi odpowiadać identyfikatorowi GA przechowywanemu w pliku cookie _ga.
• events — tablica obiektów zdarzeń. Każdy obiekt wymaga pola name i akceptuje opcjonalny obiekt params.

Wymagane parametry URL: measurement_id (G-XXXXXXXX z panelu GA4 Admin) i api_secret (generowany w ustawieniach GA4 Admin).

Konfiguracja krok po kroku

Krok 1. Uzyskanie Measurement ID i API Secret

1. Otwórz GA4 → Administracja → Strumienie danych.
2. Wybierz strumień internetowy i skopiuj Measurement ID (format: G-XXXXXXXX).
3. Przewiń w dół do sekcji „Tajne klucze API Measurement Protocol” → kliknij „Utwórz”.
4. Nadaj nazwę (np. „server-events”) i skopiuj wygenerowany API Secret.

Nigdy nie umieszczaj API Secret w kodzie frontend ani publicznych repozytoriach. To sekret po stronie serwera — przechowuj go w zmiennych środowiskowych (.env) lub menedżerze sekretów.

Krok 2. Pierwsze żądanie przez 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"
      }
    }]
  }'

Uwaga: używamy /debug/mp/collect — endpoint debugowania zwraca raport walidacyjny JSON i nie zapisuje danych do GA4.

Krok 3. Przykład w Pythonie

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 = przyjęto

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

Krok 4. Weryfikacja w GA4 DebugView

Aby monitorować zdarzenia na żywo: GA4 → Konfiguruj → DebugView. Aby zdarzenia Measurement Protocol pojawiały się w DebugView, dodaj "debug_mode": 1 do parametrów zdarzenia i wyślij na endpoint produkcyjny (/mp/collect).

Wymagane i opcjonalne parametry

Przykłady zdarzeń

Zdarzenie 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.pl/produkty/buty-biegowe/",
        "page_title": "Buty do biegania — kup online",
        "engagement_time_msec": 100
      }
    }]
  }'

Zdarzenie niestandardowe

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": 15000,
        "currency": "PLN",
        "sales_region": "polska_polnoc"
      }
    }]
  }'

Measurement Protocol dla ecommerce

Najczęstszy przypadek użycia w polskim ecommerce to serwerowe wysyłanie zdarzenia purchase po potwierdzeniu płatności. Eliminuje to duplikaty konwersji powstające, gdy klient odświeża stronę potwierdzenia zamówienia.

Zdarzenie purchase z tablicą 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": 459.97,
        "tax": 86.07,
        "shipping": 19.99,
        "currency": "PLN",
        "coupon": "LATO10",
        "items": [
          {
            "item_id": "SKU_001",
            "item_name": "Buty Nike Air Max",
            "item_category": "Obuwie",
            "price": 399.99,
            "quantity": 1
          },
          {
            "item_id": "SKU_002",
            "item_name": "Skarpety sportowe",
            "item_category": "Akcesoria",
            "price": 19.99,
            "quantity": 3
          }
        ]
      }
    }]
  }'

Zdarzenie 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": 399.99,
        "currency": "PLN",
        "items": [
          {
            "item_id": "SKU_001",
            "quantity": 1
          }
        ]
      }
    }]
  }'

Tryb debugowania i walidacja

Endpoint /debug/mp/collect

Wysyłaj żądania na https://www.google-analytics.com/debug/mp/collect zamiast /mp/collect. Endpoint debugowania zwraca raport walidacyjny JSON i nie zapisuje danych do GA4. Przykład odpowiedzi z błędem:

{
  "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"
    }
  ]
}

Poprawne żądanie zwraca: {"validationMessages": []}.

DebugView w GA4

Do monitorowania zdarzeń w czasie rzeczywistym: GA4 → Konfiguruj → DebugView. Aby zdarzenia Measurement Protocol pojawiały się w DebugView, dodaj "debug_mode": 1 do parametrów zdarzenia i wyślij na endpoint produkcyjny (/mp/collect). Zdarzenia pojawiają się w ciągu kilku sekund.

Typowe błędy przy pracy z Measurement Protocol

1. Błędny endpoint. Używanie endpointu UA www.google-analytics.com/collect zamiast endpointu GA4 www.google-analytics.com/mp/collect. Dane po prostu nie trafią do GA4.
2. Brak lub niezgodność client_id. Jeśli client_id nie odpowiada wartości w pliku cookie _ga przeglądarki, sesje serwerowe i przeglądarkowe nie zostaną połączone. Zawsze przekazuj rzeczywisty GA client_id pobrany z przeglądarki.
3. Nieprawidłowe nazwy zdarzeń. GA4 wymaga: liter łacińskich, cyfr i podkreślników; nazwa musi zaczynać się od litery; nie może zaczynać się od ga_; maks. 40 znaków. Nazwy ze spacjami, znakami specjalnymi lub literami spoza alfabetu łacińskiego nie przechodzą walidacji.
4. Błędna interpretacja 204 No Content. Odpowiedź 204 oznacza, że żądanie zostało technicznie przyjęte, ale nie gwarantuje poprawności danych ani ich pojawienia się w raportach. Zawsze najpierw waliduj przez endpoint debugowania.
5. timestamp_micros poza oknem 72 godzin. GA4 odrzuca zdarzenia starsze niż 72 godziny bez powiadomienia. Do importu starszych danych użyj funkcji Data Import w GA4 Admin.
6. API Secret w kodzie frontend. Jeśli api_secret trafi do kodu JavaScript po stronie klienta lub publicznego repozytorium, ktoś może wysyłać fałszywe zdarzenia do Twojej właściwości GA4. Przechowuj klucz wyłącznie po stronie serwera.
7. Duplikaty zdarzeń. Jeśli zarówno tag przeglądarkowy (gtag.js/GTM), jak i serwerowy Measurement Protocol wysyłają to samo zdarzenie purchase, konwersja jest liczona dwukrotnie. Wybierz jedno źródło prawdy dla każdego typu zdarzenia lub deduplikuj za pomocą transaction_id.

FAQ: Najczęstsze pytania o Measurement Protocol

Czy Measurement Protocol zastępuje gtag.js lub GTM?

Nie. Measurement Protocol to uzupełnienie, a nie zamiennik. GTM i gtag.js śledzą zachowanie w przeglądarce za pomocą JavaScript. Measurement Protocol obsługuje zdarzenia serwerowe, konwersje offline i scenariusze, w których JavaScript jest niedostępny. W projektach ecommerce w Polsce oba narzędzia często działają równolegle.

Czy można wysyłać zdarzenia z datą w przeszłości?

Tak, używając timestamp_micros możesz podać czas zdarzenia w mikrosekundach Unix epoch. GA4 akceptuje zdarzenia do 72 godzin wstecz. Zdarzenia starsze niż 72 godziny są odrzucane i nie pojawią się w raportach.

Ile zdarzeń można wysłać w jednym żądaniu?

Jedno żądanie HTTP do GA4 Measurement Protocol może zawierać maksymalnie 25 zdarzeń. Każde zdarzenie może mieć do 25 parametrów. Przy większych wolumenach wysyłaj wiele pogrupowanych żądań.

Czy jest limit zapytań?

Google nie publikuje twardego limitu zapytań dla GA4 Measurement Protocol. W praktyce zaleca się nieprzekraczanie kilku tysięcy żądań na sekundę z jednego źródła. Przy dużych wolumenach korzystaj z grupowania (do 25 zdarzeń na żądanie) i kolejek komunikatów dla niezawodności.