DfGtagManager — Documentation complète

DfGtagManager est un plugin Shopware 6.7 qui injecte un conteneur Google Tag Manager, émet les évènements GA4 e-commerce complets, gère Consent Mode v2 avec le bandeau cookies Shopware natif, pousse les Enhanced Conversions hashées SHA-256, et aligne le data layer sur votre flux Google Merchant Center. Cette documentation couvre l’installation, la configuration complète et la vérification.

Prérequis

• Shopware 6.7.0 ou plus récent
• PHP 8.2 minimum
• Accès SSH ou administration Shopware pour l’installation du ZIP
• Un compte Google Tag Manager (recommandé) ou au minimum un compte Google Analytics 4
• Pour les Enhanced Conversions : un compte Google Ads avec des campagnes de conversion configurées

Installation

Trois méthodes possibles selon votre environnement.

Depuis l’administration Shopware

1. Dans le back-office : Extensions → Mes extensions → Charger l’extension
2. Sélectionnez le fichier DfGtagManager.zip
3. Cliquez sur Installer puis sur Activer
4. Videz le cache : Paramètres → Système → Cache et index → Vider et regénérer

Depuis la ligne de commande (recommandé en production)

cd /chemin/vers/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

Configuration

Ouvrez la configuration : Extensions → Mes extensions → DataFirefly Google Tag Manager → menu ⋮ → Configurer. Sélectionnez le sales-channel concerné en haut de l’écran — chaque sales-channel peut avoir sa propre configuration indépendante.

Réglages généraux

• Activer le plugin : bascule maître. Désactivez pour couper toute injection sans désinstaller.
• Mode debug : affiche des logs préfixés [DfGtag] dans la console navigateur (add_to_cart, remove_from_cart, consent update…). À activer uniquement en environnement de test.

Google Tag Manager

