Kiedy Measurement Protocol ma sens, a kiedy to przerost formy

Measurement Protocol wygrywa w czterech konkretnych sytuacjach i tylko w nich warto go wdrażać:

• Zamówienia z ERP lub telefoniczne. Klient składa zamówienie przez telefon albo w systemie sprzedażowym (Subiekt, Comarch, własny panel). Rekord powstaje w bazie, w przeglądarce nie ma czego wysłać.
• Zamówienia B2B wystawiane ręcznie. Handlowiec tworzy zamówienie w back-office po negocjacji mailowej. Jeśli korzystasz z PrestaShop, warstwę zamówień po stronie serwera opisuje dokumentacja dla deweloperów PrestaShop.
• Zwroty księgowane po dniach. Dział księgowości zapisuje korektę 6–14 dni po zakupie. Sesja dawno wygasła, tag w przeglądarce nie ma czego wysłać.
• Rekordy tworzone poza przeglądarką. Odnowienia subskrypcji, dopłaty do zamówienia, faktury korygujące.

Różnica nie polega na tym, że MP jest „lepszy”. Client-side (gtag, GTM, dataLayer) odpala się tylko wtedy, gdy przeglądarka wykona JavaScript. Blokada reklam, brak zgody w CMP, przeładowanie strony po kliknięciu „Kupuję” — każde z nich oznacza utracony purchase. Przy typowym ruchu konsumenckim to nie 2%, a często 5–15% transakcji. MP wysyła żądanie z serwera Twojej aplikacji, więc te blokady go nie dotyczą.

Ale MP ma twarde ograniczenie: zdarzenie nie pojawi się w raportach zaangażowania (Zaangażowanie, Ścieżki, Eksplorator użytkowników), jeśli nie dołączysz engagement_time_msec i session_id. Bez nich GA4 przyjmie przychód, ale nie przypisze zdarzenia do sesji. Druga rzecz: MP nie odtworzy źródła ruchu. Zamówienie telefoniczne bez session_id wyląduje jako direct/none — kanał, który je wygenerował, zniknie z raportu.

Zasada do trzymania: jedno źródło prawdy dla transakcji. Albo purchase wysyła przeglądarka, a MP tylko uzupełnia braki (telefon, ERP, zwroty), albo wysyła wyłącznie serwer — nigdy oba dla tego samego transaction_id.

Endpoint, api_secret i measurement_id — minimalny działający request

Adres: https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXX&api_secret=XXXXXXXX. Metoda POST, nagłówek Content-Type: application/json. Oba parametry idą w query stringu, nie w body.

Skąd je wziąć:

1. measurement_id — Administracja → Strumienie danych → wybierz strumień WWW. Format: G- z dziesięcioma znakami.
2. api_secret — ten sam ekran → Measurement Protocol API secrets → Utwórz. Utwórz osobny sekret dla każdej integracji (ERP, zwroty, subskrypcje). Gdy będziesz rotować jeden z nich, nie unieruchomisz całego e-commerce. Sekret trzymaj w zmiennych środowiskowych, nigdy w kodzie frontendu.

Limity, które wyznaczają architekturę wysyłki: maksymalnie 25 zdarzeń w jednym żądaniu i do 1 MB payloadu. 500 zaległych zamówień z ERP to minimum 20 żądań — zaplanuj pętlę z paczkowaniem po 25 i krótkim opóźnieniem między żądaniami.

Minimalne body, które GA4 przyjmie:

{
  "client_id": "1234567890.1698765432",
  "events": [
    {
      "name": "purchase",
      "params": {
        "transaction_id": "ZAM-2024-1938",
        "currency": "PLN",
        "value": 249.00
      }
    }
  ]
}

Skąd client_id: z ciasteczka _ga, czyli część po GA1.1. (np. 1234567890.1698765432). Jeśli zamówienie przyszło z telefonu i nie masz tego identyfikatora, wygeneruj własny, zapisz go przy kliencie w CRM i używaj konsekwentnie w kolejnych zdarzeniach. Bez client_id GA4 potrafi przypisać zdarzenie do losowego identyfikatora, a walidacja zwrócić błąd 400 — tracisz możliwość powiązania zamówień jednego klienta.

Zanim puścisz cokolwiek na produkcję, wyślij ten sam request na https://www.google-analytics.com/debug/mp/collect. Zwraca JSON z sekcją validationMessages, w której zobaczysz brakujące lub źle nazwane parametry. Produkcyjny endpoint odpowiada pustym 204 i nie powie Ci, co zrobiłeś źle.

Payload zdarzenia purchase — pole po polu

