# 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…
- Página:
- Idioma: es
- Actualizado el: 2026-07-01
- Otros idiomas: [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), [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), [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)
- Índice:
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
```
**Consejo.** Después de `assets:install`, el archivo `df-gtag-manager.js` se publica en `public/bundles/dfgtagmanager/` y queda accesible vía el asset helper de Twig. No se necesita ningún paso de build webpack o TypeScript.
## 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](https://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](#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](#consent-mode-v2).
- **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](#enhanced-conversions).
### 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)
**¿Por qué wait_for_update: 500?** Esta instrucción le dice a Google que espere hasta 500 ms tras la carga de la página antes de emitir los hits en modo denegado — el tiempo suficiente para que tu banner de cookies recoja la respuesta del usuario y para que el plugin envíe un `gtag consent update`. Sin ese retraso, todos los hits iniciales se emiten en modo denegado incluso si el usuario acepta inmediatamente.
### 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
**Atención.** Google exige que los valores ya lleguen hasheados desde el sitio — no apliques la variable _SHA-256 Hash_ de GTM a esas variables, salen del plugin ya hasheadas. Un doble hash haría imposible el matching.
## 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](https://developers.google.com/tag-platform/tag-manager/server-side))
- 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](https://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 `` 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.