# DataFirefly Cookie Consent para Shopware 6 — Documentación

> Presentación DataFirefly Cookie Consent es un plugin de Shopware 6 que reemplaza íntegramente el banner de cookies nativo por un sistema moderno conforme con RGPD/CNIL/Garante Privacy, con Google Consent Mode…

- Página: <https://www.datafirefly.com/es/documentation/df-cookie-consent/>
- Idioma: es
- Actualizado el: 2026-06-29
- Otros idiomas: [fr](https://www.datafirefly.com/documentation/df-cookie-consent/index.md), [en](https://www.datafirefly.com/en/documentation/df-cookie-consent/index.md), [de](https://www.datafirefly.com/de/documentation/df-cookie-consent/index.md), [it](https://www.datafirefly.com/it/documentation/df-cookie-consent/index.md), [pl](https://www.datafirefly.com/pl/documentation/df-cookie-consent/index.md), [nl](https://www.datafirefly.com/nl/documentation/df-cookie-consent/index.md), [pt](https://www.datafirefly.com/pt/documentation/df-cookie-consent/index.md)
- Índice: <https://www.datafirefly.com/es/documentation/llms.txt>

## Presentación

DataFirefly Cookie Consent es un plugin de Shopware 6 que reemplaza íntegramente el banner de cookies nativo por un sistema moderno conforme con RGPD/CNIL/Garante Privacy, con Google Consent Mode v2 nativo, auditoría real de trackers y registro de auditoría protegido criptográficamente para la prueba de consentimiento.

**En una frase:** tres exigencias regulatorias cubiertas en un solo plugin — Consent Mode v2 (marzo 2024), equivalencia Aceptar/Rechazar (CNIL 2020), prueba de consentimiento (RGPD).

## Requisitos y compatibilidad

- **Shopware 6.6.x o 6.7.x** (composer constraint `~6.6.0||~6.7.0`)
- **PHP 8.2 o superior**
- Instalación autoalojada (el plugin **no** funciona en Shopware Cloud SaaS)
- HTTPS recomendado en producción (el flag de cookie Secure sólo se añade en HTTPS)
- Cloudflare recomendado para la detección EEE óptima (CF-IPCountry), pero no obligatorio

## Instalación

### Instalación por subida de ZIP (recomendado)

1. Descarga `DataFireflyCookieConsent-1.0.1.zip` desde tu cuenta de cliente DataFirefly
2. En la administración Shopware, ve a **Extensiones → Mis extensiones → Subir extensión**
3. Selecciona el archivo ZIP y confirma
4. Haz clic en **Instalar** y luego **Activar**
5. Limpia la caché: `bin/console cache:clear`
6. Recompila el tema: `bin/console theme:compile`

### Instalación por Composer (CLI)

```
cd /var/www/shopware
# Descomprimir en custom/plugins/
unzip DataFireflyCookieConsent-1.0.1.zip -d custom/plugins/

# Refrescar lista, instalar, activar
bin/console plugin:refresh
bin/console plugin:install --activate DataFireflyCookieConsent
bin/console cache:clear
bin/console theme:compile
```

**Bueno saber:** el JavaScript del plugin se entrega pre-compilado en `Resources/app/storefront/dist/`. **No necesitas** ejecutar `build-storefront.sh` para que el banner funcione.

## Configuración general

Toda la configuración se hace desde **Extensiones → Mis extensiones → DataFirefly Cookie Consent → ⋮ → Configurar**. Las opciones son scopables por sales channel (selecciona el canal en la parte superior de la página de config).

### Sección General

- **Enabled**: activa o desactiva completamente el plugin (el banner nativo de Shopware vuelve a tomar el control si está desactivado)
- **Policy version**: versión de tu política de privacidad (por defecto `1.0`). Increméntala cuando cambies tu política para forzar un nuevo consentimiento
- **Policy URL**: URL hacia tu página de política de privacidad (mostrada como enlace en el banner)
- **Respect Do Not Track**: si está activado, rechaza automáticamente las cookies para visitantes con DNT activado en su navegador

### Sección Banner

- **Layout**: `bar` (barra ancho completo), `card` (tarjeta de esquina discreta), o `modal` (modal centrada bloqueante)
- **Position**: `bottom` o `top`
- **Theme**: `light`, `dark`, o `auto` (sigue prefers-color-scheme)
- **Accent color**: color de acento personalizable vía color picker (por defecto `#3b82f6`)
- **Show floating button**: muestra el botón flotante persistente abajo a la izquierda para reabrir preferencias

### Sección Categorías

Activa o desactiva individualmente las 3 categorías opcionales. La categoría _Estrictamente necesarias_ está siempre activa.

- **Functional enabled**: cookies de personalización, preferencias de usuario
- **Analytics enabled**: Google Analytics 4, Matomo, medición de audiencia
- **Marketing enabled**: tracking publicitario, retargeting

## Google Consent Mode v2

El plugin imprime automáticamente el bloque `gtag('consent', 'default', ...)` con prioridad 1 en el head del storefront, con las 7 señales requeridas desde marzo de 2024: `ad_storage`, `ad_user_data`, `ad_personalization`, `analytics_storage`, `functionality_storage`, `personalization_storage`, `security_storage`.

### Sección Consent Mode

- **GTM Container ID**: tu ID GTM (`GTM-XXXXXXX`). Si está configurado, el plugin carga automáticamente GTM **después** del bloque default. Déjalo vacío para no cargar GTM
- **GA4 Measurement ID**: tu ID GA4 (`G-XXXXXXXXXX`). Si está configurado y GTM vacío, el plugin carga GA4 standalone. Déjalo vacío si cargas GA4 vía GTM
- **URL passthrough**: preserva los parámetros URL para las conversiones Ads cuando el consentimiento es rechazado (recomendado)
- **Ads data redaction**: anonimiza los datos ads cuando el consentimiento es rechazado (recomendado)
- **Wait for update (ms)**: retraso antes del primer ping GA4/Ads, el tiempo que el visitante responda al banner. Por defecto `500` ms

**Orden de ejecución en el head:** 1) bloque `gtag consent default` con todas las señales en `denied` — 2) loader GTM si está configurado — 3) loader GA4 si está configurado (y GTM vacío) — 4) carga del banner y señales actualizadas vía `gtag consent update` al clic del visitante.