Kompletny zestaw parametrów dla zakupu wygląda tak: transaction_id (unikalny, do 500 znaków), currency w standardzie ISO 4217, value, tax, shipping, coupon oraz tablica items[]. Do tego engagement_time_msec i session_id — bez nich nie zobaczysz zdarzenia w raportach zaangażowania.

Parametr nazywa się session_id, a wartość bierzesz z ga_session_id, czyli drugiej liczby z ciasteczka _ga_<container> albo z parametru session_id przekazanego przez gtag do serwera przy składaniu zamówienia. Zapisz ją razem z zamówieniem w bazie — inaczej nie odtworzysz jej po fakcie.

Dwie pułapki, które psują raporty najczęściej:

• value bez items — dostajesz przychód bez danych produktowych. Raporty „Sprzedane produkty” i „Przychód z pozycji” zostają puste, nie odpowiesz na pytanie, co się sprzedaje.
• items bez wartości liczbowych — price musi być liczbą (234.00), nie stringiem („234,00 zł”). GA4 policzy przychód pozycji jako 0 i suma pozycji rozjedzie się z value. To samo dotyczy quantity — liczba całkowita, nie „2 szt.”.

Przyjmij jedną zasadę i się jej trzymaj: value = kwota faktycznie zapłacona przez klienta (z dostawą i podatkiem, po rabacie). Wtedy tax i shipping są tylko informacją dodatkową w raporcie.

Pełny JSON z jedną pozycją, gotowy do podmiany wartości:

{
  "client_id": "1234567890.1698765432",
  "events": [
    {
      "name": "purchase",
      "params": {
        "transaction_id": "ZAM-2024-1938",
        "currency": "PLN",
        "value": 249.00,
        "tax": 46.54,
        "shipping": 15.00,
        "coupon": "WIOSNA10",
        "engagement_time_msec": 100,
        "session_id": "1698765400",
        "items": [
          {
            "item_id": "SKU-1042",
            "item_name": "Fotel biurowy Ergofix 200",
            "price": 234.00,
            "quantity": 1,
            "item_brand": "Ergofix",
            "item_category": "Meble biurowe"
          }
        ]
      }
    }
  ]
}

Pola item_id, item_name, price, quantity, item_brand i item_category mapuj wprost z pozycji zamówienia w sklepie — w WooCommerce to line items, których strukturę opisuje dokumentacja WooCommerce. Nie wymyślaj własnych nazw parametrów: GA4 nie ma dla nich slotu i po cichu je zignoruje.

Refund: pełny i częściowy zwrot bez psucia przychodu

Zdarzenie refund pomniejszy przychód tylko wtedy, gdy zawiera dokładnie ten sam transaction_id, który wcześniej wysłałeś w purchase. GA4 szuka po nim transakcji. Wystarczy, że ERP dopisze przedrostek (WEB-ORD-10241 zamiast ORD-10241) i zwrot nie połączy się z zakupem — przychód w raporcie rośnie, a zwroty wiszą osobno jako osobne zdarzenia.

Zwrot całego zamówienia to jeden refund z transaction_id i pełną kwotą zwrotu w value. Zwrot pojedynczej pozycji to refund, w którym przekazujesz wyłącznie zwracane items, z ujemną quantity i wartością zwrotu. Reszta zamówienia zostaje nienaruszona — dlatego to dwa różne payloady i dwa różne skutki w raportach.

Przykład zwrotu częściowego (jeden z trzech produktów):

{"client_id":"1234567890.1716200000","events":[{"name":"refund","params":{"transaction_id":"ORD-10241","currency":"PLN","value":-89.9,"items":[{"item_id":"SKU-4410","quantity":-1,"price":89.9}]}}]}

Kolejność zdarzeń ma znaczenie: refund musi trafić po purchase. Zwrot wysłany przed zakupem nie ma czego pomniejszyć i przepada bez śladu w raportach.

Najczęstsza pułapka to czas. Zwroty księgowane w ERP po kilku dniach muszą przejść przez kolejkę, która wyśle zdarzenie z timestamp_micros odpowiadającym momentowi księgowania — nie dacie zamówienia. GA4 odrzuca zdarzenia starsze niż 72 godziny, a znacznik z przyszłości również jest odrzucany. Kolejkę projektuj jako at-least-once: klucz refund_{transaction_id}_{refund_id}, log statusów i kontrolowane ponowienia, żeby jeden nieudany request nie zniknął w ciszy. Jeśli sklep działa na PrestaShop, całą operację podpina się pod hook zamówienia — mechanikę hooków opisuje dokumentacja dla deweloperów PrestaShop.

