# DfGtagManager — Vollständige Dokumentation

> DfGtagManager ist ein Shopware-6.7-Plugin, das einen Google-Tag-Manager-Container injiziert, die vollständigen GA4-E-Commerce-Events emittiert, Consent Mode v2 über das native Shopware-Cookie-Banner verwaltet, SHA-256-gehashte Enhanced Conversions pusht und den Data Layer an Ihrem…

- Seite: <https://www.datafirefly.com/de/documentation/google-tag-manager-shopware-ga4-consent-mode-enhanced-conversions/>
- Sprache: de
- Aktualisiert am: 2026-07-01
- Weitere Sprachen: [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), [it](https://www.datafirefly.com/it/documentation/google-tag-manager-shopware-ga4-consent-mode-enhanced-conversions/index.md), [pl](https://www.datafirefly.com/pl/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)
- Index: <https://www.datafirefly.com/de/documentation/llms.txt>

DfGtagManager ist ein Shopware-6.7-Plugin, das einen Google-Tag-Manager-Container injiziert, die vollständigen GA4-E-Commerce-Events emittiert, Consent Mode v2 über das native Shopware-Cookie-Banner verwaltet, SHA-256-gehashte Enhanced Conversions pusht und den Data Layer an Ihrem Google-Merchant-Center-Feed ausrichtet. Diese Dokumentation deckt Installation, vollständige Konfiguration und Verifizierung ab.

## Voraussetzungen

- Shopware 6.7.0 oder neuer
- PHP 8.2 mindestens
- SSH- oder Shopware-Admin-Zugriff zur Installation des ZIP
- Ein Google-Tag-Manager-Konto (empfohlen) oder mindestens ein Google-Analytics-4-Konto
- Für Enhanced Conversions: ein Google-Ads-Konto mit konfigurierten Conversion-Kampagnen

## Installation

Drei Methoden je nach Umgebung.

### Aus der Shopware-Administration

1. Im Back-Office: **Erweiterungen → Meine Erweiterungen → Erweiterung hochladen**
2. Wählen Sie die Datei `DfGtagManager.zip`
3. Klicken Sie auf **Installieren** und dann auf **Aktivieren**
4. Cache leeren: **Einstellungen → System → Caches & Indizes → Leeren und neu aufbauen**

### Über die Kommandozeile (empfohlen in Produktion)

```
cd /pfad/zu/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
```

**Tipp.** Nach `assets:install` wird die Datei `df-gtag-manager.js` in `public/bundles/dfgtagmanager/` veröffentlicht und ist über den Twig-Asset-Helper zugänglich. Kein webpack- oder TypeScript-Build-Schritt nötig.

## Konfiguration

Öffnen Sie die Konfiguration: **Erweiterungen → Meine Erweiterungen → DataFirefly Google Tag Manager → ⋮-Menü → Konfigurieren**. Wählen Sie oben den betreffenden Sales-Channel — jeder Sales-Channel kann seine eigene unabhängige Konfiguration haben.

### Allgemeine Einstellungen

- **Plugin aktivieren**: Master-Schalter. Zum Deaktivieren jeder Injektion ohne Deinstallation.
- **Debug-Modus**: schreibt `[DfGtag]`-präfixierte Logs in die Browser-Konsole (add_to_cart, remove_from_cart, consent update…). Nur in Testumgebungen aktivieren.

### Google Tag Manager

- **GTM Container-ID**: Format `GTM-XXXXXXX`. Verfügbar in [tagmanager.google.com](https://tagmanager.google.com) oben rechts in Ihrem Container. Leer lassen, wenn Sie GTM nicht nutzen — das Plugin fällt automatisch auf den `gtag.js`-Loader zurück, sofern eine GA4 Measurement-ID gesetzt ist.
- **Server-side GTM URL** (optional): URL Ihres Server-side-Tag-Manager-Loaders (z. B. `https://gtm.ihredomain.de`, ohne abschließenden Schrägstrich). Siehe Abschnitt [Server-side GTM](#server-side-gtm) unten.

### Google Analytics 4

- **GA4 Measurement-ID**: Format `G-XXXXXXXXXX`. Verfügbar in GA4 unter **Verwaltung → Datenströme → Web**. Wird als `gtag.js`-Fallback verwendet, wenn kein GTM-Container gesetzt ist, und in den dataLayer für GTM-Tags gepusht.
- **Automatisches page_view-Event senden**: standardmäßig aktiviert. Deaktivieren, wenn Sie `page_view` lieber manuell aus GTM auslösen.

### Consent Mode v2

- **Consent Mode v2 aktivieren**: emittiert `gtag consent default` vor dem Laden von GTM, mit den sieben Consent-Mode-v2-Kategorien. Siehe [Consent Mode v2 im Detail](#consent-mode-v2).
- **Standard-Einwilligungsstatus**:
   - _Abgelehnt_ — empfohlen für EU/DSGVO. Keine Analyse- oder Werbe-Cookie wird vor der Nutzer-Zustimmung gesetzt.
   - _Erteilt_ — für Nicht-EU-Besucher oder Shops für ein professionelles, nicht DSGVO-pflichtiges Publikum reservieren.
- **url_passthrough aktivieren**: erhält die Parameter `gclid`, `_gl`, `dclid` über Seiten hinweg, auch wenn Cookies abgelehnt sind. Nützlich für Multi-Touch-Attribution.
- **ads_data_redaction bei Ablehnung aktivieren**: redakt die an Google Ads gesendeten Werbe-IDs, wenn der Nutzer ablehnt. Reduziert die Tracking-Oberfläche weiter.

### Enhanced Conversions

- **Enhanced Conversions aktivieren**: pusht ein `user_data`-Objekt mit E-Mail, Telefon, Vorname, Nachname, Straße, Stadt, Postleitzahl, alle SHA-256-gehasht serverseitig, auf den Checkout-_Confirm_- und _Finish_-Seiten. Siehe [Enhanced Conversions im Detail](#enhanced-conversions).

### Google Shopping / Merchant Center

- **item_id-Quelle**: legt fest, was das Plugin als `item_id` in jedem GA4-Item pusht. Dieser Wert **muss** dem `id`-Feld Ihres Merchant-Center-Feeds entsprechen. Drei Optionen:
   - _Product number (SKU)_ — empfohlen, das in XML/CSV-Merchant-Center-Feeds gebräuchlichste Format.
   - _Shopware UUID_ — nützlich, wenn Sie Ihren Feed direkt aus der Shopware-Datenbank generieren.
   - _EAN / GTIN_ — nützlich, wenn Ihr Feed auf internationale Barcodes ausgerichtet ist.
- **Standard-Google-Produktkategorie**: Wert, der in `google_product_category` gepusht wird, wenn weder das Produkt noch seine Kategorie eine definiert. Google-Format (z. B. `Apparel & Accessories > Clothing`).
- **Standardmarke**: als Fallback in `item_brand` verwendet, wenn das Produkt keinen Hersteller zugewiesen hat.

### Events

Jedes GA4-Event kann einzeln aktiviert werden. Deaktivieren Sie diejenigen, die Sie nicht möchten.

- **view_item** — Produktdetailseite
- **view_item_list** — Kategorieseite und Suchergebnisse
- **add_to_cart** — Klick auf den Warenkorb-Button (JavaScript-Listener)
- **remove_from_cart** — Positions-Entfernung im Warenkorb oder Offcanvas
- **view_cart** — Warenkorb-Seite
- **begin_checkout** — Checkout-Confirm-Seite
- **purchase** — Finish-Seite nach der Bestellung
- **search** — Suchergebnisseite
- **login / sign_up** — Absenden der Konto-Formulare

## Consent Mode v2 im Detail

Consent Mode v2 ist Googles offizieller Mechanismus zur Verwaltung der Nutzereinwilligung. Seit März 2024 verlangt Google Ads dies für Werbetreibende, die den Europäischen Wirtschaftsraum ansprechen — ohne verlieren Sie den Zugang zu Remarketing und Conversion-Messung.

### Ladereihenfolge

Das Plugin garantiert auf jeder Storefront-Seite folgende Reihenfolge:

1. Initialisierung von `window.dataLayer` und des `gtag()`-Stubs
2. Emission von `gtag consent default` mit den sieben Consent-Mode-v2-Kategorien und `wait_for_update: 500`
3. Emission von `url_passthrough` und `ads_data_redaction`, wenn aktiviert
4. Push der GA4-Events der Seite (view_item, view_cart…) in den dataLayer
5. Laden des GTM-Skripts (oder `gtag.js` als Fallback)

**Warum wait_for_update: 500?** Diese Anweisung sagt Google, bis zu 500 ms nach dem Seitenladen zu warten, bevor Hits im Denied-Modus emittiert werden — genug Zeit, damit Ihr Cookie-Banner die Antwort des Nutzers sammelt und das Plugin ein `gtag consent update` pusht. Ohne diese Verzögerung werden alle initialen Hits im Denied-Modus emittiert, selbst wenn der Nutzer sofort akzeptiert.

### Integration mit dem Shopware-Cookie-Banner

Das Plugin dekoriert `CookieProviderInterface` und registriert zwei virtuelle Cookies in den nativen Banner-Gruppen:

- `df-gtag-analytics` in der Gruppe **Statistik** — steuert `analytics_storage`
- `df-gtag-ads` in der Gruppe **Marketing** — steuert `ad_storage`, `ad_user_data`, `ad_personalization`

Wenn der Nutzer seine Einstellungen speichert, feuert Shopware das Event `CookieConfiguration_Update`. Der JavaScript-Controller des Plugins lauscht darauf, liest die Werte der beiden virtuellen Cookies und emittiert sofort das entsprechende `gtag consent update`.

### Kompatibilität mit Drittanbieter-Bannern

Wenn Sie Cookiebot, CookieFirst, OneTrust oder Axeptio anstelle des nativen Shopware-Banners verwenden, müssen Sie das `gtag consent update` selbst aus dem Drittanbieter-Banner mit den richtigen Kategorien emittieren. Das Plugin blockiert das nicht — es verwaltet nur das initiale `consent default` und lauscht auf das Shopware-Event.

## Enhanced Conversions im Detail

Enhanced Conversions verbessern die Messgenauigkeit von Google Ads, indem sie First-Party-Nutzerdaten (E-Mail, Telefon, Name, Adresse) bei einer Conversion SHA-256-gehasht senden. Google verknüpft diese Conversions dann mit angemeldeten Google-Nutzern, was typischerweise 10 bis 30 % zuvor verlorene Conversions zurückgewinnt, die durch Cookie-Blocker, Cross-Device-Tracking oder Browser-Wechsel verloren gingen.

### Angewandte Normalisierung

Das Plugin normalisiert jedes Feld gemäß der Google-Spezifikation vor dem Hashing:

- **E-Mail**: kleingeschrieben, getrimmt, dann SHA-256
- **Telefon**: E.164 (automatischer Ländercode aus der Rechnungs-ISO, z. B. `+49123456789`), dann SHA-256
- **Vorname, Nachname, Straße, Stadt**: kleingeschrieben, getrimmt, dann SHA-256
- **Postleitzahl**: kleingeschrieben, getrimmt; für die USA vor dem Hashing auf die ersten 5 Ziffern gekürzt
- **Land**: ISO-2-Code in Großbuchstaben, nicht gehasht

### dataLayer-Payload

Bei den Events `begin_checkout` und `purchase` pusht das Plugin:

```
{
  "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": "DE"
    }
  }
}
```

### Konfiguration in GTM

1. Erstellen oder bearbeiten Sie in Ihrem GTM-Container Ihren **Google Ads Conversion Tracking**-Tag
2. Abschnitt **Include user-provided data from your website** → **Manual configuration**
3. Erstellen Sie acht Data Layer Variables, die zeigen auf:
   - `user_data.sha256_email_address` → gemappt auf **Email (hashed)**
   - `user_data.sha256_phone_number` → gemappt auf **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. Speichern und veröffentlichen Sie den Container

**Achtung.** Google verlangt, dass die Werte bereits auf der Website-Seite gehasht sind — wenden Sie nicht die _SHA-256 Hash_-Variable von GTM auf diese Variablen an, sie kommen bereits gehasht aus dem Plugin. Ein doppeltes Hashing würde das Matching unmöglich machen.

## Google Shopping und Merchant-Center-Feed

Damit GA4 und Google Ads E-Commerce-Events korrekt mit Ihren Shopping-Produkten matchen können, muss jedes Item im dataLayer dieselbe `item_id` wie im Merchant-Center-Feed verwenden.

### In jedem Item gepushte Felder

- `item_id` — konfigurierbare Quelle (SKU / UUID / EAN)
- `item_name` — Produktname in der aktiven Sprache
- `item_brand` — Herstellername oder Standardmarke, wenn nicht gesetzt
- `item_category` bis `item_category5` — vollständiger Breadcrumb, beginnend mit der tiefsten Kategorie
- `google_product_category` — siehe unten
- `price`, `quantity`, `currency`
- `mpn` — Manufacturer Part Number, wenn am Produkt gesetzt
- `gtin` — EAN, wenn gesetzt
- `discount` — berechnet aus der Differenz zwischen Streichpreis und Verkaufspreis

### google_product_category pro Produkt

Sie können die Google-Shopping-Kategorie für ein Produkt oder eine Kategorie über ein Custom Field überschreiben:

1. Im Back-Office: **Einstellungen → System → Custom Fields → Neues Set erstellen**
2. Technischer Name: `df_google_product_category`, Typ **Text**
3. Weisen Sie dieses Set den Entitäten **Produkt** und/oder **Kategorie** zu
4. Setzen Sie an jedem Produkt oder jeder Kategorie den Google-Wert (z. B. `Sporting Goods > Athletics > Football > Football Balls`)

Das Plugin sucht den Wert in dieser Reihenfolge: Custom Field des Produkts → Custom Field seiner tiefsten Kategorie → globaler Standardwert aus der Konfiguration.

## Server-side GTM

Server-side Tagging leitet GTM-Traffic über eine von Ihnen kontrollierte Domain, was Browser-Blocker umgeht, Nutzerdaten schützt und die Widerstandsfähigkeit gegen Cookie-Policy-Änderungen verbessert.

### Voraussetzungen

- Ein konfigurierter Server-side-GTM-Container (siehe [Google-Dokumentation](https://developers.google.com/tag-platform/tag-manager/server-side))
- Eine dedizierte Domain oder Subdomain, die auf Ihren Tag-Manager-Server zeigt, z. B. `gtm.ihredomain.de`

### Aktivierung

Setzen Sie in der Plugin-Konfiguration, Abschnitt **Google Tag Manager**, **Server-side GTM URL** mit Ihrer Domain _ohne abschließenden Schrägstrich_:

```
https://gtm.ihredomain.de
```

Das GTM-Skript und der noscript-iframe zeigen automatisch auf Ihren Server anstatt auf `www.googletagmanager.com`.

## Verifizierung

### Google Tag Assistant

1. Installieren Sie die Chrome-Erweiterung **Tag Assistant Companion**
2. Öffnen Sie [tagassistant.google.com](https://tagassistant.google.com), klicken Sie auf **Add domain** und geben Sie die URL Ihres Storefronts ein
3. Navigieren Sie zu einer Produktseite, legen Sie in den Warenkorb, gehen Sie zum Checkout — jeder Schritt sollte im Assistant mit den passenden GA4-Events erscheinen

### GA4 DebugView

In GA4: **Verwaltung → DebugView**. Events erscheinen in Echtzeit, sobald der Debug-Modus im Plugin aktiv ist oder der Parameter `debug_mode=true` gesendet wird.

### Plugin-Debug-Modus

Aktivieren Sie **Debug-Modus** in der Konfiguration und öffnen Sie die Browser-Konsole. Sie sehen:

```
[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 { ... }
```

### Validierungs-Checkliste

- Auf der Home: consent default vor dem GTM-Skript emittiert (Reihenfolge im head)
- Auf einer Produktseite: `view_item` mit `item_id`, `item_brand`, `item_category`, `google_product_category`
- Bei Add-to-Cart: `add_to_cart` mit demselben Item
- Im Warenkorb: `view_cart` mit allen Items
- Auf der Confirm-Seite: `begin_checkout` mit gehashtem `user_data`
- Auf der Finish-Seite: `purchase` mit `transaction_id`, `value`, `tax`, `shipping`, `currency`, `items` und gehashtem `user_data`
- Bei Cookie-Akzeptanz: `consent update` mit granted-Kategorien

## Fehlerbehebung

### Events erscheinen nicht in GA4 DebugView

- Prüfen Sie, dass die GA4 Measurement-ID in der Konfiguration korrekt ist
- Prüfen Sie, dass der GA4-Configuration-Tag in Ihrem GTM-Container erstellt und veröffentlicht ist
- Prüfen Sie, dass der Trigger des Tags alle Seiten abdeckt (_All Pages_)
- Leeren Sie den Shopware-Cache und laden Sie die Seite mit _Hard Reload_ neu (Strg+F5)

### Enhanced Conversions matchen nicht

- Prüfen Sie, dass keine zusätzliche Transformation (SHA-256 Hash-Variable von GTM) auf die `user_data`-Variablen angewendet wird — die Werte kommen bereits gehasht heraus
- Prüfen Sie das E.164-Format des Telefons im dataLayer (mit Ländercode-Präfix beginnend mit `+`)
- Prüfen Sie, dass das `country`-Feld in ISO-2-Großbuchstaben ist (`DE`, nicht `Deutschland`)
- Warten Sie 24 bis 48 Stunden nach der Aktivierung: Google Ads benötigt diese Frist für die erste Synchronisation

### consent update wird nicht ausgelöst, wenn der Nutzer akzeptiert

- Bestätigen Sie, dass das verwendete Banner das native Shopware-Banner ist
- Öffnen Sie die Browser-Konsole im Debug-Modus und prüfen Sie, dass das Event `CookieConfiguration_Update` ausgelöst wird, wenn der Nutzer das Banner speichert
- Prüfen Sie, dass die Cookies `df-gtag-analytics` und `df-gtag-ads` im Banner erscheinen und angehakt sind

### item_id matcht nicht meinen Merchant-Center-Feed

- Öffnen Sie Ihren XML/CSV-Feed und sehen Sie das ``-Feld für ein Produkt an
- Wählen Sie in der Plugin-Konfiguration die `item_id`-Quelle, die exakt denselben Wert erzeugt (SKU, UUID oder EAN)
- Wenn Ihr Feed einen Präfix verwendet (z. B. `shopware_SW10001`), müssen Sie einen GTM-Tag erstellen, der den Wert vor dem Senden an Google Ads präfixiert

### Das Plugin lädt nicht auf einigen Seiten

- Prüfen Sie, dass der aktuelle Sales-Channel **Plugin aktivieren** in seiner spezifischen Konfiguration auf ON hat
- Einige benutzerdefinierte Seiten (Custom CMS Landing Pages) lösen die Standard-Page-Loaded-Events möglicherweise nicht aus. In diesem Fall wird der GTM-Container trotzdem über das Header-Pagelet geladen.