Google Analytics
Moduł google_analytics łączy storefront z Google Analytics 4: aktywacja i Measurement ID osobno
dla każdego kanału sprzedaży, Enhanced Ecommerce, konfigurowany w panelu kreator zdarzeń własnych
oraz opcjonalne wysyłanie danych przez tagowanie po stronie serwera. To moduł oddzielny od
wewnętrznego dziennika zdarzeń analytics i zastępuje tamtejszy mechanizm przekazywania do GA4,
włączany zmienną środowiskową.
Konfiguracja (moduł ustawień)
Cała konfiguracja dla kanałów znajduje się w module ustawień, w grupie google_analytics.*
(wartość globalna i nadpisanie dla kanału):
| Ustawienie | Typ | Znaczenie |
|---|---|---|
google_analytics.enabled | boolean | Główny przełącznik (można go nadpisać dla kanału). |
google_analytics.measurement_id | string | GA4 G-XXXXXXXXXX. Pusty ⇒ kanał nie jest śledzony. |
google_analytics.enhanced_ecommerce_enabled | boolean | Wysyłanie zdarzeń e-commerce GA4. |
google_analytics.server_side_enabled | boolean | Wysyłanie zdarzeń przez workera po stronie serwera. |
google_analytics.server_side_endpoint | string | Adres kontenera GTM po stronie serwera (pusty ⇒ GA4 Measurement Protocol). |
google_analytics.server_side_api_secret | secret | Sekret API Measurement Protocol (wymaga SETTINGS_SECRET_ENCRYPTION_KEY). |
google_analytics.require_consent | boolean | Ładuje GA w trybie Consent Mode v2 z domyślną odmową, dopóki użytkownik nie wyrazi zgody. |
Kanał z pustym Measurement ID niczego nie wysyła, niezależnie od głównego przełącznika.
Działanie w storefroncie
gtag.jsjest wstawiany przeznext/script(afterInteractive, bezpiecznie dla Core Web Vitals) i inicjalizowany zsend_page_view: false.page_viewjest wysyłane przy każdej nawigacji w App Routerze (pierwsze wczytanie i każda zmiana trasy po stronie klienta) — dokładnie jedno na stronę docelową.- Consent Mode v2: gdy
require_consentjest włączone, GA startuje z domyślną odmową. Baner cookie wywołujeupdateAnalyticsConsent(granted), aby przełączyć na zgodę. (Ten moduł dostarcza mechanizm obsługi zgody, a nie gotowy baner cookie). - Enhanced Ecommerce (gdy włączone):
view_item(strona produktu),add_to_cart,begin_checkout(checkout) ipurchase(strona potwierdzenia zamówienia).
Zdarzenia własne
Administratorzy definiują zdarzenia własne na ekranie /google-analytics w panelu. Każde zdarzenie
ma nazwę (w formacie nazw zdarzeń GA4), działanie, które je wywołuje, i wybrany podzbiór pól
dostępnych dla tego działania:
| Działanie | Dostępne pola |
|---|---|
contact_form_submitted | wszystkie pola formularza kontaktowego oprócz przesyłanych plików |
place_order_clicked | pola wysyłane przy składaniu zamówienia |
add_to_cart / add_to_quote_request / add_to_shopping_list | sku, name, price, quantity |
button_click_by_id | strona, na której nastąpiło kliknięcie, i atrybuty data-* przycisku (wymaga identyfikatora przycisku) |
Wysyłane są tylko wybrane pola; brakujące są pomijane (nigdy nie blokują zdarzenia). Przesyłane pliki nigdy nie są dołączane. Zdarzenia własne mogą dotyczyć jednego kanału albo wszystkich, a do jednego działania można przypisać wiele zdarzeń.
Storefront nie ma jeszcze formularza kontaktowego; działanie
contact_form_submittedjest dostarczane jako hook po stronie klienta (trackContactFormSubmit), który zacznie działać po dodaniu formularza.
Tagowanie po stronie serwera (wyłącznie Measurement Protocol)
Gdy dla kanału włączone jest server_side_enabled, moduł realizuje tagowanie wyłącznie po stronie
serwera, przez własny serwer platformy — bez zewnętrznego kontenera i bez biblioteki Google w
przeglądarce:
- gtag.js nie jest ładowany. Każde zdarzenie (page_view, Enhanced Ecommerce, własne) jest
wysyłane do
POST /api/v1/storefront/google-analytics/collect, więc żadne żądanie nie trafia z przeglądarki bezpośrednio do Google (najlepsza odporność na programy blokujące reklamy, brak podwójnego liczenia przez klienta i serwer). - Trasa tylko dodaje zadania — sprawdza każde zdarzenie i dodaje jedno zadanie na zdarzenie do
trwałej kolejki BullMQ
google_analytics.ss.deliver. Osobny worker (działający w procesie API, chyba że ustawionoBACKEND_ROLE=api— wtedy tylko w procesieworker) przekazuje każde zdarzenie do GA4 przez Measurement Protocol i ponawia próbę po błędzie. Każde zdarzenie ma stały klucz idempotencjieventId. - Zakończone zadania znikają z Redis w ciągu godzin lub dni. Zadanie wysyłki zawiera
client_idodwiedzającego i parametry zdarzenia, więc kolejka przechowuje wysłane zadanie najwyżej godzinę, a zadanie, któremu zabrakło prób, najwyżej trzy dni — wystarczająco długo, by zdiagnozować niedziałający adres docelowy. Poza tym przechowuje nie więcej niż 500 ostatnich wysłanych i 5 000 ostatnich nieudanych zadań. Cogodzinne sprawdzenie w procesie workera usuwa przeterminowane zadania nawet wtedy, gdy nie przychodzi żadne nowe zdarzenie. Działa tylko wtedy, gdy moduł jest włączony, a pierwszy przebieg po ponownym włączeniu usuwa to, co w tym czasie się przeterminowało. - Nieskonfigurowany kanał nie dodaje żadnych zadań. Dla kanału, w którym wysyłka po stronie
serwera nie jest skonfigurowana — główny przełącznik albo
server_side_enabledjest wyłączony albo Measurement ID jest pusty — trasa nie dodaje żadnego zadania i odpowiada202zaccepted: 0. Storefront w ogóle nie wysyła żądań dla takiego kanału; taką odpowiedź dostaje żądanie ze strony, która wciąż ma starszą konfigurację. - Domyślne metryki GA4 działają bez dodatkowej pracy. Przeglądarka utrzymuje własny
client_idi odnawiany co 30 minutsession_id(w ciasteczkach dopiero po wyrażeniu zgody, wcześniej tylko w pamięci) i wysyłaengagement_time_msecz każdym zdarzeniem, więc GA4 sam wyznaczafirst_visit,session_start, sesje i aktywnych użytkowników ze strumienia Measurement Protocol. - Opcjonalny inny adres docelowy. Domyślnie worker wysyła dane do endpointu GA4 Measurement
Protocol. Ustaw
server_side_endpoint, aby kierować zdarzenia pod inny adres (np. własny serwer pośredniczący albo kontener GTM po stronie serwera).server_side_api_secret(sekret API Measurement Protocol, tworzony w GA4 Admin → Data Streams → Measurement Protocol API secrets) uwierzytelnia wysyłkę. - Zgoda jest przekazywana w danych Measurement Protocol (
analyticsStorage) i odzwierciedla rzeczywistą decyzję odwiedzającego w banerze. - Enhanced Measurement jest odtwarzane w przeglądarce (bo gtag.js nie jest ładowany) i
przekazywane przez serwer:
scroll(90%), wychodząceclick,file_download,form_start/form_submitiview_search_results(wyszukiwanie w sklepie). Zaangażowanie w wideo nie jest obsługiwane — wymagałoby integracji z odtwarzaczem YouTube po stronie klienta. W trybie klienckim gtag.js wysyła to wszystko samodzielnie.
Uprawnienia
google_analytics:read i google_analytics:write chronią ekrany w panelu administracyjnym
(zarządzanie zdarzeniami własnymi). Ustawieniami dla kanałów zarządza się na ogólnym ekranie
ustawień w panelu.