Measurement Protocol w GA4: dane, limity i kontrola przed wysyłką

Measurement Protocol przesyła zdarzenia z serwera do Google Analytics 4. Przykładem jest potwierdzenie płatności, które dociera później od operatora płatności. Ładunek oznacza zawartość takiego przesłania: dokument JSON z identyfikatorami i danymi zdarzeń. Protokół uzupełnia zbieranie danych przez tag Google lub SDK Firebase. Żądanie z serwera nie zastępuje pełnej integracji w przeglądarce ani decyzji o dopuszczalnym przetwarzaniu danych.

Najważniejsze rozróżnienie jest proste: odpowiedź HTTP z zakresu 2xx potwierdza odebranie żądania, a nie obecność zdarzenia w raporcie. Błędne dane również mogą nie wywołać miarodajnego błędu HTTP. Stały kod 204 dla każdego możliwego żądania nie jest jednak gwarantowaną właściwością interfejsu.

Adres, sekret i zawartość

Przesłanie odbywa się przez HTTPS POST na https://www.google-analytics.com/mp/collect. Do zbierania danych w UE Google dokumentuje adres https://region1.google-analytics.com/mp/collect. Sam ten adres nie stanowi gwarancji, że wszystkie późniejsze etapy przetwarzania odbywają się wyłącznie w UE.

Dla strumienia internetowego measurement_id i api_secret trafiają do parametrów URL. Identyfikator pomiaru wskazuje strumień, a sekret API uprawnia do przesyłania danych. Tylko sekret jest poufny. Kod przeglądarki, publiczne repozytoria i nieoczyszczone logi adresów URL nie są odpowiednim miejscem na sekret. Strumienie aplikacji używają firebase_app_id zamiast identyfikatora pomiaru.

JSON zawiera client_id dla zdarzeń internetowych albo app_instance_id dostarczony przez SDK Firebase dla aplikacji. Powiązanie zdarzenia z wcześniejszą wizytą wymaga zgodności Client ID z identyfikatorem tagu Google. Nowa losowa wartość przy każdej płatności utrudnia to powiązanie i może zniekształcać liczbę użytkowników. Nie oznacza jednak automatycznie nowej sesji przy każdym żądaniu.

Mały przykład zakupu

Poniższy JSON przedstawia strukturę zakupu internetowego. Wszystkie identyfikatory i czas zaangażowania są przykładowe; rzeczywiste przesłanie wymaga odpowiednich wartości. Opcjonalny czas zaangażowania musi odzwierciedlać faktycznie zmierzony czas od poprzedniego zdarzenia. Sama płatność obsłużona w tle nie dostarcza takiego pomiaru. Bez historycznego znacznika czasu obowiązuje chwila odebrania danych.

{
  "client_id": "1234567890.1700000000",
  "events": [
    {
      "name": "purchase",
      "params": {
        "transaction_id": "T-8891",
        "currency": "EUR",
        "value": 20,
        "session_id": 1700000000,
        "engagement_time_msec": 100,
        "items": [
          {
            "item_id": "A-1",
            "price": 10,
            "quantity": 2
          }
        ]
      }
    }
  ]
}

Wartość towaru wynosi tutaj 10 euro razy dwie sztuki. value zawiera sumę za towary bez oddzielnie wykazanych kosztów dostawy i podatków, a currency określa walutę. Stały, unikalny transaction_id pomaga unikać podwójnego zliczania zakupu. Ponowienie tego samego przesłania technicznego nie może więc tworzyć nowego numeru zamówienia.

session_id łączy zdarzenie z sesją; nowy identyfikator sesji może utworzyć nową sesję. engagement_time_msec opisuje czas zaangażowania w milisekundach. Obie wartości pomagają w obliczaniu wskaźników sesji i zaangażowania oraz w raportach czasu rzeczywistego. Brak wartości wyjaśnia możliwe luki, lecz nie dowodzi nieobecności zdarzenia w każdym raporcie.

Pola opcjonalne z konkretnym celem

user_id to opcjonalny wewnętrzny identyfikator użytkownika. Adresy e-mail i numery telefonów nie należą do tego pola, zwykłych parametrów zdarzeń ani właściwości użytkownika. Osobna funkcja user_data ma własne warunki i zasady przygotowania danych, w tym normalizację oraz haszowanie określonych informacji. To pole nie zezwala na dowolne dane osobowe.

