# 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… - Pagina: - Lingua: it - Aggiornato il: 2026-07-01 - Altre lingue: [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), [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) - Indice: 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 ``` **Suggerimento.** Dopo `assets:install`, il file `df-gtag-manager.js` viene pubblicato in `public/bundles/dfgtagmanager/` e diventa accessibile via l'asset helper di Twig. Nessun passo di build webpack o TypeScript necessario. ## 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](https://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](#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](#consent-mode-v2). - **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](#enhanced-conversions). ### 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) **Perché wait_for_update: 500?** Questa istruzione dice a Google di attendere fino a 500 ms dopo il caricamento della pagina prima di emettere gli hit in modalità denied — abbastanza tempo perché il tuo banner cookie raccolga la risposta dell'utente e il plugin invii un `gtag consent update`. Senza questo ritardo, tutti gli hit iniziali vengono emessi in modalità denied anche se l'utente accetta immediatamente. ### 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 **Attenzione.** Google richiede che i valori siano già hashati lato sito — non applicare la variabile _SHA-256 Hash_ di GTM a queste variabili, escono dal plugin già hashate. Un doppio hash renderebbe impossibile il matching. ## 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](https://developers.google.com/tag-platform/tag-manager/server-side)) - 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](https://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 `` 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.