# DataFirefly Cookie Consent für Shopware 6 — Dokumentation

> Übersicht DataFirefly Cookie Consent ist ein Shopware 6 Plugin, das das native Cookie-Banner vollständig durch ein modernes DSGVO/CNIL/Garante Privacy konformes System ersetzt, mit nativem Google Consent Mode v2, echter Tracker-Prüfung…

- Seite: <https://www.datafirefly.com/de/documentation/df-cookie-consent/>
- Sprache: de
- Aktualisiert am: 2026-06-29
- Weitere Sprachen: [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), [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/de/documentation/llms.txt>

## Übersicht

DataFirefly Cookie Consent ist ein Shopware 6 Plugin, das das native Cookie-Banner vollständig durch ein modernes DSGVO/CNIL/Garante Privacy konformes System ersetzt, mit nativem Google Consent Mode v2, echter Tracker-Prüfung und einem kryptografisch geschützten Audit-Protokoll als Einwilligungsnachweis.

**In einem Satz:** drei regulatorische Anforderungen in einem Plugin abgedeckt — Consent Mode v2 (März 2024), Accept/Reject-Gleichwertigkeit (CNIL 2020), Einwilligungsnachweis (DSGVO).

## Voraussetzungen und Kompatibilität

- **Shopware 6.6.x oder 6.7.x** (composer constraint `~6.6.0||~6.7.0`)
- **PHP 8.2 oder höher**
- Selbst gehostete Installation (das Plugin funktioniert **nicht** auf Shopware Cloud SaaS)
- HTTPS in der Produktion empfohlen (das Secure-Cookie-Flag wird nur über HTTPS gesetzt)
- Cloudflare empfohlen für optimale EWR-Erkennung (CF-IPCountry), aber nicht erforderlich

## Installation

### Installation per ZIP-Upload (empfohlen)

1. Laden Sie `DataFireflyCookieConsent-1.0.1.zip` aus Ihrem DataFirefly-Kundenkonto herunter
2. In der Shopware-Administration zu **Erweiterungen → Meine Erweiterungen → Erweiterung hochladen**
3. Wählen Sie die ZIP-Datei und bestätigen Sie
4. Klicken Sie auf **Installieren**, dann **Aktivieren**
5. Cache leeren: `bin/console cache:clear`
6. Theme neu kompilieren: `bin/console theme:compile`

### Installation per Composer (CLI)

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

# Liste aktualisieren, installieren, aktivieren
bin/console plugin:refresh
bin/console plugin:install --activate DataFireflyCookieConsent
bin/console cache:clear
bin/console theme:compile
```

**Gut zu wissen:** das JavaScript des Plugins wird vorkompiliert in `Resources/app/storefront/dist/` ausgeliefert. Sie **müssen** `build-storefront.sh` **nicht** ausführen, damit das Banner funktioniert.

## Allgemeine Konfiguration

Die gesamte Konfiguration erfolgt über **Erweiterungen → Meine Erweiterungen → DataFirefly Cookie Consent → ⋮ → Konfigurieren**. Die Optionen sind pro Sales Channel skopierbar (wählen Sie den Channel oben auf der Konfigurationsseite aus).

### Bereich Allgemein

- **Enabled**: aktiviert oder deaktiviert das Plugin vollständig (Shopwares natives Banner übernimmt wieder, wenn deaktiviert)
- **Policy version**: Version Ihrer Datenschutzerklärung (Standard `1.0`). Erhöhen Sie diese, wenn Sie Ihre Richtlinie ändern, um eine neue Einwilligung zu erzwingen
- **Policy URL**: URL zu Ihrer Datenschutzerklärungsseite (als Link im Banner angezeigt)
- **Respect Do Not Track**: wenn aktiviert, lehnt Cookies automatisch für Besucher mit aktiviertem DNT in ihrem Browser ab

### Bereich Banner

- **Layout**: `bar` (vollbreite Leiste), `card` (diskrete Eckkarte) oder `modal` (blockierendes zentriertes Modal)
- **Position**: `bottom` oder `top`
- **Theme**: `light`, `dark` oder `auto` (folgt prefers-color-scheme)
- **Accent color**: anpassbare Akzentfarbe per Color Picker (Standard `#3b82f6`)
- **Show floating button**: zeigt den persistenten schwebenden Button unten links zum erneuten Öffnen der Einstellungen

### Bereich Kategorien

Aktivieren oder deaktivieren Sie die 3 optionalen Kategorien einzeln. Die Kategorie _Unbedingt erforderlich_ ist immer aktiv.

- **Functional enabled**: Personalisierungs-Cookies, Benutzerpräferenzen
- **Analytics enabled**: Google Analytics 4, Matomo, Reichweitenmessung
- **Marketing enabled**: Werbe-Tracking, Retargeting

## Google Consent Mode v2

Das Plugin druckt automatisch den Block `gtag('consent', 'default', ...)` mit Priorität 1 in den Head des Storefronts, mit den 7 seit März 2024 erforderlichen Signalen: `ad_storage`, `ad_user_data`, `ad_personalization`, `analytics_storage`, `functionality_storage`, `personalization_storage`, `security_storage`.

### Bereich Consent Mode

- **GTM Container ID**: Ihre GTM-ID (`GTM-XXXXXXX`). Wenn gesetzt, lädt das Plugin GTM automatisch **nach** dem default-Block. Leer lassen, um GTM nicht zu laden
- **GA4 Measurement ID**: Ihre GA4-ID (`G-XXXXXXXXXX`). Wenn gesetzt und GTM leer, lädt das Plugin GA4 standalone. Leer lassen, wenn Sie GA4 über GTM laden
- **URL passthrough**: bewahrt URL-Parameter für Ads-Konvertierungen, wenn die Einwilligung abgelehnt wird (empfohlen)
- **Ads data redaction**: anonymisiert Ads-Daten, wenn die Einwilligung abgelehnt wird (empfohlen)
- **Wait for update (ms)**: Verzögerung vor dem ersten GA4/Ads-Ping, damit der Besucher Zeit hat, auf das Banner zu reagieren. Standard `500` ms

**Ausführungsreihenfolge im Head:** 1) `gtag consent default`-Block mit allen Signalen auf `denied` — 2) GTM-Loader, falls konfiguriert — 3) GA4-Loader, falls konfiguriert (und GTM leer) — 4) Banner lädt und Signale werden über `gtag consent update` bei Besucher-Klick aktualisiert.

