DataFirefly Cookie Consent per Shopware 6 — Documentazione

Panoramica

DataFirefly Cookie Consent è un plugin Shopware 6 che sostituisce integralmente il banner cookie nativo con un sistema moderno conforme GDPR/Garante Privacy/CNIL, con Google Consent Mode v2 nativo, audit reale dei tracker, e registro di audit crittograficamente protetto come prova di consenso.

Prerequisiti e compatibilità

• Shopware 6.6.x o 6.7.x (composer constraint ~6.6.0||~6.7.0)
• PHP 8.2 o superiore
• Installazione self-hosted (il plugin non funziona su Shopware Cloud SaaS)
• HTTPS raccomandato in produzione (il flag cookie Secure viene aggiunto solo in HTTPS)
• Cloudflare raccomandato per il rilevamento SEE ottimale (CF-IPCountry), ma non obbligatorio

Installazione

Installazione tramite upload ZIP (raccomandato)

1. Scarica DataFireflyCookieConsent-1.0.1.zip dal tuo account cliente DataFirefly
2. Nell’amministrazione Shopware, vai a Estensioni → Le mie estensioni → Carica estensione
3. Seleziona il file ZIP e conferma
4. Clicca Installa e poi Attiva
5. Svuota la cache: bin/console cache:clear
6. Ricompila il tema: bin/console theme:compile

Installazione tramite Composer (CLI)

cd /var/www/shopware
# Decomprimere in custom/plugins/
unzip DataFireflyCookieConsent-1.0.1.zip -d custom/plugins/

# Aggiornare lista, installare, attivare
bin/console plugin:refresh
bin/console plugin:install --activate DataFireflyCookieConsent
bin/console cache:clear
bin/console theme:compile

Configurazione generale

Tutta la configurazione si fa da Estensioni → Le mie estensioni → DataFirefly Cookie Consent → ⋮ → Configura. Le opzioni sono scopabili per sales channel (seleziona il canale in cima alla pagina di config).

Sezione Generale

• Enabled: attiva o disattiva completamente il plugin (il banner nativo Shopware riprende il controllo se disattivato)
• Policy version: versione della tua informativa sulla privacy (default 1.0). Incrementala quando cambi la tua informativa per forzare un nuovo consenso
• Policy URL: URL verso la pagina della tua informativa sulla privacy (mostrata come link nel banner)
• Respect Do Not Track: se attivato, rifiuta automaticamente i cookie per i visitatori con DNT attivato nel loro browser

Sezione Banner

