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

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 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 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.
• 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.

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)

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

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)
• 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, 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 <g:id>-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.