### Mapping Kategorien → Signale

Wenn der Besucher auf einen Button klickt, werden die ausgewählten Kategorien automatisch den Consent Mode v2 Signalen zugeordnet:

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

## EWR-Erkennung und eeaOnly-Modus

Das Plugin erkennt automatisch das Land des Besuchers, um zu bestimmen, ob die DSGVO greift (31 EU/EWR-Länder + Vereinigtes Königreich + Schweiz).

### Bereich EWR

- **EEA only mode**: wenn aktiviert, wird das Banner nur Besuchern angezeigt, die im EWR erkannt werden. Andere Besucher erhalten eine implizite Einwilligung und sehen nichts
- **Cloudflare support**: wenn aktiviert (Standard true), liest priorität die Header `CF-IPCountry` und `CF-Connecting-IP`, die von Cloudflare hinzugefügt werden

**Mit Cloudflare:** die Erkennung ist sofort und zuverlässig, der `CF-IPCountry`-Header wird kostenlos bei jeder Anfrage hinzugefügt. **Ohne Cloudflare:** Fallback auf `Accept-Language`, um das Land aus der Browser-Locale zu erraten (weniger zuverlässig, aber funktional).

## Tracker-Prüfung

Aus dem Admin-Modul (**Marketing → DataFirefly Cookie Consent → Audit**) starten Sie eine Prüfung Ihrer URL, um tatsächlich vorhandene Tracker zu erkennen und einen Compliance-Score von 0-100 zu erhalten.

### Wie startet man eine Prüfung

1. Gehen Sie zu **Marketing → DataFirefly Cookie Consent → Audit**
2. Geben Sie die zu prüfende URL ein (standardmäßig Ihre aktuelle Shop-URL)
3. Klicken Sie auf **Prüfung starten**
4. Das Ergebnis erscheint in wenigen Sekunden: visueller Score (konischer Ring), erkannte Tracker, risikobehaftete Plugins, Probleme klassifiziert critical/warning/info

### Was erkannt wird

- **23 JavaScript-Tracker**: 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 und mehr
- **11 risikobehaftete Shopware-Plugins**: Datenbankabfrage zur Erkennung von Server-Plugins, die dafür bekannt sind, nicht konforme Cookies zu setzen

### Score-Interpretation

- **90-100**: ausgezeichnet, optimale Compliance
- **70-89**: gut, einige kleinere Anpassungen vorzunehmen
- **50-69**: mittel, critical Probleme zu beheben
- **0-49**: nicht konform, dringender Handlungsbedarf

## Audit-Protokoll und Exporte

