# DataFirefly Cookie Consent pour Shopware 6 — Documentation

> Présentation DataFirefly Cookie Consent est un plugin Shopware 6 qui remplace intégralement le bandeau cookies natif par un système moderne conforme RGPD/CNIL/Garante Privacy, avec Google Consent Mode v2 natif, audit…

- Page: <https://www.datafirefly.com/documentation/df-cookie-consent/>
- Langue: fr
- Mis à jour le: 2026-06-29
- Autres langues: [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), [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)
- Index: <https://www.datafirefly.com/documentation/llms.txt>

## Présentation

DataFirefly Cookie Consent est un plugin Shopware 6 qui remplace intégralement le bandeau cookies natif par un système moderne conforme RGPD/CNIL/Garante Privacy, avec Google Consent Mode v2 natif, audit réel des trackers, et journal d'audit cryptographiquement protégé pour la preuve de consentement.

**En une phrase :** trois exigences réglementaires couvertes en un seul plugin — Consent Mode v2 (mars 2024), équivalence Accepter/Refuser (CNIL 2020), preuve de consentement (RGPD).

## Pré-requis et compatibilité

- **Shopware 6.6.x ou 6.7.x** (composer constraint `~6.6.0||~6.7.0`)
- **PHP 8.2 ou supérieur**
- Installation auto-hébergée (le plugin ne fonctionne **pas** sur Shopware Cloud SaaS)
- HTTPS recommandé en production (le flag cookie Secure n'est ajouté qu'en HTTPS)
- Cloudflare recommandé pour la détection EEE optimale (CF-IPCountry), mais non obligatoire

## Installation

### Installation par upload de ZIP (recommandé)

1. Téléchargez le fichier `DataFireflyCookieConsent-1.0.1.zip` depuis votre compte client DataFirefly
2. Dans l'admin Shopware, allez dans **Extensions → Mes extensions → Uploader une extension**
3. Sélectionnez le fichier ZIP et validez
4. Cliquez sur **Installer** puis **Activer**
5. Vider le cache : `bin/console cache:clear`
6. Recompiler le thème : `bin/console theme:compile`

### Installation par Composer (CLI)

```
cd /var/www/shopware
# Décompresser le ZIP dans custom/plugins/
unzip DataFireflyCookieConsent-1.0.1.zip -d custom/plugins/

# Rafraîchir la liste, installer, activer
bin/console plugin:refresh
bin/console plugin:install --activate DataFireflyCookieConsent
bin/console cache:clear
bin/console theme:compile
```

**Bon à savoir :** le JavaScript du plugin est livré pré-compilé dans `Resources/app/storefront/dist/`. Vous n'avez **pas besoin** d'exécuter `build-storefront.sh` pour que le bandeau fonctionne.

## Configuration générale

Toute la configuration se fait depuis **Extensions → Mes extensions → DataFirefly Cookie Consent → ⋮ → Configurer**. Les options sont scopables par sales channel (sélectionnez le canal en haut de la page de config).

### Section Général

- **Enabled** : active ou désactive complètement le plugin (le bandeau natif Shopware reprend la main si désactivé)
- **Policy version** : version de votre politique de confidentialité (par défaut `1.0`). Incrémentez-la quand vous changez votre politique pour forcer un nouveau consentement
- **Policy URL** : URL vers votre page de politique de confidentialité (affichée comme lien dans le bandeau)
- **Respect Do Not Track** : si activé, refuse automatiquement les cookies pour les visiteurs ayant DNT activé dans leur navigateur

### Section Bandeau