• Layout: bar (barra a tutta larghezza), card (card d’angolo discreta), o modal (modale centrata bloccante)
• Position: bottom o top
• Theme: light, dark, o auto (segue prefers-color-scheme)
• Accent color: colore di accento personalizzabile tramite color picker (default #3b82f6)
• Show floating button: mostra il pulsante flottante persistente in basso a sinistra per riaprire le preferenze

Sezione Categorie

Attiva o disattiva individualmente le 3 categorie opzionali. La categoria Strettamente necessari è sempre attiva.

• Functional enabled: cookie di personalizzazione, preferenze utente
• Analytics enabled: Google Analytics 4, Matomo, misurazione di audience
• Marketing enabled: tracking pubblicitario, retargeting

Google Consent Mode v2

Il plugin stampa automaticamente il blocco gtag('consent', 'default', ...) con priorità 1 nell’head dello storefront, con i 7 segnali richiesti da marzo 2024: ad_storage, ad_user_data, ad_personalization, analytics_storage, functionality_storage, personalization_storage, security_storage.

Sezione Consent Mode

• GTM Container ID: il tuo ID GTM (GTM-XXXXXXX). Se impostato, il plugin carica automaticamente GTM dopo il blocco default. Lascialo vuoto per non caricare GTM
• GA4 Measurement ID: il tuo ID GA4 (G-XXXXXXXXXX). Se impostato e GTM vuoto, il plugin carica GA4 standalone. Lascialo vuoto se carichi GA4 via GTM
• URL passthrough: preserva i parametri URL per le conversioni Ads quando il consenso è rifiutato (raccomandato)
• Ads data redaction: anonimizza i dati ads quando il consenso è rifiutato (raccomandato)
• Wait for update (ms): ritardo prima del primo ping GA4/Ads, il tempo che il visitatore risponda al banner. Default 500 ms

Mapping categorie → segnali

Quando il visitatore clicca un pulsante, le categorie selezionate sono mappate automaticamente ai segnali Consent Mode v2:

• Functional → functionality_storage, personalization_storage
• Analytics → analytics_storage
• Marketing → ad_storage, ad_user_data, ad_personalization
• Necessary → security_storage (sempre granted)

Rilevamento SEE e modalità eeaOnly

Il plugin rileva automaticamente il paese del visitatore per determinare se è soggetto al GDPR (31 paesi UE/SEE + Regno Unito + Svizzera).

Sezione SEE

• EEA only mode: se attivato, il banner viene mostrato solo ai visitatori rilevati come nel SEE. Gli altri visitatori ricevono un consenso implicito e non vedono nulla
• Cloudflare support: se attivato (true di default), legge in priorità gli header CF-IPCountry e CF-Connecting-IP aggiunti da Cloudflare

Audit dei tracker

Dal modulo admin (Marketing → DataFirefly Cookie Consent → Audit), avvia un audit della tua URL per rilevare i tracker realmente presenti e ottenere un punteggio di conformità 0-100.

Come avviare un audit

1. Vai a Marketing → DataFirefly Cookie Consent → Audit
2. Inserisci l’URL da auditare (di default la tua URL di negozio corrente)
3. Clicca Avvia audit
4. Il risultato viene mostrato in pochi secondi: punteggio visivo (anello conico), tracker rilevati, plugin a rischio, issue classificate critical/warning/info

Cosa viene rilevato

• 23 tracker 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 e altri
• 11 plugin Shopware a rischio: interrogazione del database per rilevare plugin server noti per depositare cookie non conformi

Interpretazione del punteggio

• 90-100: eccellente, conformità ottimale
• 70-89: buono, alcuni aggiustamenti minori da fare
• 50-69: medio, issue critical da trattare
• 0-49: non conforme, azione urgente richiesta

Registro di audit ed esportazioni

Ogni evento di consenso (accept_all, reject_all, custom, withdraw) viene registrato nella tabella dfcc_consent_log con timestamp millisecondo, sales channel, lingua, versione policy, snapshot delle categorie e segnali Consent Mode v2, IP doppiamente protetta e user agent.

Protezione dell’IP del visitatore

Doppia protezione unica:

• Hash SHA-256 con un sale casuale di 64 caratteri generato all’installazione e mai esposto. Matematicamente non invertibile.
• Versione troncata in parallelo: IPv4 → ultimo ottetto a zero (rete classe C), IPv6 → prefisso 64 bit. Permette analisi geografica senza re-identificazione.

Consultare il registro

1. Vai a Marketing → DataFirefly Cookie Consent → Registro
2. Filtra per tipo di evento e intervallo di date se necessario
3. La tabella pagina 50 voci per pagina

Esportare per prova Garante Privacy

Dalla pagina Registro, clicca Esporta CSV o Esporta JSON: il file scaricato contiene tutte le voci corrispondenti ai filtri attivi.

• CSV: BOM UTF-8 + separatore punto e virgola (direttamente apribile in Excel italiano)
• JSON: pretty (indentato) con unicode preservato

Sezione Registro

• Retention days: durata di conservazione in giorni (1825 di default = 5 anni, raccomandazione del Garante)
• Un task pianificato Shopware purga automaticamente ogni notte le voci più vecchie

API JavaScript pubblica

Il plugin espone un’API globale window.dfcc utilizzabile da qualsiasi codice JavaScript del tuo sito.

// Aprire il banner e la modale delle preferenze
window.dfcc.open();

// Accettare / rifiutare tutto da codice
window.dfcc.acceptAll();
window.dfcc.rejectAll();

// Ritirare il consenso (cancella cookie + localStorage)
window.dfcc.withdraw();

// Recuperare lo stato corrente
const cats = window.dfcc.getConsent();
// → { necessary: true, functional: false, analytics: true, marketing: false }
// o null se nessun consenso ancora dato

// Verificare il consenso per una categoria
if (window.dfcc.hasConsent('analytics')) {
    // caricare il tuo script analytics
}

// Diagnosticare lo stato dello storage (debug)
console.log(window.dfcc.debug());
// → { cookieRaw, localStorageRaw, parsed, policyVersion, protocol, domain }

// Versione del plugin
console.log(window.dfcc.version);
// → "1.0.1"

Eventi DOM

Il plugin emette due eventi personalizzati su window:

// Emesso non appena il plugin viene inizializzato sulla pagina
window.addEventListener('dfcc:ready', (event) => {
    console.log('DFCC ready', event.detail.config);
});

// Emesso a ogni cambio di consenso (accept, reject, custom, withdraw)
window.addEventListener('dfcc:consent', (event) => {
    const { categories, eventType, consentMode } = event.detail;
    console.log('Consent changed:', eventType, categories);
    
    // Caricare uno script di terze parti se marketing è accettato
    if (categories.marketing) {
        loadMyMarketingScript();
    }
});

Multi-canale (sales channels)

Tutta la configurazione è scopabile per sales channel. Per configurare un canale specifico in modo diverso:

1. Vai a Estensioni → Le mie estensioni → DataFirefly Cookie Consent → Configura
2. In cima alla pagina, seleziona il sales channel da configurare
3. Modifica le opzioni: solo le opzioni modificate in questa vista sovrascrivono la config di default

Personalizzazione avanzata

Wording del banner

Il testo del banner usa gli snippet storefront standard di Shopware. Per personalizzare un testo, crea il tuo plugin di snippet e sovrascrivi le chiavi dfcc.banner.* e dfcc.modal.*:

<!-- custom-snippets/storefront.it-IT.json -->
{
    "dfcc": {
        "banner": {
            "title": "Il tuo titolo personalizzato",
            "body": "La tua descrizione personalizzata."
        }
    }
}

Stile CSS

Tutti gli elementi del banner usano classi CSS prefissate .dfcc- (per esempio .dfcc-banner, .dfcc-modal, .dfcc-button--primary). Sovrascrivile dal tuo tema o tramite il plugin Custom Code Manager DataFirefly.

Risoluzione dei problemi

Il banner non viene mostrato

• Verifica che Enabled sia spuntato nella config del plugin
• Verifica che la modalità EEA only non sia attivata mentre stai testando da fuori del SEE
• Verifica nella console DevTools: window.dfcc deve essere definito. Se no, il JS non è caricato → rilanciare bin/console theme:compile
• Svuota i cookie del dominio in DevTools → Application → Cookies → Clear all, poi ricarica

Il banner ritorna ad ogni pagina (bug v1.0.0 corretto in v1.0.1)

1. Aggiorna a v1.0.1 se non l’hai già fatto
2. Lancia window.dfcc.debug() in console per diagnosticare
3. Se cookieRaw è vuoto ma localStorageRaw è pieno: il tuo browser blocca la scrittura cookie (verifica il protocollo HTTPS e i flag Secure/SameSite)
4. Se entrambi sono vuoti ma un consenso è stato cliccato: apri un ticket di supporto con il risultato di debug()

Conversioni Google Ads non riportate

• Verifica che GTM Container ID o GA4 Measurement ID sia impostato
• Verifica in DevTools → Network: il blocco gtag consent default deve eseguirsi prima del caricamento di GTM/GA4
• Attiva url_passthrough e ads_data_redaction per preservare le conversioni dei visitatori che hanno rifiutato
• Verifica in GA4 → Admin → Data collection → Consent Mode che i parametri siano riconosciuti

Le esportazioni CSV si aprono male in Excel

Il file viene generato con BOM UTF-8 e separatore punto e virgola (standard Excel italiano). Se il tuo Excel si aspetta una virgola (versioni inglesi), usa l’esportazione JSON invece, o importa tramite Dati → Da file CSV e specifica il separatore.

Disinstallazione

Per disattivare temporaneamente:

bin/console plugin:deactivate DataFireflyCookieConsent

I dati restano nel database, il banner nativo Shopware riprende il controllo.

Per disinstallare completamente:

bin/console plugin:uninstall --keep-user-data DataFireflyCookieConsent
# o per eliminare anche la tabella dfcc_consent_log e la config:
bin/console plugin:uninstall DataFireflyCookieConsent

Changelog

1.0.1 — 23 maggio 2026 (patch persistenza)

• Riscrittura completa del livello storage lato JavaScript
• Scrittura cookie diretta con Max-Age ed Expires combinati
• Flag Secure aggiunto solo se HTTPS
• Fallback automatico localStorage se la scrittura cookie fallisce
• Self-check write→read con log console in caso di desincronizzazione
• Nuovo metodo window.dfcc.debug()

1.0.0 — 23 maggio 2026 (release iniziale)

• Compatibilità Shopware 6.6 e 6.7
• Banner v3 con 3 layout, 2 posizioni, 3 temi
• Google Consent Mode v2 nativo con i 7 segnali
• Audit reale dei tracker (23 tracker + 11 plugin a rischio)
• Registro di audit con IP doppiamente protetta (SHA-256 + truncate)
• Rilevamento SEE intelligente (31 paesi + UK + CH, supporto Cloudflare)
• Modulo Admin Vue 3 (mt-*): dashboard, audit, registro
• Esportazioni CSV e JSON
• Snippet storefront e admin per 5 lingue