Jedes Einwilligungsereignis (accept_all, reject_all, custom, withdraw) wird in der Tabelle `dfcc_consent_log` mit Millisekunden-Zeitstempel, Sales Channel, Sprache, Richtlinienversion, Snapshot der Kategorien und Consent Mode v2 Signale, doppelt geschützter IP und User Agent protokolliert.

### Schutz der Besucher-IP

Einzigartiger doppelter Schutz:

- **SHA-256-Hash** mit einem zufälligen 64-Zeichen-Salt, generiert bei der Installation und nie offengelegt. Mathematisch nicht invertierbar.
- **Gekürzte Version** parallel: IPv4 → letztes Oktett auf null (Klasse-C-Netzwerk), IPv6 → 64-Bit-Präfix. Ermöglicht geografische Analyse ohne Re-Identifikation.

### Protokoll einsehen

1. Gehen Sie zu **Marketing → DataFirefly Cookie Consent → Protokoll**
2. Filtern Sie bei Bedarf nach Ereignistyp und Datumsbereich
3. Die Tabelle paginiert 50 Einträge pro Seite

### Export für DPA/DSGVO-Nachweis

Klicken Sie auf der Protokoll-Seite auf **CSV exportieren** oder **JSON exportieren**: die heruntergeladene Datei enthält alle Einträge, die den aktiven Filtern entsprechen.

- **CSV**: BOM UTF-8 + Semikolon-Trennzeichen (direkt in französischem/italienischem Excel öffenbar)
- **JSON**: pretty (eingerückt) mit erhaltenem Unicode

### Bereich Protokoll

- **Retention days**: Aufbewahrungsdauer in Tagen (Standard 1825 = 5 Jahre, CNIL-Empfehlung)
- Ein geplanter Shopware-Task purgt jeden Nacht automatisch ältere Einträge

## Öffentliche JavaScript-API

Das Plugin stellt eine globale `window.dfcc` API bereit, die aus jedem JavaScript-Code Ihrer Site nutzbar ist.

```
// Banner und Präferenzen-Modal öffnen
window.dfcc.open();

// Alle akzeptieren / ablehnen per Code
window.dfcc.acceptAll();
window.dfcc.rejectAll();

// Einwilligung zurückziehen (löscht Cookie + localStorage)
window.dfcc.withdraw();

// Aktuellen Zustand abrufen
const cats = window.dfcc.getConsent();
// → { necessary: true, functional: false, analytics: true, marketing: false }
// oder null wenn noch keine Einwilligung erteilt

// Einwilligung für eine Kategorie prüfen
if (window.dfcc.hasConsent('analytics')) {
    // Ihr Analytics-Skript laden
}

// Storage-Zustand diagnostizieren (debug)
console.log(window.dfcc.debug());
// → { cookieRaw, localStorageRaw, parsed, policyVersion, protocol, domain }

// Plugin-Version
console.log(window.dfcc.version);
// → "1.0.1"
```

## DOM-Ereignisse

Das Plugin sendet zwei benutzerdefinierte Ereignisse auf `window`:

```
// Wird ausgesendet, sobald das Plugin auf der Seite initialisiert ist
window.addEventListener('dfcc:ready', (event) => {
    console.log('DFCC ready', event.detail.config);
});

// Wird bei jedem Einwilligungswechsel ausgesendet (accept, reject, custom, withdraw)
window.addEventListener('dfcc:consent', (event) => {
    const { categories, eventType, consentMode } = event.detail;
    console.log('Consent changed:', eventType, categories);

    // Drittanbieter-Skript laden, wenn Marketing akzeptiert ist
    if (categories.marketing) {
        loadMyMarketingScript();
    }
});
```

## Multi-Channel (Sales Channels)

Die gesamte Konfiguration ist pro Sales Channel skopierbar. Um einen bestimmten Channel anders zu konfigurieren:

1. Gehen Sie zu **Erweiterungen → Meine Erweiterungen → DataFirefly Cookie Consent → Konfigurieren**
2. Wählen Sie oben auf der Seite den zu konfigurierenden Sales Channel
3. Ändern Sie die Optionen: nur die in dieser Ansicht geänderten Optionen überschreiben die Standardkonfiguration

## Erweiterte Anpassung

### Banner-Wortlaut

Der Banner-Text verwendet Shopwares Standard-Storefront-Snippets. Um einen Text anzupassen, erstellen Sie Ihr eigenes Snippet-Plugin und überschreiben Sie die Schlüssel `dfcc.banner.*` und `dfcc.modal.*`:

```
<!-- custom-snippets/storefront.de-DE.json -->
{
    "dfcc": {
        "banner": {
            "title": "Ihr individueller Titel",
            "body": "Ihre individuelle Beschreibung."
        }
    }
}
```