### Mapping categorías → señales

Cuando el visitante hace clic en un botón, las categorías seleccionadas se mapean automáticamente a las señales Consent Mode v2:

- **Functional** → `functionality_storage`, `personalization_storage`
- **Analytics** → `analytics_storage`
- **Marketing** → `ad_storage`, `ad_user_data`, `ad_personalization`
- **Necessary** → `security_storage` (siempre granted)

## Detección EEE y modo eeaOnly

El plugin detecta automáticamente el país del visitante para determinar si está concernido por el RGPD (31 países UE/EEE + Reino Unido + Suiza).

### Sección EEE

- **EEA only mode**: si está activado, el banner sólo se muestra a los visitantes detectados como en el EEE. Los demás visitantes reciben un consentimiento implícito y no ven nada
- **Cloudflare support**: si está activado (true por defecto), lee con prioridad las cabeceras `CF-IPCountry` y `CF-Connecting-IP` añadidas por Cloudflare

**Con Cloudflare:** la detección es instantánea y fiable, la cabecera `CF-IPCountry` se añade gratuitamente en cada petición. **Sin Cloudflare:** fallback a `Accept-Language` para adivinar el país a partir del locale del navegador (menos fiable pero funcional).

## Auditoría de trackers

Desde el módulo admin (**Marketing → DataFirefly Cookie Consent → Auditoría**), lanza una auditoría de tu URL para detectar los trackers realmente presentes y obtener una puntuación de conformidad 0-100.

### Cómo lanzar una auditoría

1. Ve a **Marketing → DataFirefly Cookie Consent → Auditoría**
2. Introduce la URL a auditar (por defecto tu URL de tienda actual)
3. Haz clic en **Lanzar auditoría**
4. El resultado se muestra en unos segundos: puntuación visual (anillo cónico), trackers detectados, plugins a riesgo, issues clasificadas critical/warning/info

### Lo que se detecta

