# 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…

- Pagina: <https://www.datafirefly.com/it/documentation/df-cookie-consent/>
- Lingua: it
- Aggiornato il: 2026-06-29
- Altre lingue: [fr](https://www.datafirefly.com/documentation/df-cookie-consent/index.md), [en](https://www.datafirefly.com/en/documentation/df-cookie-consent/index.md), [es](https://www.datafirefly.com/es/documentation/df-cookie-consent/index.md), [de](https://www.datafirefly.com/de/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)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

## 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.

**In una frase:** tre requisiti normativi coperti in un solo plugin — Consent Mode v2 (marzo 2024), equivalenza Accetta/Rifiuta (Garante 2021), prova di consenso (GDPR).

## 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
```

**Buono a sapersi:** il JavaScript del plugin viene consegnato pre-compilato in `Resources/app/storefront/dist/`. **Non hai bisogno** di eseguire `build-storefront.sh` perché il banner funzioni.

## 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

**Ordine di esecuzione nell'head:** 1) blocco `gtag consent default` con tutti i segnali a `denied` — 2) loader GTM se configurato — 3) loader GA4 se configurato (e GTM vuoto) — 4) caricamento del banner e segnali aggiornati tramite `gtag consent update` al clic del visitatore.

### 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

**Con Cloudflare:** il rilevamento è istantaneo e affidabile, l'header `CF-IPCountry` viene aggiunto gratuitamente su ogni richiesta. **Senza Cloudflare:** fallback su `Accept-Language` per indovinare il paese dalla locale del browser (meno affidabile ma funzionale).

## 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
```

**Attenzione:** senza il flag `--keep-user-data`, il registro di audit (dfcc_consent_log) viene perso. Se prevedi di reinstallare in seguito, usa sempre `--keep-user-data`.

## 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