DfGtagManager — Documentazione completa

DfGtagManager è un plugin Shopware 6.7 che inietta un container Google Tag Manager, emette gli eventi GA4 e-commerce completi, gestisce Consent Mode v2 con il banner cookie Shopware nativo, invia le Enhanced Conversions hashate SHA-256 e allinea il data layer al tuo feed Google Merchant Center. Questa documentazione copre installazione, configurazione completa e verifica.

Prerequisiti

• Shopware 6.7.0 o più recente
• PHP 8.2 minimo
• Accesso SSH o amministrazione Shopware per installare lo ZIP
• Un account Google Tag Manager (consigliato) o almeno un account Google Analytics 4
• Per le Enhanced Conversions: un account Google Ads con campagne di conversione configurate

Installazione

Tre metodi disponibili a seconda del tuo ambiente.

Dall’amministrazione Shopware

1. Nel back-office: Estensioni → Le mie estensioni → Carica estensione
2. Seleziona il file DfGtagManager.zip
3. Clicca su Installa poi su Attiva
4. Svuota la cache: Impostazioni → Sistema → Cache e indici → Svuota e ricostruisci

Dalla riga di comando (consigliato in produzione)

cd /percorso/verso/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

Configurazione

Apri la configurazione: Estensioni → Le mie estensioni → DataFirefly Google Tag Manager → menu ⋮ → Configura. Seleziona il sales-channel interessato in alto — ogni sales-channel può avere la propria configurazione indipendente.

Impostazioni generali

• Attiva plugin: interruttore principale. Disattiva per interrompere ogni iniezione senza disinstallare.
• Modalità debug: mostra log prefissati [DfGtag] nella console del browser (add_to_cart, remove_from_cart, consent update…). Da attivare solo in ambienti di test.

Google Tag Manager

