DfGtagManager: volledige documentatie

DfGtagManager is een Shopware 6.7-plugin die een Google Tag Manager-container invoegt, de volledige GA4 e-commerce-events uitzendt, Consent Mode v2 afhandelt met de native cookiebanner van Shopware, Enhanced Conversions met SHA-256 gehasht doorstuurt en de data layer afstemt op uw Google Merchant Center-feed. Deze documentatie behandelt de installatie, de volledige configuratie en de verificatie.

Vereisten

• Shopware 6.7.0 of nieuwer
• PHP 8.2 minimaal
• SSH-toegang of de Shopware-administration om de ZIP te installeren
• Een Google Tag Manager-account (aanbevolen) of ten minste een Google Analytics 4-account
• Voor de Enhanced Conversions: een Google Ads-account met geconfigureerde conversiecampagnes

Installatie

Er zijn drie methodes, afhankelijk van uw omgeving.

Vanuit de Shopware-administration

1. In de backoffice: Extensies → Mijn extensies → Extensie uploaden
2. Selecteer het bestand DfGtagManager.zip
3. Klik op Installeren en daarna op Activeren
4. Leeg de cache: Instellingen → Systeem → Cache en index → Legen en opnieuw genereren

Vanaf de commandoregel (aanbevolen in productie)

cd /pad/naar/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

Configuratie

Open de configuratie: Extensies → Mijn extensies → DataFirefly Google Tag Manager → menu ⋮ → Configureren. Selecteer bovenaan het scherm het betreffende sales channel, want elk sales channel kan zijn eigen onafhankelijke configuratie hebben.

Algemene instellingen

• Plugin activeren: hoofdschakelaar. Schakel uit om alle invoeging te stoppen zonder te verwijderen.
• Debugmodus: toont logs met het voorvoegsel [DfGtag] in de browserconsole (add_to_cart, remove_from_cart, consent update en meer). Activeer dit alleen in een testomgeving.

Google Tag Manager

