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 und einem kryptografisch geschützten Audit-Protokoll als Einwilligungsnachweis.

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

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

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

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

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