Deduplikacja: purchase z przeglądarki i z serwera w jednym sklepie

GA4 ma wbudowaną deduplikację purchase po transaction_id, ale ona nie zastąpi spójnej architektury wysyłki. Nie naprawi sytuacji, w której ten sam zakup leci dwa razy z dwóch różnych źródeł i z dwoma różnymi client_id — w raportach zobaczysz dwa zakupy, podwójny przychód i podwójną konwersję.

Typowy scenariusz: GTM wysyła purchase z przeglądarki na stronie „Dziękujemy”, a integracja z ERP wysyła to samo zdarzenie po zmianie statusu na „opłacone”. Jeśli ERP nie pobrało cookie _ga z zamówienia, wysyła inny client_id i nic ich nie połączy.

Rekomendacja: jedno źródło prawdy. purchase wysyła serwer, a tag w przeglądarce zostaje wyłączony — nie „ukryty”, tylko usunięty z kontenera GTM. Wtedy nie musisz zgadywać, które zdarzenie wygrało w raportach.

• Kolejka po stronie serwera: klucz idempotencji purchase_{transaction_id}, blokada powtórnej wysyłki na poziomie bazy, statusy pending/sent/failed i osobny log requestów.
• Ponowienia tylko dla błędów 5xx i timeoutów. HTTP 400 z Measurement Protocol oznacza błąd w payloadzie — kolejna próba nic nie da, trzeba poprawić dane.
• Wysyłka na jeden, zdefiniowany status zamówienia. Nie wysyłaj purchase przy każdej zmianie statusu, bo część sklepów ma ich pięć.

Wykrycie dubli: w eksporcie GA4 do BigQuery porównaj COUNT(DISTINCT transaction_id) z liczbą wierszy purchase w tym samym okresie. Każda różnica to albo duplikat, albo zdarzenie bez transaction_id — jedno i drugie psuje raporty.

Identyfikacja użytkownika i atrybucja: client_id, user_id, session_id

Zdarzenie wysłane z serwera bez identyfikatorów wejdzie do raportów jako (direct)/(none) lub „Unassigned”. Liczba się zgadza, atrybucja kanałowa już nie — i cały sens serwerowej wysyłki znika.

client_id pochodzi z cookie _ga i ma format GA1.1.XXXXXXXXXX.YYYYYYYYYY. Identyfikatorem jest część po ostatniej kropce w wersji z prefiksem, czyli dwa ostatnie segmenty. Zapisz go w zamówieniu w momencie składania — polem ukrytym w formularzu albo metą zamówienia. Z ERP go nie odtworzysz. Jeśli cookie nie ma (brak zgody na analitykę, blokada, wygasło), nie zmyślaj wartości: albo wyślij zdarzenie bez client_id, albo wygeneruj własny identyfikator i zaakceptuj, że w GA4 powstanie nowy „użytkownik”.

user_id to identyfikator zalogowanego klienta z systemu sklepu, np. numer konta. Wysyłaj go w formie zhashowanej — SHA-256 z solą dodaną po stronie serwera. Nigdy nie wysyłaj e-maila ani loginu: to dane osobowe, a GA4 nie przyjmuje PII. Hash musi być stały dla danego klienta, inaczej rozjedzie ci się ścieżka cross-device.

session_id (ga_session_id) pobierzesz z cookie _ga_<ID_kontenera> lub ze zdarzenia session_start. Przekazany razem z client_id pozwala wpiąć zdarzenie w istniejącą sesję, zamiast tworzyć nową — sesja z kampanii nie rozbije się na dwie i kanał nie zostanie zgubiony.

timestamp_micros ustawiaj ostrożnie: zdarzenia wsteczne mają limit 72 godzin, a znacznik z przyszłości jest odrzucany. Zwrot księgowany po pięciu dniach wejdzie z datą wysyłki, nie z datą zamówienia — zaplanuj to w raportowaniu.

Implementacja krok po kroku w PrestaShop i WooCommerce

W PrestaShop zdarzenie zakupu podpinasz pod hook actionValidateOrder — odpala się w momencie zatwierdzenia zamówienia, a w parametrach dostajesz obiekt order, z którego bierzesz id, total_paid, id_currency i listę pozycji przez getProducts(). Osobnego hooka „refund” nie ma — obserwujesz zmianę statusu w actionOrderStatusPostUpdate (parametry newOrderStatus, id_order). Jeśli nowy status to ten skonfigurowany u Ciebie jako „Zwrócono”, wysyłasz refund. Warunek: kwota zwrotu to nie total_paid, tylko wartość faktycznie zaksięgowana — inaczej zwroty częściowe zawyżą korektę przychodu.