• GTM Container ID: formaat GTM-XXXXXXX. Te vinden op tagmanager.google.com, rechtsboven in uw container. Laat leeg als u GTM niet gebruikt; de plugin schakelt dan automatisch over op de loader gtag.js zodra er een GA4 Measurement ID is ingevuld.
• Server-side GTM URL (optioneel): de URL van uw server-side Tag Manager-loader (bijvoorbeeld https://gtm.uwdomein.com, zonder afsluitende schuine streep). Zie het hoofdstuk Server-side GTM hieronder.

Google Analytics 4

• GA4 Measurement ID: formaat G-XXXXXXXXXX. Te vinden in GA4 onder Beheer → Gegevensstromen → Web. Wordt gebruikt als terugval via gtag.js wanneer er geen GTM-container is geconfigureerd, en wordt in de dataLayer gezet voor de GTM-tags.
• Het event page_view automatisch versturen: standaard ingeschakeld. Schakel dit uit als u page_view liever handmatig vanuit GTM afvuurt.

Consent Mode v2

• Consent Mode v2 activeren: zendt gtag consent default uit vóór het laden van GTM, met de zeven categorieën van Consent Mode v2. Zie Consent Mode v2 in detail.
• Standaard toestemmingsstatus:
  • Geweigerd: aanbevolen voor de EU en de AVG. Er wordt geen enkele analytische of advertentiecookie geplaatst voordat de gebruiker accepteert.
  • Toegestaan: alleen voor bezoekers buiten de EU, of voor shops die uitsluitend gericht zijn op een zakelijk publiek dat niet onder de AVG valt.
• url_passthrough activeren: behoudt de parameters gclid, _gl en dclid tussen pagina’s, ook wanneer cookies worden geweigerd. Nuttig voor multitouch-attributie.
• ads_data_redaction activeren bij weigering: anonimiseert de advertentie-identificaties die naar Google Ads worden gestuurd wanneer de gebruiker weigert. Verkleint het trackingoppervlak verder.

Enhanced Conversions

• Enhanced Conversions activeren: stuurt een object user_data mee met e-mail, telefoon, voornaam, achternaam, straat, plaats en postcode, alle aan serverzijde met SHA-256 gehasht, op de pagina’s confirm en finish van het besteltraject. Zie Enhanced Conversions in detail.

Google Shopping en Merchant Center

• Bron van item_id: bepaalt wat de plugin als item_id in elk GA4-item meestuurt. Deze waarde moet overeenkomen met het veld id van uw Merchant Center-feed. Drie opties:
  • Productnummer (SKU): aanbevolen, het gangbaarste formaat in XML- en CSV-feeds voor Merchant Center.
  • Shopware UUID: nuttig als u uw feed rechtstreeks uit de Shopware-database genereert.
  • EAN / GTIN: nuttig als uw feed op internationale barcodes is afgestemd.
• Standaard Google-categorie: de waarde die in google_product_category wordt gezet wanneer noch het product noch de categorie er een definieert. Google-formaat (bijvoorbeeld Apparel & Accessories > Clothing).
• Standaardmerk: gebruikt als terugval in item_brand wanneer het product geen fabrikant heeft.

Events

Elk GA4-event is afzonderlijk te activeren. Vink de events uit die u niet wilt.

• view_item: productpagina
• view_item_list: categoriepagina en zoekresultaten
• add_to_cart: klik op de knop toevoegen aan winkelwagen (JavaScript-listener)
• remove_from_cart: verwijderen van een winkelwagenregel of van een regel in de offcanvas
• view_cart: winkelwagenpagina
• begin_checkout: bevestigingspagina van het besteltraject
• purchase: finish-pagina na de bestelling
• search: pagina met zoekresultaten
• login / sign_up: verzenden van de accountformulieren

Consent Mode v2 in detail

Consent Mode v2 is het officiële mechanisme van Google om toestemming van gebruikers af te handelen. Sinds maart 2024 eist Google Ads het van adverteerders die zich op de Europese Economische Ruimte richten; zonder dat mechanisme verliest u toegang tot remarketing en tot conversiemeting.

Laadvolgorde

De plugin garandeert op elke pagina van de storefront de volgende volgorde:

1. Initialisatie van window.dataLayer en van de stub gtag()
2. Uitzenden van gtag consent default met de zeven categorieën van Consent Mode v2 en wait_for_update: 500
3. Uitzenden van url_passthrough en ads_data_redaction indien geactiveerd
4. Pushen van de GA4-events van de pagina (view_item, view_cart en andere) in de dataLayer
5. Laden van het GTM-script (of van gtag.js als terugval)

Integratie met de cookiebanner van Shopware

De plugin decoreert CookieProviderInterface en registreert twee virtuele cookies in de groepen van de native banner:

• df-gtag-analytics in de groep Statistieken: bestuurt analytics_storage
• df-gtag-ads in de groep Marketing: bestuurt ad_storage, ad_user_data en ad_personalization

Wanneer de gebruiker zijn voorkeuren bevestigt, zendt Shopware het event CookieConfiguration_Update uit. De JavaScript-controller van de plugin luistert naar dat event, leest de waarde van de twee virtuele cookies en zendt onmiddellijk de bijbehorende gtag consent update uit.

Compatibiliteit met een banner van derden

Gebruikt u Cookiebot, CookieFirst, OneTrust of Axeptio in plaats van de native banner van Shopware, dan moet u zelf de gtag consent update met de juiste categorieën vanuit die banner uitzenden. De plugin staat dat niet in de weg; hij verzorgt alleen de initiële consent default en het luisteren naar het Shopware-event.

Enhanced Conversions in detail

Enhanced Conversions verbeteren de nauwkeurigheid van de meting in Google Ads door bij een conversie first-party gebruikersgegevens (e-mail, telefoon, naam, adres) met SHA-256 gehasht mee te sturen. Google koppelt die conversies daarna aan ingelogde Google-gebruikers, wat doorgaans 10 tot 30 % van de conversies terugwint die eerder verloren gingen door cookieblokkers, gebruik van meerdere apparaten of het wisselen van browser.

Toegepaste normalisatie

De plugin normaliseert elk veld volgens de specificatie van Google vóór het hashen:

• E-mail: kleine letters, spaties verwijderd, daarna SHA-256
• Telefoon: E.164 (automatisch landvoorvoegsel op basis van de ISO-code van het factuuradres, bijvoorbeeld +31612345678), daarna SHA-256
• Voornaam, achternaam, straat, plaats: kleine letters, spaties verwijderd, daarna SHA-256
• Postcode: kleine letters, spaties verwijderd; voor de VS afgekapt tot de eerste 5 cijfers vóór het hashen
• Land: ISO-2-code in hoofdletters, niet gehasht

dataLayer-payload

Bij de events begin_checkout en purchase stuurt de plugin het volgende mee:

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

Configuratie in GTM

1. Maak of bewerk in uw GTM-container uw tag Google Ads Conversion Tracking
2. Sectie Include user-provided data from your website → Manual configuration
3. Maak acht Data Layer Variables die verwijzen naar:
   • user_data.sha256_email_address → gekoppeld aan Email (hashed)
   • user_data.sha256_phone_number → gekoppeld aan 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. Sla op en publiceer de container

Google Shopping en Merchant Center-feed

Om GA4 en Google Ads de e-commerce-events aan uw Shopping-producten te laten koppelen, moet elk item in de dataLayer dezelfde item_id gebruiken als de Merchant Center-feed.

Velden in elk item

• item_id: instelbare bron (SKU / UUID / EAN)
• item_name: naam van het product in de actieve taal
• item_brand: naam van de fabrikant, of het standaardmerk indien niet ingevuld
• item_category tot item_category5: volledig kruimelpad, vertrekkend van de diepste categorie
• google_product_category: zie hieronder
• price, quantity, currency
• mpn: Manufacturer Part Number indien op het product ingevuld
• gtin: EAN indien ingevuld
• discount: berekend uit het verschil tussen de doorgestreepte prijs en de verkoopprijs

google_product_category per product

U kunt de Google Shopping-categorie voor een product of een categorie overschrijven via een aangepast veld:

1. In de backoffice: Instellingen → Systeem → Aangepaste velden → Nieuwe set aanmaken
2. Technische naam: df_google_product_category, type Tekst
3. Wijs die set toe aan de entiteiten Product en/of Categorie
4. Vul op elk product of elke categorie de Google-waarde in (bijvoorbeeld Sporting Goods > Athletics > Football > Football Balls)

De plugin zoekt de waarde in deze volgorde: aangepast veld van het product → aangepast veld van de diepste categorie → globale standaardwaarde uit de configuratie.

Server-side GTM

Met server-side tagging routeert u het GTM-verkeer via een domein dat u zelf beheert, wat browserblokkers omzeilt, gebruikersgegevens beschermt en de weerbaarheid tegen veranderingen in het cookiebeleid vergroot.

Vereisten

• Een geconfigureerde server-side GTM-container (zie de documentatie van Google)
• Een eigen domein of subdomein dat naar uw Tag Manager-server verwijst, bijvoorbeeld gtm.uwdomein.com

Activering

Vul in de configuratie van de plugin, sectie Google Tag Manager, het veld Server-side GTM URL in met uw domein zonder afsluitende schuine streep:

https://gtm.uwdomein.com

Het GTM-script en de noscript-iframe verwijzen dan automatisch naar uw server in plaats van naar www.googletagmanager.com.

Verificatie

Google Tag Assistant

1. Installeer de Chrome-extensie Tag Assistant Companion
2. Open tagassistant.google.com, klik op Add domain en voer de URL van uw storefront in
3. Navigeer naar een productpagina, voeg toe aan de winkelwagen en ga naar de checkout; elke stap moet met de bijbehorende GA4-events in de assistent verschijnen

GA4 DebugView

In GA4: Beheer → DebugView. De events verschijnen daar in realtime zodra de debugmodus in de plugin actief is of zodra de parameter debug_mode=true wordt meegestuurd.

Debugmodus van de plugin

Activeer Debugmodus in de configuratie en open daarna de browserconsole. U ziet dan:

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

Validatiechecklist

• Op de homepage: consent default uitgezonden vóór het GTM-script (volgorde van de tags in de head)
• Op een productpagina: view_item met item_id, item_brand, item_category en google_product_category
• Bij toevoegen aan de winkelwagen: add_to_cart met hetzelfde item
• Op de winkelwagen: view_cart met alle items
• Op de confirm-pagina: begin_checkout met gehashte user_data
• Op de finish-pagina: purchase met transaction_id, value, tax, shipping, currency, items en gehashte user_data
• Bij het accepteren van cookies: consent update met de toegestane categorieën

Probleemoplossing

De events verschijnen niet in de GA4 DebugView

• Controleer of het GA4 Measurement ID in de configuratie klopt
• Controleer of de tag GA4 Configuration daadwerkelijk is aangemaakt en gepubliceerd in uw GTM-container
• Controleer of de trigger van de tag alle pagina’s dekt (All Pages)
• Leeg de Shopware-cache en herlaad de pagina met een hard reload (Ctrl+F5)

De Enhanced Conversions komen niet overeen

• Controleer of er geen extra transformatie (de GTM-variabele SHA-256 Hash) op de variabelen user_data wordt toegepast, want de waarden zijn al gehasht
• Controleer het E.164-formaat van het telefoonnummer in de dataLayer (met landvoorvoegsel dat met + begint)
• Controleer of het veld country in ISO-2 met hoofdletters staat (NL, niet Nederland)
• Wacht 24 tot 48 uur na de activering: Google Ads heeft die tijd nodig voor de eerste synchronisatie

Consent update wordt niet uitgezonden wanneer de gebruiker accepteert

• Bevestig dat de gebruikte banner daadwerkelijk de native banner van Shopware is
• Open de browserconsole in debugmodus en controleer of het event CookieConfiguration_Update wordt uitgezonden wanneer de gebruiker de banner bevestigt
• Controleer of de cookies df-gtag-analytics en df-gtag-ads in de banner verschijnen en aangevinkt zijn

item_id komt niet overeen met mijn Merchant Center-feed

• Open uw XML- of CSV-feed en bekijk het veld <g:id> voor een product
• Kies in de configuratie van de plugin de bron voor item_id die exact dezelfde waarde oplevert (SKU, UUID of EAN)
• Gebruikt uw feed een voorvoegsel (bijvoorbeeld shopware_SW10001), maak dan een GTM-tag die de waarde van dat voorvoegsel voorziet voordat ze naar Google Ads gaat

De plugin laadt niet op bepaalde pagina’s

• Controleer of het huidige sales channel Plugin activeren op AAN heeft staan in zijn eigen configuratie
• Sommige aangepaste pagina’s (eigen CMS-landingspagina’s) vuren de standaard Page Loaded Events mogelijk niet af. In dat geval wordt de GTM-container toch geladen via de header-pagelet.