DfGtagManager — Documentación completa

DfGtagManager es un plugin de Shopware 6.7 que inyecta un contenedor Google Tag Manager, emite los eventos GA4 e-commerce completos, gestiona Consent Mode v2 con el banner de cookies Shopware nativo, envía las Enhanced Conversions hasheadas SHA-256 y alinea el data layer con tu feed Google Merchant Center. Esta documentación cubre la instalación, la configuración completa y la verificación.

Requisitos previos

• Shopware 6.7.0 o más reciente
• PHP 8.2 mínimo
• Acceso SSH o administración Shopware para instalar el ZIP
• Una cuenta de Google Tag Manager (recomendado) o al menos una cuenta Google Analytics 4
• Para las Enhanced Conversions: una cuenta Google Ads con campañas de conversión configuradas

Instalación

Tres métodos posibles según tu entorno.

Desde la administración Shopware

1. En el back-office: Extensiones → Mis extensiones → Cargar extensión
2. Selecciona el archivo DfGtagManager.zip
3. Haz clic en Instalar y luego en Activar
4. Vacía la caché: Configuración → Sistema → Caché e índices → Vaciar y regenerar

Desde la línea de comandos (recomendado en producción)

cd /ruta/a/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

Configuración

Abre la configuración: Extensiones → Mis extensiones → DataFirefly Google Tag Manager → menú ⋮ → Configurar. Selecciona el sales-channel correspondiente en la parte superior — cada sales-channel puede tener su propia configuración independiente.

Ajustes generales

• Activar plugin: interruptor maestro. Desactívalo para cortar toda inyección sin desinstalar.
• Modo debug: muestra logs prefijados [DfGtag] en la consola del navegador (add_to_cart, remove_from_cart, consent update…). Actívalo únicamente en entornos de test.

Google Tag Manager