W WooCommerce masz dwie drogi. Push: webhooki z topicami order.completed i refund.created, podpisane nagłówkiem X-WC-Webhook-Signature (HMAC-SHA256 na surowym body) — podpis weryfikuj, bo endpoint przyjmujący dane z zewnątrz bez weryfikacji to zaproszenie do śmieci w raportach. Pull: REST API, np. GET /wp-json/wc/v3/orders?status=completed&modified_after=... oraz .../orders/{id}/refunds. Pull jest odporniejszy na zaginione webhooki, ale wymaga paginacji i własnego wskaźnika ostatniego pobrania.

Sam POST do MP nie może siedzieć w ścieżce zamówienia — jeśli Google zwróci 500, nie chcesz blokować płatności. Wzorzec: zdarzenie ląduje w tabeli kolejki (id, event_name, transaction_id, payload, status, attempts, next_attempt_at), cron co minut bierze paczkę np. 50 rekordów i wysyła. Retry z backoffem: 1, 5, 15, 60, 240 minut, po szóstej próbie status dead i alert mailem. api_secret trzymaj w zmiennej środowiskowej, nie w repozytorium; rotuj co 90–180 dni, a w trakcie rotacji utrzymuj dwa aktywne sekrety.

Loguj minimum: transaction_id, typ zdarzenia, kod HTTP odpowiedzi, pełny payload i czas. MP zwraca 204 bez treści, więc sam kod to za mało — bez payloadu nie odtworzysz, co poszło.

Testowanie i debugowanie, zanim dane trafią do raportów

Zanim cokolwiek pojawi się w raportach, wyślij zdarzenie na endpoint walidacyjny /debug/mp/collect — zamiast /mp/collect, z tym samym measurement_id i api_secret. Odpowiedź zawiera validationMessages. Czytaj je dosłownie, punkt po punkcie. Jeśli komunikat mówi o nieznanej walucie, nie zgaduj, że „to pewnie nic nie znaczy” — popraw i wyślij ponownie. Walidacja wyłapuje rzeczy, których nie pokaże żaden inny ekran: literówki w nazwach parametrów, stringi w polach liczbowych, brak wymaganego currency.

Drugi krok to DebugView w GA4. To jedyne miejsce, w którym potwierdzasz, że zdarzenie w ogóle dotarło. Wymaga debug_mode: true w parametrach zdarzenia albo ?debug_mode=1. Uwaga: dane w DebugView żyją krótko — jeśli szukasz zdarzenia z zeszłego tygodnia, już go tam nie będzie. To narzędzie do testu tu i teraz, nie do audytu.

Trzeci krok to cierpliwość. Raporty standardowe pokazują dane częściowo po kilku godzinach, ale pełne przetworzenie potrafi zająć kilkadziesiąt godzin. Sprawdzanie raportu 20 minut po wdrożeniu i wyciąganie wniosków to najczęstszy sposób na niepotrzebną panikę i cofanie działającej integracji.

Ostateczna weryfikacja: eksport do BigQuery. W tabeli events_YYYYMMDD widzisz surowe zdarzenia bez agregacji i sprawdzisz dokładnie, co poszło: czy transaction_id się zgadza, czy items ma komplet pozycji, czy value jest liczbą. Zapytanie z UNNEST(event_params) to podstawa takiego sprawdzenia.

Test kontrolny na koniec: wyślij zdarzenie z celowo złym currency (np. PLN1) na endpoint debug i przeczytaj komunikat. Zapamiętaj jego treść — następnym razem rozpoznasz ten sam problem w logach w kilka sekund. Pamiętaj, że adres debug zawiera api_secret, więc nie wklejaj go do zgłoszeń i ticketów.

Pułapki, które psują dane — z sposobem ich wykrycia

Objawy widać w raportach, przyczyny siedzą w payloadzie albo w kolejce. Zestawienie objaw–przyczyna–diagnoza:

Objaw	Przyczyna	Metoda diagnozy
Przychód wyższy niż w sklepie	Duble purchase	Porównanie liczby wystąpień transaction_id
Brak pozycji w raportach produktowych	Brak items lub niepoprawne typy liczbowe	Sprawdzenie tablicy items w BigQuery i typów price, quantity
Zwroty nie pomniejszają przychodu	Inny transaction_id lub brak currency	Porównanie znak w znak z pierwotnym purchase
Zerowe sesje przy zdarzeniach z MP	Brak engagement_time_msec i session_id	Podgląd parametrów zdarzenia w DebugView
Zdarzenia nie pojawiają się wcale	Przekroczony limit 25 zdarzeń w request, payload powyżej 1 MB lub zły api_secret	Rozmiar i liczba zdarzeń w payloadzie, kod HTTP z kolejki