- **23 trackers JavaScript**: Google Analytics 4, Google Tag Manager, Meta Pixel, TikTok Pixel, LinkedIn Insight Tag, Pinterest Tag, Snapchat Pixel, Twitter X Pixel, Bing UET, Matomo, Microsoft Clarity, Hotjar, Mixpanel, Plausible, HubSpot, Intercom, Crisp, Tawk, YouTube embed, Vimeo embed, Stripe Elements y más
- **11 plugins Shopware a riesgo**: consulta a la base para detectar plugins servidor conocidos por depositar cookies no conformes

### Interpretación de la puntuación

- **90-100**: excelente, conformidad óptima
- **70-89**: bueno, algunos ajustes menores a hacer
- **50-69**: medio, issues critical a tratar
- **0-49**: no conforme, acción urgente requerida

## Registro de auditoría y exportaciones

Cada evento de consentimiento (accept_all, reject_all, custom, withdraw) se registra en la tabla `dfcc_consent_log` con marca temporal milisegundo, sales channel, idioma, versión política, snapshot de categorías y señales Consent Mode v2, IP doblemente protegida y user agent.

### Protección de la IP del visitante

Doble protección única:

- **Hash SHA-256** con un sal aleatorio de 64 caracteres generado en la instalación y nunca expuesto. Matemáticamente no invertible.
- **Versión truncada** en paralelo: IPv4 → último octeto a cero (red clase C), IPv6 → prefijo 64 bits. Permite análisis geográfico sin reidentificación.

### Consultar el registro

1. Ve a **Marketing → DataFirefly Cookie Consent → Registro**
2. Filtra por tipo de evento y rango de fechas si es necesario
3. La tabla pagina 50 entradas por página

### Exportar para prueba CNIL/AEPD

Desde la página Registro, haz clic en **Exportar CSV** o **Exportar JSON**: el archivo descargado contiene todas las entradas correspondientes a los filtros activos.

- **CSV**: BOM UTF-8 + separador punto y coma (directamente abrible en Excel francés/italiano)
- **JSON**: pretty (indentado) con unicode preservado

### Sección Registro

- **Retention days**: duración de conservación en días (1825 por defecto = 5 años, recomendación CNIL)
- Una tarea programada Shopware purga automáticamente cada noche las entradas más antiguas

## API JavaScript pública

El plugin expone una API global `window.dfcc` utilizable desde cualquier código JavaScript de tu sitio.

```
// Abrir el banner y la modal de preferencias
window.dfcc.open();

// Aceptar / rechazar todo por código
window.dfcc.acceptAll();
window.dfcc.rejectAll();

// Retirar el consentimiento (borra cookie + localStorage)
window.dfcc.withdraw();

// Recuperar el estado actual
const cats = window.dfcc.getConsent();
// → { necessary: true, functional: false, analytics: true, marketing: false }
// o null si aún no se ha dado consentimiento

// Verificar el consentimiento para una categoría
if (window.dfcc.hasConsent('analytics')) {
    // cargar tu script analytics
}

// Diagnosticar el estado del storage (debug)
console.log(window.dfcc.debug());
// → { cookieRaw, localStorageRaw, parsed, policyVersion, protocol, domain }

// Versión del plugin
console.log(window.dfcc.version);
// → "1.0.1"
```

## Eventos DOM

El plugin emite dos eventos personalizados en `window`:

```
// Emitido en cuanto el plugin se inicializa en la página
window.addEventListener('dfcc:ready', (event) => {
    console.log('DFCC ready', event.detail.config);
});

// Emitido en cada cambio de consentimiento (accept, reject, custom, withdraw)
window.addEventListener('dfcc:consent', (event) => {
    const { categories, eventType, consentMode } = event.detail;
    console.log('Consent changed:', eventType, categories);

    // Cargar un script de tercero si marketing es aceptado
    if (categories.marketing) {
        loadMyMarketingScript();
    }
});
```

## Multi-canal (sales channels)

Toda la configuración es scopable por sales channel. Para configurar un canal específico de forma diferente:

1. Ve a **Extensiones → Mis extensiones → DataFirefly Cookie Consent → Configurar**
2. En la parte superior de la página, selecciona el sales channel a configurar
3. Modifica las opciones: sólo las opciones modificadas en esta vista sobrescriben la config por defecto

## Personalización avanzada

### Wording del banner

