DfGtagManager: kompletna dokumentacja

DfGtagManager to plugin dla Shopware 6.7, który wstrzykuje kontener Google Tag Manager, emituje pełne zdarzenia e-commerce GA4, obsługuje Consent Mode v2 z natywnym banerem cookies Shopware, wysyła Enhanced Conversions haszowane SHA-256 i dopasowuje data layer do Twojego feedu Google Merchant Center. Ta dokumentacja obejmuje instalację, pełną konfigurację i weryfikację.

Wymagania

• Shopware 6.7.0 lub nowszy
• PHP minimum 8.2
• Dostęp SSH albo administracja Shopware do instalacji ZIP-a
• Konto Google Tag Manager (zalecane) albo co najmniej konto Google Analytics 4
• Dla Enhanced Conversions: konto Google Ads ze skonfigurowanymi kampaniami konwersji

Instalacja

Trzy możliwe metody, zależnie od Twojego środowiska.

Z administracji Shopware

1. W panelu: Rozszerzenia → Moje rozszerzenia → Prześlij rozszerzenie
2. Wybierz plik DfGtagManager.zip
3. Kliknij Zainstaluj, a następnie Aktywuj
4. Wyczyść cache: Ustawienia → System → Cache i indeksy → Wyczyść i wygeneruj ponownie

Z wiersza poleceń (zalecane w produkcji)

cd /path/to/shopware
unzip DfGtagManager.zip -d custom/plugins/
bin/console plugin:refresh
bin/console plugin:install --activate DfGtagManager
bin/console assets:install
bin/console cache:clear

Konfiguracja

Otwórz konfigurację: Rozszerzenia → Moje rozszerzenia → DataFirefly Google Tag Manager → menu ⋮ → Konfiguruj. Wybierz odpowiedni sales-channel u góry ekranu: każdy sales-channel może mieć własną, niezależną konfigurację.

Ustawienia ogólne

• Włącz plugin: przełącznik główny. Wyłącz, aby odciąć całe wstrzykiwanie bez odinstalowywania.
• Tryb debug: wyświetla logi z prefiksem [DfGtag] w konsoli przeglądarki (add_to_cart, remove_from_cart, consent update…). Włączaj wyłącznie w środowisku testowym.

Google Tag Manager