- **Layout** : `bar` (barre pleine largeur), `card` (carte d'angle discrète) ou `modal` (modale centrée bloquante)
- **Position** : `bottom` ou `top`
- **Theme** : `light`, `dark` ou `auto` (suit prefers-color-scheme)
- **Accent color** : couleur d'accent personnalisable via color picker (par défaut `#3b82f6`)
- **Show floating button** : affiche le bouton flottant persistant en bas à gauche pour rouvrir les préférences

### Section Catégories

Activez ou désactivez individuellement les 3 catégories optionnelles. La catégorie _Strictement nécessaires_ est toujours active.

- **Functional enabled** : cookies de personnalisation, préférences utilisateur
- **Analytics enabled** : Google Analytics 4, Matomo, mesure d'audience
- **Marketing enabled** : tracking publicitaire, retargeting

## Google Consent Mode v2

Le plugin imprime automatiquement le bloc `gtag('consent', 'default', ...)` en priorité 1 dans le head du storefront, avec les 7 signaux requis depuis mars 2024 : `ad_storage`, `ad_user_data`, `ad_personalization`, `analytics_storage`, `functionality_storage`, `personalization_storage`, `security_storage`.

### Section Consent Mode

- **GTM Container ID** : votre ID GTM (`GTM-XXXXXXX`). Si renseigné, le plugin charge automatiquement GTM **après** le bloc default. Laissez vide pour ne pas charger GTM
- **GA4 Measurement ID** : votre ID GA4 (`G-XXXXXXXXXX`). Si renseigné et GTM vide, le plugin charge GA4 en standalone. Laissez vide si vous chargez GA4 via GTM
- **URL passthrough** : préserve les paramètres URL pour les conversions Ads quand le consentement est refusé (recommandé)
- **Ads data redaction** : anonymise les données ads quand le consentement est refusé (recommandé)
- **Wait for update (ms)** : délai d'attente avant le premier ping GA4/Ads, le temps que le visiteur réponde au bandeau. Par défaut `500` ms

**Ordre d'exécution dans le head :** 1) bloc `gtag consent default` avec tous les signaux à `denied` — 2) loader GTM si configuré — 3) loader GA4 si configuré (et GTM vide) — 4) chargement de la bannière et signaux mis à jour via `gtag consent update` dès le clic visiteur.

### Mapping catégories → signaux

Quand le visiteur clique sur un bouton, les catégories sélectionnées sont automatiquement mappées vers les signaux Consent Mode v2 :

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

## Détection EEE et mode eeaOnly

Le plugin détecte automatiquement le pays du visiteur pour déterminer s'il est concerné par le RGPD (31 pays UE/EEE + Royaume-Uni + Suisse).

### Section EEE

- **EEA only mode** : si activé, le bandeau ne s'affiche qu'aux visiteurs détectés comme étant dans l'EEE. Les autres visiteurs reçoivent un consentement implicite et ne voient rien
- **Cloudflare support** : si activé (true par défaut), lit en priorité les en-têtes `CF-IPCountry` et `CF-Connecting-IP` ajoutés par Cloudflare

**Avec Cloudflare :** la détection est instantanée et fiable, l'en-tête `CF-IPCountry` est ajouté gratuitement sur chaque requête. **Sans Cloudflare :** fallback sur `Accept-Language` pour deviner le pays à partir de la locale du navigateur (moins fiable mais fonctionnel).

## Audit des trackers

Depuis le module admin (**Marketing → DataFirefly Cookie Consent → Audit**), lancez un audit de votre URL pour détecter les trackers réellement présents et obtenir un score de conformité 0-100.

### Comment lancer un audit

1. Allez dans **Marketing → DataFirefly Cookie Consent → Audit**
2. Renseignez l'URL à auditer (par défaut votre URL de boutique courante)
3. Cliquez sur **Lancer l'audit**
4. Le résultat s'affiche en quelques secondes : score visuel (anneau conique), trackers détectés, plugins à risque, issues classées critical/warning/info

### Ce qui est détecté

- **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 et plus
- **11 plugins Shopware à risque** : interrogation de la base pour détecter les plugins serveur connus pour déposer des cookies non-conformes

### Interprétation du score

- **90-100** : excellent, conformité optimale
- **70-89** : bon, quelques ajustements mineurs à faire
- **50-69** : moyen, des issues critical à traiter
- **0-49** : non-conforme, action urgente requise

## Journal d'audit et exports

Chaque événement de consentement (accept_all, reject_all, custom, withdraw) est journalisé dans la table `dfcc_consent_log` avec horodatage milliseconde, sales channel, langue, version politique, snapshot des catégories et signaux Consent Mode v2, IP doublement protégée et user agent.

### Protection de l'IP visiteur

Double protection unique :

- **Hash SHA-256** avec un sel aléatoire de 64 caractères généré à l'installation et jamais exposé. Mathématiquement non inversible.
- **Version tronquée** en parallèle : IPv4 → dernier octet à zéro (réseau classe C), IPv6 → préfixe 64 bits. Permet l'analyse géographique sans réidentification.

### Consulter le journal

1. Allez dans **Marketing → DataFirefly Cookie Consent → Journal**
2. Filtrez par type d'événement et plage de dates si nécessaire
3. Le tableau pagine 50 entrées par page

### Exporter pour preuve CNIL

Depuis la page Journal, cliquez sur **Export CSV** ou **Export JSON** : le fichier téléchargé contient toutes les entrées correspondant aux filtres actifs.

- **CSV** : BOM UTF-8 + séparateur point-virgule (directement ouvrable dans Excel français/italien)
- **JSON** : pretty (indenté) avec unicode préservé

### Section Journal

- **Retention days** : durée de conservation en jours (1825 par défaut = 5 ans, recommandation CNIL)
- Une tâche planifiée Shopware purge automatiquement chaque nuit les entrées plus anciennes

## API JavaScript publique

Le plugin expose une API globale `window.dfcc` utilisable depuis n'importe quel code JavaScript de votre site.

```
// Ouvrir le bandeau et la modale de préférences
window.dfcc.open();

// Accepter / refuser tout par code
window.dfcc.acceptAll();
window.dfcc.rejectAll();

// Retirer le consentement (efface cookie + localStorage)
window.dfcc.withdraw();

// Récupérer l'état actuel
const cats = window.dfcc.getConsent();
// → { necessary: true, functional: false, analytics: true, marketing: false }
// ou null si aucun consentement encore donné

// Vérifier le consentement pour une catégorie
if (window.dfcc.hasConsent('analytics')) {
    // charger ton script analytics
}

// Diagnostiquer l'état du storage (debug)
console.log(window.dfcc.debug());
// → { cookieRaw, localStorageRaw, parsed, policyVersion, protocol, domain }

// Version du plugin
console.log(window.dfcc.version);
// → "1.0.1"
```

## Événements DOM

Le plugin émet deux événements personnalisés sur `window` :

```
// Émis dès que le plugin est initialisé sur la page
window.addEventListener('dfcc:ready', (event) => {
    console.log('DFCC ready', event.detail.config);
});

// Émis à chaque changement de consentement (accept, reject, custom, withdraw)
window.addEventListener('dfcc:consent', (event) => {
    const { categories, eventType, consentMode } = event.detail;
    console.log('Consent changed:', eventType, categories);

    // Charger un script tiers si la catégorie marketing est acceptée
    if (categories.marketing) {
        loadMyMarketingScript();
    }
});
```

## Multi-canal (sales channels)

Toute la configuration est scopable par sales channel. Pour configurer un canal spécifique différemment des autres :

1. Allez dans **Extensions → Mes extensions → DataFirefly Cookie Consent → Configurer**
2. En haut de la page, sélectionnez le sales channel à configurer
3. Modifiez les options : seules les options modifiées dans cette vue override la config par défaut

## Personnalisation avancée

### Wording du bandeau

Le texte du bandeau utilise les snippets storefront standard de Shopware. Pour personnaliser un texte, créez votre propre plugin de snippets et override les clés `dfcc.banner.*` et `dfcc.modal.*` :

```
<!-- custom-snippets/storefront.fr-FR.json -->
{
    "dfcc": {
        "banner": {
            "title": "Votre titre personnalisé",
            "body": "Votre description personnalisée."
        }
    }
}
```

### Style CSS

Tous les éléments du bandeau utilisent des classes CSS préfixées `.dfcc-` (par exemple `.dfcc-banner`, `.dfcc-modal`, `.dfcc-button--primary`). Surchargez-les depuis votre thème ou via le plugin _Custom Code Manager DataFirefly_.

## Dépannage

### Le bandeau ne s'affiche pas

- Vérifiez que **Enabled** est bien coché dans la config plugin
- Vérifiez que le mode **EEA only** n'est pas activé alors que vous testez depuis hors EEE
- Vérifiez en console DevTools : `window.dfcc` doit être défini. Si non, le JS n'est pas chargé → relancer `bin/console theme:compile`
- Videz les cookies du domaine dans DevTools → Application → Cookies → Clear all, puis rechargez

### Le bandeau revient après chaque page (bug v1.0.0 corrigé en v1.0.1)

1. Mettez à jour en v1.0.1 si ce n'est déjà fait
2. Lancez `window.dfcc.debug()` en console pour diagnostiquer
3. Si `cookieRaw` est vide mais `localStorageRaw` est rempli : votre navigateur bloque l'écriture cookie (vérifiez le protocole HTTPS et les flags Secure/SameSite)
4. Si les deux sont vides mais qu'un consentement a bien été cliqué : ouvrir un ticket support avec le résultat de `debug()`

### Conversions Google Ads non remontées

- Vérifiez que **GTM Container ID** ou **GA4 Measurement ID** est bien renseigné
- Vérifiez en DevTools → Network : le bloc `gtag consent default` doit s'exécuter **avant** le chargement de GTM/GA4
- Activez **url_passthrough** et **ads_data_redaction** pour préserver les conversions des visiteurs ayant refusé
- Vérifiez dans GA4 → Admin → Data collection → Consent Mode que les paramètres sont reconnus

### Les exports CSV s'ouvrent mal dans Excel

Le fichier est généré avec BOM UTF-8 et séparateur point-virgule (standard Excel français). Si votre Excel attend une virgule (versions anglaises), utilisez l'export JSON à la place, ou importez via **Données → À partir d'un fichier CSV** et précisez le séparateur.

## Désinstallation

Pour désactiver temporairement :

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

Les données restent en base, le bandeau natif Shopware reprend la main.

Pour désinstaller complètement :

```
bin/console plugin:uninstall --keep-user-data DataFireflyCookieConsent
# ou pour supprimer aussi la table dfcc_consent_log et la config :
bin/console plugin:uninstall DataFireflyCookieConsent
```

**Attention :** sans le flag `--keep-user-data`, le journal d'audit (dfcc_consent_log) est perdu. Si vous prévoyez de réinstaller plus tard, utilisez toujours `--keep-user-data`.

## Changelog

### 1.0.1 — 23 mai 2026 (patch persistance)

- Réécriture complète de la couche storage côté JavaScript
- Écriture cookie directe avec Max-Age et Expires combinés
- Flag Secure ajouté uniquement si HTTPS
- Fallback automatique localStorage si l'écriture cookie échoue
- Self-check write→read avec log console en cas de désynchro
- Nouvelle méthode `window.dfcc.debug()`

### 1.0.0 — 23 mai 2026 (release initiale)

- Compatibilité Shopware 6.6 et 6.7
- Bandeau v3 avec 3 layouts, 2 positions, 3 thèmes
- Google Consent Mode v2 natif avec les 7 signaux
- Audit réel des trackers (23 trackers + 11 plugins à risque)
- Journal d'audit avec IP doublement protégée (SHA-256 + truncate)
- Détection EEE intelligente (31 pays + UK + CH, support Cloudflare)
- Module Admin Vue 3 (mt-*) : dashboard, audit, journal
- Exports CSV et JSON
- Snippets storefront et admin pour 5 langues