• GTM Container ID: formato GTM-XXXXXXX. Reperibile in tagmanager.google.com in alto a destra del tuo container. Lascialo vuoto se non usi GTM — il plugin cadrà automaticamente sul loader gtag.js se c’è un Measurement ID GA4 configurato.
• Server-side GTM URL (opzionale): URL del tuo loader Tag Manager server-side (per esempio https://gtm.tuodominio.it, senza slash finale). Vedi la sezione Server-side GTM più sotto.

Google Analytics 4

• GA4 Measurement ID: formato G-XXXXXXXXXX. Reperibile in GA4 in Amministrazione → Flussi di dati → Web. Utilizzato come fallback gtag.js quando nessun container GTM è configurato, e inviato al dataLayer per i tag GTM.
• Invia evento page_view automatico: attivato di default. Disattiva se preferisci attivare page_view manualmente da GTM.

Consent Mode v2

• Attiva Consent Mode v2: emette gtag consent default prima del caricamento di GTM, con le sette categorie del Consent Mode v2. Vedi Consent Mode v2 in dettaglio.
• Stato di consenso predefinito:
  • Rifiutato — consigliato per UE/GDPR. Nessun cookie analitico o pubblicitario viene depositato prima dell’accettazione dell’utente.
  • Concesso — da riservare a visitatori fuori UE o negozi per un pubblico professionale non soggetto al GDPR.
• Attiva url_passthrough: conserva i parametri gclid, _gl, dclid tra le pagine anche quando i cookie sono rifiutati. Utile per l’attribuzione multi-touch.
• Attiva ads_data_redaction se rifiutato: redige gli identificatori pubblicitari inviati a Google Ads quando l’utente rifiuta. Riduce ulteriormente la superficie di tracking.

Enhanced Conversions

• Attiva Enhanced Conversions: invia un oggetto user_data con email, telefono, nome, cognome, via, città, codice postale, tutti hashati SHA-256 lato server, sulle pagine confirm e finish del checkout. Vedi Enhanced Conversions in dettaglio.

Google Shopping / Merchant Center

• Sorgente item_id: determina ciò che il plugin invia come item_id in ogni item GA4. Questo valore deve corrispondere al campo id del tuo feed Merchant Center. Tre opzioni:
  • Product number (SKU) — consigliato, il formato più comune nei feed XML/CSV Merchant Center.
  • Shopware UUID — utile se generi il tuo feed direttamente dal database Shopware.
  • EAN / GTIN — utile se il tuo feed è allineato ai codici a barre internazionali.
• Categoria Google predefinita: valore inviato a google_product_category quando né il prodotto né la sua categoria ne definiscono una. Formato Google (per esempio Apparel & Accessories > Clothing).
• Marca predefinita: utilizzata come fallback in item_brand quando il prodotto non ha un produttore assegnato.

Eventi

Ogni evento GA4 è attivabile individualmente. Deseleziona quelli che non vuoi.

• view_item — pagina prodotto
• view_item_list — pagina categoria e risultati di ricerca
• add_to_cart — clic sul pulsante di aggiunta al carrello (listener JavaScript)
• remove_from_cart — rimozione di una riga dal carrello o offcanvas
• view_cart — pagina carrello
• begin_checkout — pagina di conferma del checkout
• purchase — pagina finish dopo l’ordine
• search — pagina risultati di ricerca
• login / sign_up — invio dei form account

Consent Mode v2 in dettaglio

Il Consent Mode v2 è il meccanismo ufficiale di Google per gestire il consenso utente. Dal marzo 2024, Google Ads lo richiede per gli inserzionisti che si rivolgono allo Spazio Economico Europeo — senza di esso, perdi l’accesso al remarketing e alla misurazione delle conversioni.

Ordine di caricamento

Il plugin garantisce il seguente ordine su ogni pagina del storefront:

1. Inizializzazione di window.dataLayer e dello stub gtag()
2. Emissione di gtag consent default con le sette categorie Consent Mode v2 e wait_for_update: 500
3. Emissione di url_passthrough e ads_data_redaction se attivi
4. Push degli eventi GA4 della pagina (view_item, view_cart…) nel dataLayer
5. Caricamento dello script GTM (o gtag.js come fallback)

Integrazione al banner cookie Shopware

Il plugin decora CookieProviderInterface e registra due cookie virtuali nei gruppi del banner nativo:

• df-gtag-analytics nel gruppo Statistiche — controlla analytics_storage
• df-gtag-ads nel gruppo Marketing — controlla ad_storage, ad_user_data, ad_personalization

Quando l’utente convalida le sue preferenze, Shopware emette l’evento CookieConfiguration_Update. Il controller JavaScript del plugin lo ascolta, legge il valore dei due cookie virtuali ed emette immediatamente il gtag consent update corrispondente.

Compatibilità con banner di terze parti

Se usi Cookiebot, CookieFirst, OneTrust o Axeptio al posto del banner nativo Shopware, devi emettere tu stesso il gtag consent update dal banner di terze parti con le categorie corrette. Il plugin non te lo impedisce — gestisce solo il consent default iniziale e l’ascolto dell’evento Shopware.

Enhanced Conversions in dettaglio

Le Enhanced Conversions migliorano la precisione della misurazione Google Ads inviando dati utente first-party (email, telefono, nome, indirizzo) hashati SHA-256 al momento di una conversione. Google può poi riconnettere queste conversioni agli utenti Google connessi, il che tipicamente recupera dal 10 al 30 % di conversioni prima perse a causa di blocchi cookie, tracking cross-device o cambi di browser.

Normalizzazione applicata

Il plugin normalizza ogni campo secondo la specifica Google prima dell’hashing:

• Email: lowercased, trimmed e poi SHA-256
• Telefono: E.164 (prefisso paese automatico dall’ISO dell’indirizzo di fatturazione, esempio +39123456789), poi SHA-256
• Nome, cognome, via, città: lowercased, trimmed e poi SHA-256
• Codice postale: lowercased, trimmed; per gli USA, troncato ai primi 5 caratteri prima dell’hashing
• Paese: codice ISO-2 in maiuscolo, non hashato

Payload dataLayer

Sugli eventi begin_checkout e purchase, il plugin invia:

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

Configurazione in GTM

1. Nel tuo container GTM, crea o modifica il tuo tag Google Ads Conversion Tracking
2. Sezione Include user-provided data from your website → Manual configuration
3. Crea otto Data Layer Variables che puntano a:
   • user_data.sha256_email_address → mappato a Email (hashed)
   • user_data.sha256_phone_number → mappato a 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. Salva e pubblica il container

Google Shopping e feed Merchant Center

Affinché GA4 e Google Ads possano abbinare correttamente gli eventi e-commerce ai tuoi prodotti Shopping, ogni item nel dataLayer deve utilizzare lo stesso item_id di quello del tuo feed Merchant Center.

Campi inviati in ogni item

• item_id — sorgente configurabile (SKU / UUID / EAN)
• item_name — nome del prodotto nella lingua attiva
• item_brand — nome del produttore, o marca predefinita se non impostato
• item_category a item_category5 — breadcrumb completo a partire dalla categoria più profonda
• google_product_category — vedi sotto
• price, quantity, currency
• mpn — Manufacturer Part Number quando impostato sul prodotto
• gtin — EAN quando impostato
• discount — calcolato dalla differenza tra prezzo barrato e prezzo di vendita

google_product_category per prodotto

Puoi sovrascrivere la categoria Google Shopping per un prodotto o una categoria tramite un custom field:

1. Nel back-office: Impostazioni → Sistema → Custom fields → Crea nuovo set
2. Nome tecnico: df_google_product_category, tipo Testo
3. Assegna questo set alle entità Prodotto e/o Categoria
4. Su ogni prodotto o categoria, imposta il valore Google (per esempio Sporting Goods > Athletics > Football > Football Balls)

Il plugin cerca il valore in questo ordine: custom field del prodotto → custom field della sua categoria più profonda → valore globale predefinito dalla configurazione.

Server-side GTM

Il server-side tagging permette di instradare il traffico GTM tramite un dominio che controlli, il che aggira i blocchi lato browser, protegge i dati utente e migliora la resilienza ai cambiamenti delle policy sui cookie.

Prerequisiti

• Un container server-side GTM configurato (vedi documentazione Google)
• Un dominio o sottodominio dedicato che punta al tuo server Tag Manager, per esempio gtm.tuodominio.it

Attivazione

Nella configurazione del plugin, sezione Google Tag Manager, indica Server-side GTM URL con il tuo dominio senza slash finale:

https://gtm.tuodominio.it

Lo script GTM e l’iframe noscript punteranno automaticamente al tuo server invece che a www.googletagmanager.com.

Verifica

Google Tag Assistant

1. Installa l’estensione Chrome Tag Assistant Companion
2. Apri tagassistant.google.com, clicca su Add domain e inserisci l’URL del tuo storefront
3. Naviga su una pagina prodotto, aggiungi al carrello, vai al checkout — ogni passo deve apparire nell’assistente con gli eventi GA4 corrispondenti

GA4 DebugView

In GA4: Amministrazione → DebugView. Gli eventi appaiono in tempo reale non appena la modalità Debug è attiva nel plugin o il parametro debug_mode=true viene inviato.

Modalità debug del plugin

Attiva Modalità debug nella configurazione poi apri la console del browser. Vedrai:

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

Checklist di validazione

• Sulla home: consent default emesso prima dello script GTM (ordine dei tag nell’head)
• Su una pagina prodotto: view_item con item_id, item_brand, item_category, google_product_category
• All’aggiunta al carrello: add_to_cart con lo stesso item
• Sul carrello: view_cart con tutti gli item
• Sulla pagina confirm: begin_checkout con user_data hashato
• Sulla pagina finish: purchase con transaction_id, value, tax, shipping, currency, items e user_data hashato
• All’accettazione cookie: consent update con le categorie granted

Risoluzione dei problemi

Gli eventi non appaiono in GA4 DebugView

• Verifica che il Measurement ID GA4 sia corretto nella configurazione
• Verifica che il tag GA4 Configuration sia creato e pubblicato nel tuo container GTM
• Verifica che il trigger del tag copra tutte le pagine (All Pages)
• Svuota la cache di Shopware e ricarica la pagina in hard reload (Ctrl+F5)

Le Enhanced Conversions non abbinano

• Verifica che nessuna trasformazione aggiuntiva (variabile SHA-256 Hash di GTM) sia applicata alle variabili user_data — i valori escono già hashati
• Verifica il formato E.164 del telefono nel dataLayer (con prefisso paese che inizia con +)
• Verifica che il campo country sia in ISO-2 maiuscolo (IT, non Italia)
• Attendi 24-48 ore dopo l’attivazione: Google Ads ha bisogno di questo lasso di tempo per la prima sincronizzazione

consent update non emesso quando l’utente accetta

• Conferma che il banner in uso sia quello nativo di Shopware
• Apri la console del browser in modalità debug e verifica che l’evento CookieConfiguration_Update venga emesso quando l’utente convalida il banner
• Verifica che i cookie df-gtag-analytics e df-gtag-ads appaiano nel banner e siano spuntati

item_id non corrisponde al mio feed Merchant Center

• Apri il tuo feed XML/CSV e guarda il campo <g:id> per un prodotto
• Nella configurazione del plugin, scegli la sorgente item_id che produce esattamente lo stesso valore (SKU, UUID o EAN)
• Se il tuo feed usa un prefisso (per esempio shopware_SW10001), dovrai creare un tag GTM che prefissi il valore prima dell’invio a Google Ads

Il plugin non si carica su alcune pagine

• Verifica che il sales-channel in uso abbia Attiva plugin su ON nella sua configurazione specifica
• Alcune pagine personalizzate (landing page CMS custom) possono non attivare i Page Loaded Events standard. In quel caso, il container GTM viene comunque caricato tramite l’header pagelet.