• GTM Container ID: formato GTM-XXXXXXX. Se recupera en tagmanager.google.com arriba a la derecha de tu contenedor. Déjalo vacío si no usas GTM: el plugin caerá automáticamente al loader gtag.js si hay un Measurement ID GA4 configurado.
• Server-side GTM URL (opcional): URL de tu loader Tag Manager server-side (por ejemplo https://gtm.tudominio.com, sin barra final). Ver la sección Server-side GTM más abajo.

Google Analytics 4

• GA4 Measurement ID: formato G-XXXXXXXXXX. Se recupera en GA4 en Administrar → Flujos de datos → Web. Se usa como fallback gtag.js cuando no hay contenedor GTM configurado, y se envía al dataLayer para los tags GTM.
• Enviar evento page_view automático: activado por defecto. Desactívalo si prefieres disparar page_view manualmente desde GTM.

Consent Mode v2

• Activar Consent Mode v2: emite gtag consent default antes de que se cargue GTM, con las siete categorías Consent Mode v2. Ver Consent Mode v2 en detalle.
• Estado de consentimiento por defecto:
  • Rechazado — recomendado para UE/RGPD. No se deposita ninguna cookie analítica o publicitaria antes de la aceptación del usuario.
  • Concedido — a reservar para visitantes fuera de la UE o tiendas para público profesional no sujeto al RGPD.
• Activar url_passthrough: conserva los parámetros gclid, _gl, dclid entre páginas incluso cuando las cookies están rechazadas. Útil para atribución multi-touch.
• Activar ads_data_redaction si rechazado: redacta los identificadores publicitarios enviados a Google Ads cuando el usuario rechaza. Reduce aún más la superficie de tracking.

Enhanced Conversions

• Activar Enhanced Conversions: envía un objeto user_data con email, teléfono, nombre, apellido, calle, ciudad, código postal, todo hasheado SHA-256 en el servidor, en las páginas confirm y finish del embudo. Ver Enhanced Conversions en detalle.

Google Shopping / Merchant Center

• Fuente item_id: determina lo que el plugin envía como item_id en cada item GA4. Este valor debe coincidir con el campo id de tu feed Merchant Center. Tres opciones:
  • Product number (SKU) — recomendado, el formato más común en los feeds XML/CSV de Merchant Center.
  • Shopware UUID — útil si generas tu feed directamente desde la base de datos Shopware.
  • EAN / GTIN — útil si tu feed está alineado con códigos de barras internacionales.
• Categoría Google por defecto: valor enviado a google_product_category cuando ni el producto ni su categoría definen uno. Formato Google (por ejemplo Apparel & Accessories > Clothing).
• Marca por defecto: usada como fallback en item_brand cuando el producto no tiene fabricante asignado.

Eventos

Cada evento GA4 se puede activar individualmente. Desmarca los que no quieras.

• view_item — ficha de producto
• view_item_list — página de categoría y resultados de búsqueda
• add_to_cart — clic en el botón de añadir al carrito (listener JavaScript)
• remove_from_cart — eliminación de una línea del carrito u offcanvas
• view_cart — página del carrito
• begin_checkout — página de confirmación del embudo
• purchase — página finish tras el pedido
• search — página de resultados de búsqueda
• login / sign_up — envío de formularios de cuenta

Consent Mode v2 en detalle

Consent Mode v2 es el mecanismo oficial de Google para gestionar el consentimiento del usuario. Desde marzo de 2024, Google Ads lo exige a los anunciantes que se dirigen al Espacio Económico Europeo — sin él, pierdes el acceso al remarketing y a la medición de conversiones.

Orden de carga

El plugin garantiza el siguiente orden en cada página del storefront:

1. Inicialización de window.dataLayer y del stub gtag()
2. Emisión de gtag consent default con las siete categorías Consent Mode v2 y wait_for_update: 500
3. Emisión de url_passthrough y ads_data_redaction si están activos
4. Envío de los eventos GA4 de la página (view_item, view_cart…) al dataLayer
5. Carga del script GTM (o gtag.js como fallback)

Integración con el banner de cookies Shopware

El plugin decora CookieProviderInterface y registra dos cookies virtuales en los grupos del banner nativo:

• df-gtag-analytics en el grupo Estadísticas — controla analytics_storage
• df-gtag-ads en el grupo Marketing — controla ad_storage, ad_user_data, ad_personalization

Cuando el usuario valida sus preferencias, Shopware emite el evento CookieConfiguration_Update. El controlador JavaScript del plugin lo escucha, lee el valor de las dos cookies virtuales y emite inmediatamente el gtag consent update correspondiente.

Compatibilidad con un banner de terceros

Si usas Cookiebot, CookieFirst, OneTrust o Axeptio en lugar del banner nativo Shopware, tienes que emitir tú mismo el gtag consent update desde el banner de terceros con las categorías correctas. El plugin no te lo impide — sólo gestiona el consent default inicial y la escucha del evento Shopware.

Enhanced Conversions en detalle

Las Enhanced Conversions mejoran la precisión de la medición de Google Ads enviando datos de usuario first-party (email, teléfono, nombre, dirección) hasheados SHA-256 en el momento de una conversión. Google entonces reconecta esas conversiones con los usuarios de Google conectados, lo que normalmente recupera del 10 al 30 % de conversiones antes perdidas por bloqueadores de cookies, tracking cross-device o cambios de navegador.

Normalización aplicada

El plugin normaliza cada campo conforme a la especificación Google antes del hashing:

• Email: lowercased, trimmed y luego SHA-256
• Teléfono: E.164 (prefijo de país automático desde el ISO de la dirección de facturación, ejemplo +34612345678), luego SHA-256
• Nombre, apellido, calle, ciudad: lowercased, trimmed y luego SHA-256
• Código postal: lowercased, trimmed; para EE.UU. se trunca a los 5 primeros dígitos antes del hashing
• País: código ISO-2 en mayúsculas, no hasheado

Payload dataLayer

En los eventos begin_checkout y purchase, el plugin envía:

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

Configuración en GTM

1. En tu contenedor GTM, crea o edita tu tag Google Ads Conversion Tracking
2. Sección Include user-provided data from your website → Manual configuration
3. Crea ocho Data Layer Variables apuntando a:
   • user_data.sha256_email_address → mapeado a Email (hashed)
   • user_data.sha256_phone_number → mapeado 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. Guarda y publica el contenedor

Google Shopping y feed Merchant Center

Para que GA4 y Google Ads puedan casar correctamente los eventos e-commerce con tus productos Shopping, cada item del dataLayer debe usar el mismo item_id que el de tu feed Merchant Center.

Campos enviados en cada item

• item_id — fuente configurable (SKU / UUID / EAN)
• item_name — nombre del producto en el idioma activo
• item_brand — nombre del fabricante, o marca por defecto si no está definido
• item_category a item_category5 — breadcrumb completo empezando por la categoría más profunda
• google_product_category — ver abajo
• price, quantity, currency
• mpn — Manufacturer Part Number cuando esté informado
• gtin — EAN cuando esté informado
• discount — calculado desde la diferencia entre precio tachado y precio de venta

google_product_category por producto

Puedes sobrescribir la categoría Google Shopping para un producto o una categoría vía un custom field:

1. En el back-office: Configuración → Sistema → Custom fields → Crear nuevo set
2. Nombre técnico: df_google_product_category, tipo Texto
3. Asigna ese set a las entidades Producto y/o Categoría
4. En cada producto o categoría, informa el valor Google (por ejemplo Sporting Goods > Athletics > Football > Football Balls)

El plugin busca el valor en este orden: custom field del producto → custom field de su categoría más profunda → valor global por defecto de la configuración.

Server-side GTM

El server-side tagging permite enrutar el tráfico GTM por un dominio que tú controlas, lo que esquiva los bloqueadores del navegador, protege los datos de usuario y mejora la resiliencia frente a cambios en la política de cookies.

Requisitos previos

• Un contenedor server-side GTM configurado (ver documentación Google)
• Un dominio o subdominio dedicado apuntando a tu servidor Tag Manager, por ejemplo gtm.tudominio.com

Activación

En la configuración del plugin, sección Google Tag Manager, indica Server-side GTM URL con tu dominio sin barra final:

https://gtm.tudominio.com

El script GTM y el iframe noscript apuntarán automáticamente a tu servidor en lugar de www.googletagmanager.com.

Verificación

Google Tag Assistant

1. Instala la extensión Chrome Tag Assistant Companion
2. Abre tagassistant.google.com, haz clic en Add domain e introduce la URL de tu storefront
3. Navega a una ficha de producto, añade al carrito, ve al checkout — cada paso debe aparecer en el asistente con los eventos GA4 correspondientes

GA4 DebugView

En GA4: Administrar → DebugView. Los eventos aparecen en tiempo real en cuanto Debug mode está activo en el plugin o se envía el parámetro debug_mode=true.

Modo debug del plugin

Activa Debug mode en la configuración y abre la consola del navegador. Verás:

[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 validación

• En la home: consent default emitido antes del script GTM (orden de las balizas en el head)
• En una ficha de producto: view_item con item_id, item_brand, item_category, google_product_category
• Al añadir al carrito: add_to_cart con el mismo item
• En el carrito: view_cart con todos los items
• En la página confirm: begin_checkout con user_data hasheado
• En la página finish: purchase con transaction_id, value, tax, shipping, currency, items y user_data hasheado
• Al aceptar cookies: consent update con las categorías granted

Solución de problemas

Los eventos no aparecen en GA4 DebugView

• Comprueba que el Measurement ID GA4 es correcto en la configuración
• Comprueba que el tag GA4 Configuration está creado y publicado en tu contenedor GTM
• Comprueba que el activador del tag cubre todas las páginas (All Pages)
• Vacía la caché de Shopware y recarga la página en hard reload (Ctrl+F5)

Las Enhanced Conversions no casan

• Comprueba que no se aplica ninguna transformación adicional (variable SHA-256 Hash de GTM) a las variables user_data — los valores salen ya hasheados
• Comprueba el formato E.164 del teléfono en el dataLayer (con prefijo de país empezando por +)
• Comprueba que el campo country está en ISO-2 mayúsculas (ES, no España)
• Espera 24 a 48 horas tras la activación: Google Ads necesita ese plazo para la primera sincronización

Consent update no emitido cuando el usuario acepta

• Confirma que el banner en uso es el nativo de Shopware
• Abre la consola del navegador en modo debug y comprueba que el evento CookieConfiguration_Update se emite cuando el usuario valida el banner
• Comprueba que las cookies df-gtag-analytics y df-gtag-ads aparecen en el banner y están marcadas

item_id no coincide con mi feed Merchant Center

• Abre tu feed XML/CSV y mira el campo <g:id> de un producto
• En la configuración del plugin, elige la fuente item_id que produce exactamente el mismo valor (SKU, UUID o EAN)
• Si tu feed usa un prefijo (por ejemplo shopware_SW10001), tendrás que crear un tag GTM que anteponga el prefijo al valor antes de enviarlo a Google Ads

El plugin no se carga en algunas páginas

• Comprueba que el sales-channel en curso tiene Activar plugin en ON en su configuración específica
• Algunas páginas personalizadas (landing pages CMS custom) pueden no disparar los Page Loaded Events estándar. En ese caso, el contenedor GTM se carga igualmente vía el header pagelet.