# 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…

- Strona: <https://www.datafirefly.com/pl/documentation/google-tag-manager-shopware-ga4-consent-mode-enhanced-conversions/>
- Język: pl
- Zaktualizowano: 2026-07-29
- Inne języki: [fr](https://www.datafirefly.com/documentation/google-tag-manager-shopware-ga4-consent-mode-enhanced-conversions/index.md), [en](https://www.datafirefly.com/en/documentation/google-tag-manager-shopware-ga4-consent-mode-enhanced-conversions/index.md), [es](https://www.datafirefly.com/es/documentation/google-tag-manager-shopware-ga4-consent-mode-enhanced-conversions/index.md), [de](https://www.datafirefly.com/de/documentation/google-tag-manager-shopware-ga4-consent-mode-enhanced-conversions/index.md), [it](https://www.datafirefly.com/it/documentation/google-tag-manager-shopware-ga4-consent-mode-enhanced-conversions/index.md), [nl](https://www.datafirefly.com/nl/documentation/google-tag-manager-shopware-ga4-consent-mode-enhanced-conversions/index.md), [pt](https://www.datafirefly.com/pt/documentation/google-tag-manager-shopware-ga4-consent-mode-enhanced-conversions/index.md)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

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
```

**Wskazówka.** Po `assets:install` plik `df-gtag-manager.js` jest publikowany w `public/bundles/dfgtagmanager/` i staje się dostępny przez helper assetów Twig. Nie jest potrzebny żaden build webpacka ani TypeScriptu.

## 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](https://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](#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](#consent-mode-v2).
- **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](#enhanced-conversions).

### 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)

**Dlaczego wait_for_update: 500?** Ta instrukcja mówi Google, aby odczekał do 500 ms po załadowaniu strony przed wysłaniem hitów w trybie odmowy, dając czas Twojemu banerowi cookies na zebranie odpowiedzi użytkownika, a pluginowi na wypchnięcie `gtag consent update`. Bez tego opóźnienia wszystkie początkowe hity wychodzą w trybie odmowy, nawet jeśli użytkownik natychmiast zaakceptuje.

### 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

**Uwaga.** Google wymaga, aby wartości były zahaszowane już po stronie witryny: nie stosuj do tych zmiennych zmiennej _SHA-256 Hash_ z GTM, one wychodzą z pluginu już zahaszowane. Podwójne haszowanie uniemożliwiłoby dopasowanie.

## 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](https://developers.google.com/tag-platform/tag-manager/server-side))
- 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](https://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 `` 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.