El texto del banner usa los snippets storefront estándar de Shopware. Para personalizar un texto, crea tu propio plugin de snippets y sobrescribe las claves `dfcc.banner.*` y `dfcc.modal.*`:

```
<!-- custom-snippets/storefront.es-ES.json -->
{
    "dfcc": {
        "banner": {
            "title": "Tu título personalizado",
            "body": "Tu descripción personalizada."
        }
    }
}
```

### Estilo CSS

Todos los elementos del banner usan clases CSS prefijadas `.dfcc-` (por ejemplo `.dfcc-banner`, `.dfcc-modal`, `.dfcc-button--primary`). Sobrescríbelas desde tu tema o vía el plugin _Custom Code Manager DataFirefly_.

## Solución de problemas

### El banner no se muestra

- Verifica que **Enabled** esté marcado en la config del plugin
- Verifica que el modo **EEA only** no esté activado mientras pruebas desde fuera del EEE
- Verifica en la consola DevTools: `window.dfcc` debe estar definido. Si no, el JS no está cargado → relanzar `bin/console theme:compile`
- Vacía las cookies del dominio en DevTools → Application → Cookies → Clear all, luego recarga

### El banner vuelve después de cada página (bug v1.0.0 corregido en v1.0.1)

1. Actualiza a v1.0.1 si aún no lo has hecho
2. Lanza `window.dfcc.debug()` en consola para diagnosticar
3. Si `cookieRaw` está vacío pero `localStorageRaw` está lleno: tu navegador bloquea la escritura cookie (verifica el protocolo HTTPS y los flags Secure/SameSite)
4. Si ambos están vacíos pero un consentimiento fue clicado: abre un ticket de soporte con el resultado de `debug()`

### Conversiones Google Ads no reportadas

- Verifica que **GTM Container ID** o **GA4 Measurement ID** esté configurado
- Verifica en DevTools → Network: el bloque `gtag consent default` debe ejecutarse **antes** del carga de GTM/GA4
- Activa **url_passthrough** y **ads_data_redaction** para preservar las conversiones de visitantes que rechazaron
- Verifica en GA4 → Admin → Data collection → Consent Mode que los parámetros sean reconocidos

### Las exportaciones CSV se abren mal en Excel

El archivo se genera con BOM UTF-8 y separador punto y coma (estándar Excel francés). Si tu Excel espera una coma (versiones inglesas), usa la exportación JSON en su lugar, o importa vía **Datos → Desde archivo CSV** y especifica el separador.

## Desinstalación

Para desactivar temporalmente:

```
bin/console plugin:deactivate DataFireflyCookieConsent
```

Los datos quedan en la base, el banner nativo Shopware vuelve a tomar el control.

Para desinstalar completamente:

```
bin/console plugin:uninstall --keep-user-data DataFireflyCookieConsent
# o para borrar también la tabla dfcc_consent_log y la config:
bin/console plugin:uninstall DataFireflyCookieConsent
```

**Atención:** sin el flag `--keep-user-data`, el registro de auditoría (dfcc_consent_log) se pierde. Si planeas reinstalar más tarde, usa siempre `--keep-user-data`.

## Changelog

### 1.0.1 — 23 mayo 2026 (parche persistencia)

- Reescritura completa de la capa storage del lado JavaScript
- Escritura cookie directa con Max-Age y Expires combinados
- Flag Secure añadido sólo si HTTPS
- Fallback automático localStorage si la escritura cookie falla
- Self-check write→read con log de consola en caso de desincronización
- Nuevo método `window.dfcc.debug()`

### 1.0.0 — 23 mayo 2026 (lanzamiento inicial)

- Compatibilidad Shopware 6.6 y 6.7
- Banner v3 con 3 layouts, 2 posiciones, 3 temas
- Google Consent Mode v2 nativo con las 7 señales
- Auditoría real de trackers (23 trackers + 11 plugins a riesgo)
- Registro de auditoría con IP doblemente protegida (SHA-256 + truncate)
- Detección EEE inteligente (31 países + UK + CH, soporte Cloudflare)
- Módulo Admin Vue 3 (mt-*): dashboard, auditoría, registro
- Exportaciones CSV y JSON
- Snippets storefront y admin para 5 idiomas