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 v2 nativo, auditoría real de trackers y registro de auditoría protegido criptográficamente para la prueba de consentimiento.

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

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

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

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

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