### CSS-Styling

Alle Banner-Elemente verwenden CSS-Klassen mit dem Präfix `.dfcc-` (z.B. `.dfcc-banner`, `.dfcc-modal`, `.dfcc-button--primary`). Überschreiben Sie sie aus Ihrem Theme oder über das _Custom Code Manager DataFirefly_ Plugin.

## Fehlerbehebung

### Das Banner erscheint nicht

- Prüfen Sie, dass **Enabled** in der Plugin-Konfiguration angekreuzt ist
- Prüfen Sie, dass der **EEA only**-Modus nicht aktiviert ist, während Sie von außerhalb des EWR testen
- Prüfen Sie in der DevTools-Konsole: `window.dfcc` muss definiert sein. Falls nicht, ist das JS nicht geladen → `bin/console theme:compile` erneut ausführen
- Leeren Sie die Domain-Cookies in DevTools → Application → Cookies → Clear all, dann neu laden

### Banner erscheint nach jeder Seite wieder (Bug in v1.0.0, behoben in v1.0.1)

1. Aktualisieren Sie auf v1.0.1, falls noch nicht geschehen
2. Führen Sie `window.dfcc.debug()` in der Konsole aus, um zu diagnostizieren
3. Wenn `cookieRaw` leer ist, aber `localStorageRaw` gefüllt: Ihr Browser blockiert das Cookie-Schreiben (HTTPS-Protokoll und Secure/SameSite-Flags prüfen)
4. Wenn beide leer sind, aber eine Einwilligung geklickt wurde: öffnen Sie ein Support-Ticket mit dem Ergebnis von `debug()`

### Google Ads-Konvertierungen werden nicht zurückgemeldet

- Prüfen Sie, dass **GTM Container ID** oder **GA4 Measurement ID** gesetzt ist
- Prüfen Sie in DevTools → Network: der `gtag consent default`-Block muss **vor** dem Laden von GTM/GA4 ausgeführt werden
- Aktivieren Sie **url_passthrough** und **ads_data_redaction**, um Konvertierungen von Besuchern zu erhalten, die abgelehnt haben
- Prüfen Sie in GA4 → Admin → Data collection → Consent Mode, dass die Parameter erkannt werden

### CSV-Exporte öffnen sich schlecht in Excel

Die Datei wird mit BOM UTF-8 und Semikolon-Trennzeichen generiert (französischer Excel-Standard). Wenn Ihr Excel ein Komma erwartet (englische Versionen), verwenden Sie stattdessen den JSON-Export oder importieren Sie über **Daten → Aus CSV-Datei** und geben Sie das Trennzeichen an.

## Deinstallation

Zum vorübergehenden Deaktivieren:

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

Die Daten bleiben in der Datenbank, Shopwares natives Banner übernimmt wieder.

Zum vollständigen Deinstallieren:

```
bin/console plugin:uninstall --keep-user-data DataFireflyCookieConsent
# oder um auch die Tabelle dfcc_consent_log und die Konfiguration zu löschen:
bin/console plugin:uninstall DataFireflyCookieConsent
```

**Achtung:** ohne das Flag `--keep-user-data` geht das Audit-Protokoll (dfcc_consent_log) verloren. Wenn Sie eine spätere Neuinstallation planen, verwenden Sie immer `--keep-user-data`.

## Changelog

### 1.0.1 — 23. Mai 2026 (Persistenz-Patch)

- Komplette Neuschreibung der clientseitigen Storage-Schicht
- Direktes Cookie-Schreiben mit kombiniertem Max-Age und Expires
- Secure-Flag nur über HTTPS gesetzt
- Automatischer localStorage-Fallback bei fehlgeschlagenem Cookie-Schreiben
- Write→read-Selbsttest mit Konsolen-Log bei Desync
- Neue Methode `window.dfcc.debug()`

### 1.0.0 — 23. Mai 2026 (Erstausgabe)

- Kompatibilität Shopware 6.6 und 6.7
- v3 Banner mit 3 Layouts, 2 Positionen, 3 Themes
- Natives Google Consent Mode v2 mit 7 Signalen
- Echte Tracker-Prüfung (23 Tracker + 11 risikobehaftete Plugins)
- Audit-Protokoll mit doppelt geschützter IP (SHA-256 + truncate)
- Intelligente EWR-Erkennung (31 Länder + GB + CH, Cloudflare-Unterstützung)
- Vue 3 Admin-Modul (mt-*): Dashboard, Audit, Protokoll
- CSV- und JSON-Exporte
- Storefront- und Admin-Snippets für 5 Sprachen