• GTM Container ID : format GTM-XXXXXXX. Récupérable dans tagmanager.google.com en haut à droite de votre conteneur. Laissez vide si vous n’utilisez pas GTM — le plugin basculera automatiquement sur le loader gtag.js si un Measurement ID GA4 est renseigné.
• Server-side GTM URL (optionnel) : URL de votre loader Tag Manager server-side (par exemple https://gtm.votredomaine.com, sans slash final). Voir la section Server-side GTM plus bas.

Google Analytics 4

• GA4 Measurement ID : format G-XXXXXXXXXX. Récupérable dans GA4 sous Admin → Flux de données → Web. Utilisé comme fallback gtag.js si aucun conteneur GTM n’est configuré, et poussé dans le dataLayer pour les tags GTM.
• Envoyer l’évènement page_view automatique : activé par défaut. Désactivez si vous préférez déclencher page_view manuellement depuis GTM.

Consent Mode v2

• Activer Consent Mode v2 : émet gtag consent default avant le chargement de GTM, avec les sept catégories du Consent Mode v2. Voir Consent Mode v2 en détail.
• État de consentement par défaut :
  • Refusé — recommandé pour l’UE/RGPD. Aucun cookie analytique ou publicitaire n’est déposé avant l’acceptation utilisateur.
  • Accordé — à réserver aux visiteurs hors UE, ou aux boutiques réservées à un public professionnel non soumis au RGPD.
• Activer url_passthrough : conserve les paramètres gclid, _gl, dclid entre les pages même quand les cookies sont refusés. Utile pour l’attribution multi-touch.
• Activer ads_data_redaction si refusé : redact les identifiants publicitaires envoyés à Google Ads quand l’utilisateur refuse. Réduit encore la surface de tracking.

Enhanced Conversions

• Activer Enhanced Conversions : pousse un objet user_data avec email, téléphone, prénom, nom, rue, ville, code postal, tous hashés SHA-256 côté serveur, sur les pages confirm et finish du tunnel. Voir Enhanced Conversions en détail.

Google Shopping / Merchant Center

• Source item_id : détermine ce que le plugin pousse comme item_id dans chaque item GA4. Cette valeur doit correspondre au champ id de votre flux Merchant Center. Trois options :
  • Product number (SKU) — recommandé, le format le plus courant dans les flux XML/CSV Merchant Center.
  • Shopware UUID — utile si vous générez votre flux directement depuis la base Shopware.
  • EAN / GTIN — utile si votre flux est aligné sur les codes-barres internationaux.
• Catégorie Google par défaut : valeur poussée dans google_product_category quand ni le produit ni sa catégorie n’en définit une. Format Google (par exemple Apparel & Accessories > Clothing).
• Marque par défaut : utilisée en fallback dans item_brand quand le produit n’a pas de fabricant assigné.

Évènements

Chaque évènement GA4 est activable individuellement. Décochez ceux dont vous ne voulez pas.

• view_item — fiche produit
• view_item_list — page catégorie et résultats de recherche
• add_to_cart — clic sur le bouton d’ajout au panier (listener JavaScript)
• remove_from_cart — suppression d’une ligne panier ou offcanvas
• view_cart — page panier
• begin_checkout — page de confirmation du tunnel
• purchase — page finish après commande
• search — page de résultats de recherche
• login / sign_up — soumission des formulaires de compte

Consent Mode v2 en détail

Le Consent Mode v2 est le mécanisme officiel de Google pour gérer le consentement utilisateur. Depuis mars 2024, Google Ads l’exige pour les annonceurs ciblant l’Espace économique européen — sans lui, vous perdez l’accès au remarketing et à la mesure des conversions.

Ordre de chargement

Le plugin garantit l’ordre suivant sur chaque page du storefront :

1. Initialisation de window.dataLayer et du stub gtag()
2. Émission de gtag consent default avec les sept catégories Consent Mode v2 et wait_for_update: 500
3. Émission de url_passthrough et ads_data_redaction si activés
4. Push des évènements GA4 de la page (view_item, view_cart…) dans le dataLayer
5. Chargement du script GTM (ou gtag.js en fallback)

Intégration au bandeau cookies Shopware

Le plugin décore CookieProviderInterface et enregistre deux cookies virtuels dans les groupes du bandeau natif :

• df-gtag-analytics dans le groupe Statistiques — contrôle analytics_storage
• df-gtag-ads dans le groupe Marketing — contrôle ad_storage, ad_user_data, ad_personalization

Quand l’utilisateur valide ses préférences, Shopware émet l’évènement CookieConfiguration_Update. Le contrôleur JavaScript du plugin écoute cet évènement, lit la valeur des deux cookies virtuels, et émet immédiatement le gtag consent update correspondant.

Compatibilité avec un bandeau tiers

Si vous utilisez Cookiebot, CookieFirst, OneTrust ou Axeptio à la place du bandeau natif Shopware, vous devez émettre vous-même le gtag consent update depuis le bandeau tiers avec les catégories correctes. Le plugin ne vous en empêche pas — il gère seulement le consent default initial et l’écoute de l’évènement Shopware.

Enhanced Conversions en détail

Les Enhanced Conversions améliorent la précision de la mesure Google Ads en envoyant des données utilisateur first-party (email, téléphone, nom, adresse) hashées SHA-256 lors d’une conversion. Google reconnecte ensuite ces conversions aux utilisateurs Google connectés, ce qui restaure typiquement 10 à 30 % de conversions auparavant perdues à cause des bloqueurs cookies, du cross-device ou des changements de navigateur.

Normalisation appliquée

Le plugin normalise chaque champ conformément à la spécification Google avant hashage :

• Email : lowercased, trimmed, puis SHA-256
• Téléphone : E.164 (préfixe pays automatique depuis l’ISO de l’adresse de facturation, exemple +33612345678), puis SHA-256
• Prénom, nom, rue, ville : lowercased, trimmed, puis SHA-256
• Code postal : lowercased, trimmed ; pour les US, tronqué aux 5 premiers chiffres avant hashage
• Pays : code ISO-2 en majuscules, non hashé

Payload dataLayer

Sur les évènements begin_checkout et purchase, le plugin pousse :

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

Configuration dans GTM

1. Dans votre conteneur GTM, créez ou éditez votre tag Google Ads Conversion Tracking
2. Section Include user-provided data from your website → Manual configuration
3. Créez huit variables Data Layer Variable pointant vers :
   • user_data.sha256_email_address → mappé sur Email (hashed)
   • user_data.sha256_phone_number → mappé sur 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. Enregistrez et publiez le conteneur

Google Shopping et flux Merchant Center

Pour que GA4 et Google Ads puissent matcher les évènements e-commerce avec vos produits Shopping, chaque item du dataLayer doit utiliser le même item_id que celui du flux Merchant Center.

Champs poussés dans chaque item

• item_id — source configurable (SKU / UUID / EAN)
• item_name — nom du produit dans la langue active
• item_brand — nom du fabricant, ou marque par défaut si non renseigné
• item_category à item_category5 — breadcrumb complet en partant de la catégorie la plus profonde
• google_product_category — voir ci-dessous
• price, quantity, currency
• mpn — Manufacturer Part Number si renseigné sur le produit
• gtin — EAN si renseigné
• discount — calculé depuis la différence entre prix barré et prix de vente

google_product_category par produit

Vous pouvez surcharger la catégorie Google Shopping pour un produit ou une catégorie via un custom field :

1. Dans le back-office : Paramètres → Système → Custom fields → Créer un nouveau set
2. Nom technique : df_google_product_category, type Texte
3. Assignez ce set aux entités Produit et/ou Catégorie
4. Sur chaque produit ou catégorie, renseignez la valeur Google (par exemple Sporting Goods > Athletics > Football > Football Balls)

Le plugin cherche la valeur dans cet ordre : custom field du produit → custom field de sa catégorie la plus profonde → valeur globale par défaut de la configuration.

Server-side GTM

Le server-side tagging permet de router le trafic GTM via un domaine que vous contrôlez, ce qui contourne les bloqueurs navigateur, protège les données utilisateur, et améliore la résilience face aux changements de politique cookies.

Prérequis

• Un conteneur server-side GTM configuré (voir documentation Google)
• Un domaine ou sous-domaine dédié pointant vers votre serveur Tag Manager, par exemple gtm.votredomaine.com

Activation

Dans la configuration du plugin, section Google Tag Manager, renseignez Server-side GTM URL avec votre domaine sans slash final :

https://gtm.votredomaine.com

Le script GTM et l’iframe noscript pointeront automatiquement vers votre serveur au lieu de www.googletagmanager.com.

Vérification

Google Tag Assistant

1. Installez l’extension Chrome Tag Assistant Companion
2. Ouvrez tagassistant.google.com, cliquez sur Add domain et entrez l’URL de votre storefront
3. Naviguez sur une fiche produit, ajoutez au panier, allez au checkout — chaque étape doit apparaître dans l’assistant avec les évènements GA4 correspondants

GA4 DebugView

Dans GA4 : Admin → DebugView. Les évènements y apparaissent en temps réel dès que Debug mode est actif dans le plugin ou que le paramètre debug_mode=true est envoyé.

Mode debug du plugin

Activez Debug mode dans la configuration puis ouvrez la console navigateur. Vous verrez :

[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 de validation

• Sur la home : consent default émis avant le script GTM (ordre des balises dans le head)
• Sur une fiche produit : view_item avec item_id, item_brand, item_category, google_product_category
• Sur ajout au panier : add_to_cart avec le même item
• Sur le panier : view_cart avec tous les items
• Sur la page confirm : begin_checkout avec user_data hashé
• Sur la page finish : purchase avec transaction_id, value, tax, shipping, currency, items et user_data hashé
• Sur acceptation cookies : consent update avec les catégories granted

Résolution de problèmes

Les évènements n’apparaissent pas dans GA4 DebugView

• Vérifiez que le Measurement ID GA4 est correct dans la configuration
• Vérifiez que le tag GA4 Configuration est bien créé et publié dans votre conteneur GTM
• Vérifiez que le déclencheur du tag couvre bien toutes les pages (All Pages)
• Videz le cache Shopware et rechargez la page en hard reload (Ctrl+F5)

Les Enhanced Conversions ne matchent pas

• Vérifiez qu’aucune transformation supplémentaire (variable SHA-256 Hash de GTM) n’est appliquée aux variables user_data — les valeurs sortent déjà hashées
• Vérifiez le format E.164 du téléphone dans le dataLayer (avec préfixe pays commençant par +)
• Vérifiez que le champ country est bien en ISO-2 majuscule (FR, pas France)
• Attendez 24 à 48 heures après l’activation : Google Ads a besoin de ce délai pour la première synchronisation

Consent update pas émis quand l’utilisateur accepte

• Confirmez que le bandeau utilisé est bien celui de Shopware natif
• Ouvrez la console navigateur en mode debug et vérifiez que l’évènement CookieConfiguration_Update est bien émis quand l’utilisateur valide le bandeau
• Vérifiez que les cookies df-gtag-analytics et df-gtag-ads apparaissent dans le bandeau et sont bien cochés

item_id ne matche pas mon flux Merchant Center

• Ouvrez votre flux XML/CSV et regardez le champ <g:id> pour un produit
• Dans la configuration du plugin, choisissez la source item_id qui produit exactement la même valeur (SKU, UUID ou EAN)
• Si votre flux utilise un préfixe (par exemple shopware_SW10001), il faudra créer un tag GTM qui préfixe la valeur avant envoi à Google Ads

Le plugin ne se charge pas sur certaines pages

• Vérifiez que le sales-channel en cours a bien Activer le plugin à ON dans sa configuration spécifique
• Certaines pages personnalisées (landing pages CMS custom) peuvent ne pas déclencher les Page Loaded Events standards. Dans ce cas, le conteneur GTM est quand même chargé via le header pagelet.