DataFirefly Cookie Consent voor Shopware 6: documentatie

Overzicht

DataFirefly Cookie Consent is een Shopware 6-plugin die de native cookiebanner volledig vervangt door een modern systeem conform de AVG en de richtlijnen van de Europese toezichthouders, met native Google Consent Mode v2, een echte audit van de trackers en een cryptografisch beschermd auditlogboek als bewijs van toestemming.

Vereisten en compatibiliteit

• Shopware 6.6.x of 6.7.x (composer constraint ~6.6.0||~6.7.0)
• PHP 8.2 of hoger
• Zelfgehoste installatie (de plugin werkt niet op Shopware Cloud SaaS)
• HTTPS aanbevolen in productie (de cookievlag Secure wordt alleen bij HTTPS toegevoegd)
• Cloudflare aanbevolen voor een optimale EER-detectie (CF-IPCountry), maar niet verplicht

Installatie

Installatie via ZIP-upload (aanbevolen)

1. Download het bestand DataFireflyCookieConsent-1.0.1.zip vanuit uw DataFirefly-klantaccount
2. Ga in de Shopware-admin naar Extensies → Mijn extensies → Extensie uploaden
3. Selecteer het ZIP-bestand en bevestig
4. Klik op Installeren en daarna op Activeren
5. Leeg de cache: bin/console cache:clear
6. Compileer het thema opnieuw: bin/console theme:compile

Installatie via Composer (CLI)

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

# De lijst verversen, installeren, activeren
bin/console plugin:refresh
bin/console plugin:install --activate DataFireflyCookieConsent
bin/console cache:clear
bin/console theme:compile

Algemene configuratie

De volledige configuratie gebeurt via Extensies → Mijn extensies → DataFirefly Cookie Consent → ⋮ → Configureren. De opties zijn per sales channel in te stellen (selecteer het kanaal bovenaan de configuratiepagina).

Sectie Algemeen

• Enabled: schakelt de plugin volledig in of uit (bij uitschakeling neemt de native banner van Shopware het weer over)
• Policy version: de versie van uw privacyverklaring (standaard 1.0). Verhoog die wanneer u uw verklaring wijzigt om een nieuwe toestemming af te dwingen
• Policy URL: URL naar de pagina met uw privacyverklaring (getoond als link in de banner)
• Respect Do Not Track: indien ingeschakeld worden cookies automatisch geweigerd voor bezoekers die DNT in hun browser hebben aanstaan

Sectie Banner