• GTM Container ID: format GTM-XXXXXXX. Znajdziesz go na tagmanager.google.com w prawym górnym rogu swojego kontenera. Zostaw puste, jeśli nie używasz GTM: plugin przełączy się automatycznie na loader gtag.js, o ile podano Measurement ID GA4.
• Server-side GTM URL (opcjonalnie): adres URL Twojego loadera Tag Manager server-side (na przykład https://gtm.twojadomena.com, bez końcowego ukośnika). Zobacz sekcję Server-side GTM poniżej.

Google Analytics 4

• GA4 Measurement ID: format G-XXXXXXXXXX. Znajdziesz go w GA4 w Administracja → Strumienie danych → Sieć. Używany jako fallback gtag.js, gdy nie skonfigurowano kontenera GTM, i wypychany do dataLayer na potrzeby tagów GTM.
• Wysyłaj automatyczne zdarzenie page_view: domyślnie włączone. Wyłącz, jeśli wolisz wyzwalać page_view ręcznie z GTM.

Consent Mode v2

• Włącz Consent Mode v2: emituje gtag consent default przed załadowaniem GTM, z siedmioma kategoriami Consent Mode v2. Zobacz Consent Mode v2 w szczegółach.
• Domyślny stan zgody:
  • Odmowa: zalecane dla UE/RODO. Żaden cookie analityczny ani reklamowy nie jest zapisywany przed akceptacją użytkownika.
  • Udzielona: zarezerwuj dla odwiedzających spoza UE albo dla sklepów kierowanych do odbiorców zawodowych nieobjętych RODO.
• Włącz url_passthrough: zachowuje parametry gclid, _gl, dclid między stronami nawet przy odrzuconych cookies. Przydatne przy atrybucji multi-touch.
• Włącz ads_data_redaction przy odmowie: redaguje identyfikatory reklamowe wysyłane do Google Ads, gdy użytkownik odmawia. Dodatkowo zmniejsza powierzchnię śledzenia.

Enhanced Conversions

• Włącz Enhanced Conversions: wypycha obiekt user_data z e-mailem, telefonem, imieniem, nazwiskiem, ulicą, miastem i kodem pocztowym, wszystkim haszowanym SHA-256 po stronie serwera, na stronach confirm i finish ścieżki zakupowej. Zobacz Enhanced Conversions w szczegółach.

Google Shopping / Merchant Center

• Źródło item_id: określa, co plugin wypycha jako item_id w każdym itemie GA4. Ta wartość musi odpowiadać polu id Twojego feedu Merchant Center. Trzy opcje:
  • Product number (SKU): zalecane, najczęstszy format w feedach XML/CSV Merchant Center.
  • Shopware UUID: przydatne, jeśli generujesz feed bezpośrednio z bazy Shopware.
  • EAN / GTIN: przydatne, jeśli Twój feed opiera się na międzynarodowych kodach kreskowych.
• Domyślna kategoria Google: wartość wypychana w google_product_category, gdy ani produkt, ani jego kategoria jej nie definiuje. Format Google (na przykład Apparel & Accessories > Clothing).
• Domyślna marka: używana jako fallback w item_brand, gdy produkt nie ma przypisanego producenta.

Zdarzenia

Każde zdarzenie GA4 można włączyć indywidualnie. Odznacz te, których nie chcesz.

• view_item: karta produktu
• view_item_list: strona kategorii i wyniki wyszukiwania
• add_to_cart: kliknięcie przycisku dodania do koszyka (listener JavaScript)
• remove_from_cart: usunięcie pozycji z koszyka albo z offcanvas
• view_cart: strona koszyka
• begin_checkout: strona potwierdzenia w ścieżce zakupowej
• purchase: strona finish po złożeniu zamówienia
• search: strona wyników wyszukiwania
• login / sign_up: wysłanie formularzy konta

Consent Mode v2 w szczegółach

Consent Mode v2 to oficjalny mechanizm Google do obsługi zgody użytkownika. Od marca 2024 Google Ads wymaga go od reklamodawców kierujących reklamy do Europejskiego Obszaru Gospodarczego: bez niego tracisz dostęp do remarketingu i pomiaru konwersji.

Kolejność ładowania

Plugin gwarantuje następującą kolejność na każdej stronie storefrontu:

1. Inicjalizacja window.dataLayer i stuba gtag()
2. Emisja gtag consent default z siedmioma kategoriami Consent Mode v2 i wait_for_update: 500
3. Emisja url_passthrough i ads_data_redaction, jeśli są włączone
4. Wypchnięcie zdarzeń GA4 danej strony (view_item, view_cart…) do dataLayer
5. Załadowanie skryptu GTM (albo gtag.js jako fallback)

Integracja z banerem cookies Shopware

Plugin dekoruje CookieProviderInterface i rejestruje dwa wirtualne cookies w grupach natywnego banera:

• df-gtag-analytics w grupie Statystyki: steruje analytics_storage
• df-gtag-ads w grupie Marketing: steruje ad_storage, ad_user_data, ad_personalization

Gdy użytkownik zatwierdza swoje preferencje, Shopware emituje zdarzenie CookieConfiguration_Update. Kontroler JavaScript pluginu nasłuchuje tego zdarzenia, odczytuje wartość obu wirtualnych cookies i natychmiast emituje odpowiadający gtag consent update.

Zgodność z banerem firm trzecich

Jeśli zamiast natywnego banera Shopware używasz Cookiebota, CookieFirst, OneTrust albo Axeptio, musisz samodzielnie emitować gtag consent update z tego banera, z właściwymi kategoriami. Plugin Ci tego nie utrudnia: obsługuje wyłącznie początkowy consent default i nasłuch zdarzenia Shopware.

Enhanced Conversions w szczegółach

Enhanced Conversions poprawiają precyzję pomiaru w Google Ads, wysyłając dane użytkownika first-party (e-mail, telefon, imię i nazwisko, adres) haszowane SHA-256 przy konwersji. Google następnie łączy te konwersje z zalogowanymi użytkownikami Google, co zwykle odzyskuje od 10 do 30% konwersji wcześniej traconych przez blokery cookies, ruch cross-device albo zmianę przeglądarki.

Stosowana normalizacja

Plugin normalizuje każde pole zgodnie ze specyfikacją Google przed haszowaniem:

• E-mail: małe litery, przycięte spacje, następnie SHA-256
• Telefon: E.164 (prefiks kraju automatycznie z kodu ISO adresu rozliczeniowego, przykład +48601234567), następnie SHA-256
• Imię, nazwisko, ulica, miasto: małe litery, przycięte spacje, następnie SHA-256
• Kod pocztowy: małe litery, przycięte spacje; dla USA obcinany do pierwszych 5 cyfr przed haszowaniem
• Kraj: kod ISO-2 wielkimi literami, niehaszowany

Payload dataLayer

Przy zdarzeniach begin_checkout i purchase plugin wypycha:

{
  "event": "purchase",
  "ecommerce": { ... },
  "user_data": {
    "sha256_email_address": "...",
    "sha256_phone_number": "...",
    "address": {
      "sha256_first_name": "...",
      "sha256_last_name": "...",
      "sha256_street": "...",
      "sha256_city": "...",
      "postal_code": "...",
      "country": "PL"
    }
  }
}

Konfiguracja w GTM

1. W swoim kontenerze GTM utwórz albo edytuj tag Google Ads Conversion Tracking
2. Sekcja Include user-provided data from your website → Manual configuration
3. Utwórz osiem zmiennych Data Layer Variable wskazujących na:
   • user_data.sha256_email_address → mapowane na Email (hashed)
   • user_data.sha256_phone_number → mapowane na Phone (hashed)
   • user_data.address.sha256_first_name → First name (hashed)
   • user_data.address.sha256_last_name → Last name (hashed)
   • user_data.address.sha256_street → Street (hashed)
   • user_data.address.sha256_city → City (hashed)
   • user_data.address.postal_code → Postal code
   • user_data.address.country → Country
4. Zapisz i opublikuj kontener

Google Shopping i feed Merchant Center

Aby GA4 i Google Ads mogły dopasować zdarzenia e-commerce do Twoich produktów Shopping, każdy item w dataLayer musi używać tego samego item_id co feed Merchant Center.

Pola wypychane w każdym itemie

• item_id: konfigurowalne źródło (SKU / UUID / EAN)
• item_name: nazwa produktu w aktywnym języku
• item_brand: nazwa producenta albo marka domyślna, jeśli nie podano
• item_category do item_category5: pełna ścieżka nawigacyjna od najgłębszej kategorii
• google_product_category: zobacz niżej
• price, quantity, currency
• mpn: Manufacturer Part Number, jeśli uzupełniony na produkcie
• gtin: EAN, jeśli uzupełniony
• discount: obliczany z różnicy między ceną przekreśloną a ceną sprzedaży

google_product_category per produkt

Możesz nadpisać kategorię Google Shopping dla produktu albo kategorii przez pole niestandardowe:

1. W panelu: Ustawienia → System → Pola niestandardowe → Utwórz nowy zestaw
2. Nazwa techniczna: df_google_product_category, typ Tekst
3. Przypisz ten zestaw do encji Produkt i/albo Kategoria
4. Na każdym produkcie albo kategorii uzupełnij wartość Google (na przykład Sporting Goods > Athletics > Football > Football Balls)

Plugin szuka wartości w tej kolejności: pole niestandardowe produktu → pole niestandardowe jego najgłębszej kategorii → globalna wartość domyślna z konfiguracji.

Server-side GTM

Tagowanie server-side pozwala kierować ruch GTM przez domenę, którą kontrolujesz, co omija blokery przeglądarkowe, chroni dane użytkowników i poprawia odporność na zmiany polityk cookies.

Wymagania

• Skonfigurowany kontener server-side GTM (zobacz dokumentację Google)
• Dedykowana domena albo subdomena wskazująca na Twój serwer Tag Manager, na przykład gtm.twojadomena.com

Aktywacja

W konfiguracji pluginu, w sekcji Google Tag Manager, uzupełnij Server-side GTM URL swoją domeną bez końcowego ukośnika:

https://gtm.twojadomena.com

Skrypt GTM i ramka noscript będą automatycznie wskazywać na Twój serwer zamiast na www.googletagmanager.com.

Weryfikacja

Google Tag Assistant

1. Zainstaluj rozszerzenie Chrome Tag Assistant Companion
2. Otwórz tagassistant.google.com, kliknij Add domain i wpisz adres swojego storefrontu
3. Przejdź na kartę produktu, dodaj do koszyka, przejdź do checkoutu: każdy krok powinien pojawić się w asystencie wraz z odpowiadającymi zdarzeniami GA4

GA4 DebugView

W GA4: Administracja → DebugView. Zdarzenia pojawiają się tam w czasie rzeczywistym, gdy tryb debug jest aktywny w pluginie albo gdy wysyłany jest parametr debug_mode=true.

Tryb debug pluginu

Włącz Tryb debug w konfiguracji, a następnie otwórz konsolę przeglądarki. Zobaczysz:

[DfGtag] consent update { analytics_storage: "granted", ad_storage: "denied", ... }
[DfGtag] add_to_cart { item_id: "SW10001", item_name: "...", price: 129, quantity: 1 }
[DfGtag] remove_from_cart { ... }

Lista kontrolna walidacji

• Na stronie głównej: consent default emitowany przed skryptem GTM (kolejność znaczników w sekcji head)
• Na karcie produktu: view_item z item_id, item_brand, item_category, google_product_category
• Przy dodaniu do koszyka: add_to_cart z tym samym itemem
• W koszyku: view_cart ze wszystkimi itemami
• Na stronie confirm: begin_checkout z zahaszowanym user_data
• Na stronie finish: purchase z transaction_id, value, tax, shipping, currency, items i zahaszowanym user_data
• Przy akceptacji cookies: consent update z kategoriami granted

Rozwiązywanie problemów

Zdarzenia nie pojawiają się w GA4 DebugView

• Sprawdź, czy Measurement ID GA4 w konfiguracji jest poprawne
• Sprawdź, czy tag GA4 Configuration jest utworzony i opublikowany w Twoim kontenerze GTM
• Sprawdź, czy wyzwalacz tagu obejmuje wszystkie strony (All Pages)
• Wyczyść cache Shopware i przeładuj stronę twardym odświeżeniem (Ctrl+F5)

Enhanced Conversions nie dopasowują się

• Sprawdź, czy do zmiennych user_data nie jest stosowana dodatkowa transformacja (zmienna SHA-256 Hash z GTM): wartości wychodzą już zahaszowane
• Sprawdź format E.164 telefonu w dataLayer (z prefiksem kraju zaczynającym się od +)
• Sprawdź, czy pole country jest w ISO-2 wielkimi literami (PL, a nie Polska)
• Odczekaj 24 do 48 godzin po aktywacji: Google Ads potrzebuje tego czasu na pierwszą synchronizację

Consent update nie jest emitowany, gdy użytkownik akceptuje

• Potwierdź, że używany baner to rzeczywiście natywny baner Shopware
• Otwórz konsolę przeglądarki w trybie debug i sprawdź, czy zdarzenie CookieConfiguration_Update jest emitowane, gdy użytkownik zatwierdza baner
• Sprawdź, czy cookies df-gtag-analytics i df-gtag-ads pojawiają się w banerze i są zaznaczone

item_id nie pasuje do mojego feedu Merchant Center

• Otwórz swój feed XML/CSV i sprawdź pole <g:id> dla jednego produktu
• W konfiguracji pluginu wybierz źródło item_id, które daje dokładnie tę samą wartość (SKU, UUID albo EAN)
• Jeśli Twój feed używa prefiksu (na przykład shopware_SW10001), trzeba utworzyć tag GTM dodający prefiks do wartości przed wysyłką do Google Ads

Plugin nie ładuje się na niektórych stronach

• Sprawdź, czy bieżący sales-channel ma Włącz plugin ustawione na ON w swojej własnej konfiguracji
• Niektóre strony niestandardowe (własne landing page CMS) mogą nie wyzwalać standardowych Page Loaded Events. W takim przypadku kontener GTM i tak jest ładowany przez header pagelet.