user_properties opisuje cechy, na przykład poziom klienta. user_location, ip_override i device mogą dostarczać informacji o lokalizacji lub urządzeniu. Dodatkowe dane wymagają znanego pochodzenia, odpowiedniej dokładności i dopuszczalnego celu użycia. Niezmieniony obiekt dataLayer nie pasuje automatycznie do protokołu. Własne pola wymagają przyporządkowania i sprawdzenia według dokumentacji; nieznany klucz nie oznacza udokumentowanej utraty całego żądania w każdym przypadku.

Nazwy i ważne limity

Zalecane nazwy zdarzeń mają określone znaczenie. purchase oznacza zakup, a Purchase z wielką literą jest inną nazwą. Nazwy zastrzeżone, takie jak session_start, nie zastępują poprawnego identyfikatora sesji. screen_view, ad_impression i in_app_purchase są przeznaczone dla strumieni aplikacji.

Instrukcja wysyłania podaje najwyżej dziesięć własnych parametrów pozycji, natomiast dokumentacja zdarzenia purchase podaje 27. Do wyjaśnienia tej rozbieżności dziesięć jest ostrożniejszym limitem dla żądań Measurement Protocol. Tabela zbiera często istotne ograniczenia, ale nie zastępuje dokumentacji konkretnego zdarzenia.

Znaki i bajty to różne wielkości. Polska litera może zajmować kilka bajtów UTF-8. Rozmiar żądania zależy zatem od gotowego JSON-a, na przykład wyniku Buffer.byteLength(JSON.stringify(payload), 'utf8') w Node.js. Nie istnieje stała granica 29 pozycji na zdarzenie: dłuższe nazwy produktów i dodatkowe pola zmieniają rozmiar. Paczka musi jednocześnie spełniać limit liczby zdarzeń i limit bajtów.

Znaczniki czasu bez pomyłek jednostek

timestamp_micros używa mikrosekund od 1 stycznia 1970 r. Dla istniejącego czasu zdarzenia w JavaScripcie, wyrażonego w milisekundach, eventTimeMs * 1000 daje wymaganą jednostkę. Liczba milisekund omyłkowo przesłana jako mikrosekundy matematycznie wskazuje datę w 1970 r.

Dla znaczników starszych niż 72 godziny Google rozróżnia dwa przypadki. Bez validation_behavior albo przy RELAXED czas zostaje przesunięty na 72 godziny przed odebraniem danych. Przy ENFORCE_RECOMMENDATIONS zdarzenie zostaje odrzucone. Pomyłka jednostek może więc spowodować błędne umiejscowienie w czasie zamiast całkowitej utraty zdarzenia.

Instrukcja wysyłania dodatkowo wskazuje 48-godzinne okno dla łączenia ze zdarzeniami wcześniej zebranymi przez tag lub SDK. Samo dozwolone datowanie wstecz nie gwarantuje prawidłowego przypisania do reklamy lub wcześniejszej wizyty.

Kolejna rozbieżność w dokumentacji dotyczy czasu pojedynczego zdarzenia: instrukcja wysyłania umieszcza timestamp_micros bezpośrednio w zdarzeniu, a opis pól wymienia wartość w parametrach zdarzenia. Proste rozwiązanie używa jednoznacznie udokumentowanego czasu na poziomie żądania i grupuje wyłącznie zdarzenia o tym samym czasie. Różne czasy wymagają wtedy osobnych żądań.

Zgoda i walidacja

Obiekt consent obsługuje ad_user_data i ad_personalization z wartościami GRANTED lub DENIED. Bez tego obiektu GA4 korzysta z ustawień powiązanych interakcji online. analytics_storage i ad_storage nie są tutaj udokumentowanymi polami. Nadawca potrzebuje więc osobnej decyzji o dopuszczalności przesłania przed wysyłką. Brak Client ID lub blokada reklam nie uzasadnia obchodzenia odmowy za pomocą wymyślonych identyfikatorów. non_personalized_ads jest przestarzałe; zastępuje je consent.ad_personalization.

Adres walidacyjny /debug/mp/collect zwraca validationMessages. Te zdarzenia testowe nie pojawiają się w raportach. Google zaleca ENFORCE_RECOMMENDATIONS w testach i pominięcie validation_behavior w produkcji. Pusta lista komunikatów nadal nie potwierdza działania całej drogi: serwer walidacyjny nie sprawdza identyfikatora strumienia ani sekretu API.