• Layout: bar (balk over de volle breedte), card (discrete kaart in een hoek) of modal (blokkerend gecentreerd venster)
• Position: bottom of top
• Theme: light, dark of auto (volgt prefers-color-scheme)
• Accent color: aanpasbare accentkleur via een kleurenkiezer (standaard #3b82f6)
• Show floating button: toont de blijvende zwevende knop linksonder om de voorkeuren opnieuw te openen

Sectie Categorieën

Schakel de 3 optionele categorieën afzonderlijk in of uit. De categorie Strikt noodzakelijk is altijd actief.

• Functional enabled: cookies voor personalisatie en gebruikersvoorkeuren
• Analytics enabled: Google Analytics 4, Matomo, bezoekmeting
• Marketing enabled: advertentietracking, retargeting

Google Consent Mode v2

De plugin drukt automatisch het blok gtag('consent', 'default', ...) met prioriteit 1 af in de head van de storefront, met de 7 signalen die sinds maart 2024 vereist zijn: ad_storage, ad_user_data, ad_personalization, analytics_storage, functionality_storage, personalization_storage en security_storage.

Sectie Consent Mode

• GTM Container ID: uw GTM-ID (GTM-XXXXXXX). Indien ingevuld laadt de plugin GTM automatisch na het defaultblok. Laat leeg om GTM niet te laden
• GA4 Measurement ID: uw GA4-ID (G-XXXXXXXXXX). Indien ingevuld en GTM leeg, laadt de plugin GA4 zelfstandig. Laat leeg als u GA4 via GTM laadt
• URL passthrough: behoudt de URL-parameters voor Ads-conversies wanneer de toestemming wordt geweigerd (aanbevolen)
• Ads data redaction: anonimiseert de advertentiegegevens wanneer de toestemming wordt geweigerd (aanbevolen)
• Wait for update (ms): wachttijd vóór de eerste ping naar GA4/Ads, zodat de bezoeker tijd heeft om op de banner te reageren. Standaard 500 ms

Koppeling categorieën naar signalen

Wanneer de bezoeker op een knop klikt, worden de gekozen categorieën automatisch gekoppeld aan de signalen van Consent Mode v2:

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

EER-detectie en modus eeaOnly

De plugin bepaalt automatisch het land van de bezoeker om vast te stellen of de AVG op hem van toepassing is (31 landen van de EU en de EER, plus het Verenigd Koninkrijk en Zwitserland).

Sectie EER

• EEA only mode: indien ingeschakeld verschijnt de banner alleen bij bezoekers die als binnen de EER worden herkend. De andere bezoekers krijgen een impliciete toestemming en zien niets
• Cloudflare support: indien ingeschakeld (standaard true) worden de headers CF-IPCountry en CF-Connecting-IP die Cloudflare toevoegt met voorrang gelezen

Audit van de trackers

Start vanuit de adminmodule (Marketing → DataFirefly Cookie Consent → Audit) een audit van uw URL om de trackers op te sporen die daadwerkelijk aanwezig zijn, en een conformiteitsscore van 0 tot 100 te krijgen.

Een audit starten

1. Ga naar Marketing → DataFirefly Cookie Consent → Audit
2. Vul de te auditen URL in (standaard de huidige URL van uw shop)
3. Klik op Audit starten
4. Het resultaat verschijnt binnen enkele seconden: visuele score (conische ring), gedetecteerde trackers, risicovolle plugins en issues ingedeeld als critical, warning of info

Wat er wordt gedetecteerd

• 23 JavaScript-trackers: 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 en meer
• 11 risicovolle Shopware-plugins: bevraging van de database om serverplugins te herkennen die bekend staan om het plaatsen van niet-conforme cookies

De score interpreteren

• 90-100: uitstekend, optimale conformiteit
• 70-89: goed, enkele kleine aanpassingen nodig
• 50-69: matig, er zijn critical-issues aan te pakken
• 0-49: niet conform, dringende actie vereist

Auditlogboek en exports

Elke toestemmingsgebeurtenis (accept_all, reject_all, custom, withdraw) wordt vastgelegd in de tabel dfcc_consent_log met een tijdstempel tot op de milliseconde, het sales channel, de taal, de versie van de verklaring, een momentopname van de categorieën en de signalen van Consent Mode v2, een dubbel beschermd IP-adres en de user agent.

Bescherming van het IP van de bezoeker

Unieke dubbele bescherming:

• SHA-256-hash met een willekeurig zout van 64 tekens dat bij de installatie wordt gegenereerd en nooit wordt getoond. Wiskundig niet omkeerbaar.
• Afgekapte versie daarnaast: IPv4 → laatste octet op nul (klasse C-netwerk), IPv6 → prefix van 64 bits. Maakt geografische analyse mogelijk zonder heridentificatie.

Het logboek raadplegen

1. Ga naar Marketing → DataFirefly Cookie Consent → Logboek
2. Filter zo nodig op gebeurtenistype en op datumbereik
3. De tabel toont 50 items per pagina

Exporteren als bewijs voor de toezichthouder

Klik op de pagina Logboek op CSV exporteren of JSON exporteren: het gedownloade bestand bevat alle items die aan de actieve filters voldoen.

• CSV: UTF-8 BOM en puntkomma als scheidingsteken (direct te openen in de Franse en Italiaanse versies van Excel)
• JSON: pretty (ingesprongen) met behoud van unicode

Sectie Logboek

• Retention days: bewaartermijn in dagen (standaard 1825, dus 5 jaar, de gangbare aanbeveling)
• Een geplande taak van Shopware ruimt elke nacht automatisch de oudere items op

Publieke JavaScript-API

De plugin stelt een globale API window.dfcc beschikbaar die u vanuit elke JavaScript-code op uw site kunt gebruiken.

// De banner en het voorkeurenvenster openen
window.dfcc.open();

// Alles accepteren of weigeren via code
window.dfcc.acceptAll();
window.dfcc.rejectAll();

// De toestemming intrekken (wist cookie en localStorage)
window.dfcc.withdraw();

// De huidige status ophalen
const cats = window.dfcc.getConsent();
// → { necessary: true, functional: false, analytics: true, marketing: false }
// of null als er nog geen toestemming is gegeven

// De toestemming voor een categorie controleren
if (window.dfcc.hasConsent('analytics')) {
    // laad uw analyticsscript
}

// De status van de opslag diagnosticeren (debug)
console.log(window.dfcc.debug());
// → { cookieRaw, localStorageRaw, parsed, policyVersion, protocol, domain }

// Versie van de plugin
console.log(window.dfcc.version);
// → "1.0.1"

DOM-events

De plugin zendt twee eigen events uit op window:

// Uitgezonden zodra de plugin op de pagina is geïnitialiseerd
window.addEventListener('dfcc:ready', (event) => {
    console.log('DFCC ready', event.detail.config);
});

// Uitgezonden bij elke wijziging van de toestemming (accept, reject, custom, withdraw)
window.addEventListener('dfcc:consent', (event) => {
    const { categories, eventType, consentMode } = event.detail;
    console.log('Consent changed:', eventType, categories);
    
    // Een extern script laden als de categorie marketing is geaccepteerd
    if (categories.marketing) {
        loadMyMarketingScript();
    }
});

Meerdere kanalen (sales channels)

De volledige configuratie is per sales channel in te stellen. Om één kanaal anders in te stellen dan de rest:

1. Ga naar Extensies → Mijn extensies → DataFirefly Cookie Consent → Configureren
2. Selecteer bovenaan de pagina het sales channel dat u wilt instellen
3. Wijzig de opties: alleen de opties die u in deze weergave aanpast, overschrijven de standaardconfiguratie

Geavanceerde aanpassing

Teksten van de banner

De tekst van de banner gebruikt de standaard storefront-snippets van Shopware. Om een tekst aan te passen, maakt u uw eigen snippetplugin en overschrijft u de sleutels dfcc.banner.* en dfcc.modal.*:

<!-- custom-snippets/storefront.nl-NL.json -->
{
    "dfcc": {
        "banner": {
            "title": "Uw eigen titel",
            "body": "Uw eigen beschrijving."
        }
    }
}

CSS-stijl

Alle elementen van de banner gebruiken CSS-klassen met het voorvoegsel .dfcc- (bijvoorbeeld .dfcc-banner, .dfcc-modal, .dfcc-button--primary). Overschrijf ze vanuit uw thema of via de plugin Custom Code Manager DataFirefly.

Probleemoplossing

De banner verschijnt niet

• Controleer of Enabled is aangevinkt in de configuratie van de plugin
• Controleer of de modus EEA only niet actief is terwijl u van buiten de EER test
• Controleer in de console van DevTools of window.dfcc gedefinieerd is. Zo niet, dan is de JS niet geladen: voer bin/console theme:compile opnieuw uit
• Wis de cookies van het domein via DevTools → Application → Cookies → Clear all en herlaad daarna

De banner keert bij elke pagina terug (bug in v1.0.0, opgelost in v1.0.1)

1. Werk bij naar v1.0.1 als u dat nog niet hebt gedaan
2. Voer window.dfcc.debug() uit in de console om te diagnosticeren
3. Is cookieRaw leeg maar localStorageRaw gevuld, dan blokkeert uw browser het schrijven van de cookie (controleer het HTTPS-protocol en de vlaggen Secure en SameSite)
4. Zijn ze allebei leeg terwijl er wel op een toestemming is geklikt, open dan een supportticket met het resultaat van debug()

Google Ads-conversies worden niet doorgegeven

• Controleer of GTM Container ID of GA4 Measurement ID daadwerkelijk is ingevuld
• Controleer in DevTools → Network of het blok gtag consent default vóór het laden van GTM/GA4 wordt uitgevoerd
• Activeer url_passthrough en ads_data_redaction om de conversies van weigerende bezoekers te behouden
• Controleer in GA4 → Admin → Data collection → Consent Mode of de parameters worden herkend

De CSV-exports openen verkeerd in Excel

Het bestand wordt gegenereerd met UTF-8 BOM en puntkomma als scheidingsteken (de standaard voor de Franse Excel). Verwacht uw Excel een komma (Engelse versies), gebruik dan de JSON-export, of importeer via Gegevens → Uit een CSV-bestand en geef het scheidingsteken op.

Verwijderen

Om tijdelijk uit te schakelen:

bin/console plugin:deactivate DataFireflyCookieConsent

De gegevens blijven in de database staan en de native banner van Shopware neemt het weer over.

Om volledig te verwijderen:

bin/console plugin:uninstall --keep-user-data DataFireflyCookieConsent
# of om ook de tabel dfcc_consent_log en de configuratie te wissen:
bin/console plugin:uninstall DataFireflyCookieConsent

Changelog

1.0.1, 23 mei 2026 (patch voor persistentie)

• Volledige herschrijving van de opslaglaag aan JavaScript-zijde
• Rechtstreeks schrijven van de cookie met Max-Age en Expires gecombineerd
• De vlag Secure wordt alleen bij HTTPS toegevoegd
• Automatische terugval op localStorage als het schrijven van de cookie mislukt
• Zelfcontrole write naar read met een consolelog bij desynchronisatie
• Nieuwe methode window.dfcc.debug()

1.0.0, 23 mei 2026 (eerste release)

• Compatibiliteit met Shopware 6.6 en 6.7
• Banner v3 met 3 layouts, 2 posities en 3 thema’s
• Native Google Consent Mode v2 met de 7 signalen
• Echte audit van de trackers (23 trackers en 11 risicovolle plugins)
• Auditlogboek met dubbel beschermd IP (SHA-256 en afkapping)
• Slimme EER-detectie (31 landen plus UK en CH, ondersteuning voor Cloudflare)
• Adminmodule in Vue 3 (mt-*): dashboard, audit, logboek
• CSV- en JSON-exports
• Snippets voor storefront en admin in 5 talen