Diagnozę dubli rób po stronie serwera, nie w GA4: SELECT transaction_id, COUNT(*) FROM mp_queue GROUP BY 1 HAVING COUNT(*) > 1. Jeśli wynik jest większy niż jeden, sprawdź, czy hook nie odpala się dwukrotnie (w PrestaShop zdarza się przy ponownej walidacji zamówienia) albo czy nie przyszła powtórka webhooka z WooCommerce. Wygodne zabezpieczenie: przed wysłaniem sprawdź, czy dla danej pary transaction_id i typu zdarzenia nie ma już rekordu ze statusem sent.

Typy danych to druga cicha pułapka. price jako string („49.99”) przejdzie przez request, ale wiersz w raporcie produktowym zostanie pusty. Pilnuj, żeby value, price i quantity były liczbami, a item_id niepuste i zgodne z identyfikatorami w sklepie.

Przy zwrotach najważniejsza jest dyscyplina: ten sam transaction_id i ta sama waluta co w purchase. Inaczej zdarzenie dotrze, ale nie skoryguje przychodu.

Najczęstsze błędy i jak je wykryć

Lista kontrolna do odklikania

• Osobny api_secret dla strumienia — Wygeneruj w GA4: Admin, Data Streams, wybrany strumień, Measurement Protocol API secrets. Sprawdź, że sekret należy do tego samego strumienia, do którego wysyłasz zdarzenia.
• Sekret po stronie serwera — Zweryfikuj, że klucz nie występuje w plikach JS, szablonach ani publicznym repozytorium. Wyszukaj go w kodzie przed wdrożeniem na produkcję.
• Poprawny measurement_id — Format G-XXXXXXX, ten sam co w tagu na stronie. Sprawdź w Admin, Data Streams, przed pierwszym testem.
• client_id spójny z zamówieniem — Zapisz client_id (z cookie _ga lub wygenerowany) razem z zamówieniem w bazie albo ERP, żeby użyć go zarówno przy purchase, jak i przy refund.
• Unikalny transaction_id — Sprawdź, czy identyfikator jest unikalny w sklepie i zapisany w bazie. Do 500 znaków, bez spacji na końcu.
• currency zgodne z zamówieniem — Kod ISO 4217, np. PLN. Sprawdź na zamówieniach w innej walucie — rozjazd walut zaburza sumy w raportach.
• value zgodne z konwencją — Ustal raz, czy value zawiera podatek i dostawę, i trzymaj się tego w każdym zdarzeniu. Porównaj z polem używanym w przeglądarce.
• items kompletne i liczbowe — item_id, item_name, price, quantity jako liczby. Sprawdź payload wypisany do logów przed wysłaniem.
• ga_session_id i engagement_time_msec — Dodaj, jeśli zamówienie powstało w sesji przeglądarkowej i chcesz widzieć je w raportach zaangażowania. Dla zamówień z ERP przyjmij, że danych sesyjnych nie będzie.
• Test w DebugView — Wyślij request z payloadem testowym i sprawdź zdarzenie w DebugView. Brak zdarzenia przy odpowiedzi 204 oznacza problem z payloadem, nie z połączeniem.
• Batchowanie i limity — Maksymalnie 25 zdarzeń w jednym żądaniu i do 1 MB payloadu. Przy migracji historii zamówień podziel dane na paczki i loguj odpowiedzi.
• Deduplikacja z tagiem w przeglądarce — Sprawdź na kilku zamówieniach, czy purchase nie leci z dwóch miejsc. Porównaj liczbę transakcji w GA4 z liczbą zamówień w sklepie.
• Zwroty z kolejki i poprawny czas zdarzenia — Jeśli zwroty księgujesz po kilku dniach, zaplanuj kolejkę i ustawiaj timestamp_micros. Sprawdź, czy data zdarzenia mieści się w oknie przyjmowanym przez GA4.
• Miesięczne porównanie z księgowością — Raz w miesiącu zestaw przychód i zwroty z GA4 z danymi z ERP lub sklepu. Różnica powyżej kilku procent to sygnał do sprawdzenia payloadów.

Najczęściej zadawane pytania

Źródła i materiały

• schema.org – lista typów
• PrestaShop – dokumentacja dla deweloperów
• WooCommerce – dokumentacja
• Google Ads – dokumentacja API
• Google Search Central – tworzenie treści dla ludzi