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

- Pagina: <https://www.datafirefly.com/nl/documentation/google-tag-manager-shopware-ga4-consent-mode-enhanced-conversions/>
- Taal: nl
- Bijgewerkt op: 2026-08-19
- Andere talen: [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), [pl](https://www.datafirefly.com/pl/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/nl/documentation/llms.txt>

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

**Tip.** Na `assets:install` wordt het bestand `df-gtag-manager.js` gepubliceerd in `public/bundles/dfgtagmanager/` en is het bereikbaar via de Twig asset helper. Er is geen webpack- of TypeScript-build nodig.

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

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

**Waarom wait_for_update: 500?** Die instructie zegt Google tot 500 ms na het laden van de pagina te wachten voordat het hits in geweigerde modus uitzendt, zodat uw cookiebanner tijd heeft om het antwoord van de gebruiker op te halen en de plugin een `gtag consent update` kan pushen. Zonder die vertraging worden alle eerste hits in geweigerde modus verstuurd, ook als de gebruiker meteen accepteert.

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

**Let op.** Google eist dat de waarden al aan de kant van de site gehasht zijn; pas de GTM-variabele _SHA-256 Hash_ dus niet toe op deze variabelen, want ze verlaten de plugin al gehasht. Dubbel hashen maakt matching onmogelijk.

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