# DataFirefly Cookie Consent for Shopware 6 — Documentation

> Overview DataFirefly Cookie Consent is a Shopware 6 plugin that fully replaces the native cookie banner with a modern GDPR/CNIL/Garante Privacy compliant system, with native Google Consent Mode v2, real…

- Page: <https://www.datafirefly.com/en/documentation/df-cookie-consent/>
- Language: en
- Last updated: 2026-06-29
- Other languages: [fr](https://www.datafirefly.com/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/en/documentation/llms.txt>

## Overview

DataFirefly Cookie Consent is a Shopware 6 plugin that fully replaces the native cookie banner with a modern GDPR/CNIL/Garante Privacy compliant system, with native Google Consent Mode v2, real tracker auditing, and a cryptographically protected audit log for consent evidence.

**In one sentence:** three regulatory requirements covered in one plugin — Consent Mode v2 (March 2024), Accept/Reject equivalence (CNIL 2020), consent evidence (GDPR).

## Requirements and compatibility

- **Shopware 6.6.x or 6.7.x** (composer constraint `~6.6.0||~6.7.0`)
- **PHP 8.2 or higher**
- Self-hosted installation (the plugin does **not** work on Shopware Cloud SaaS)
- HTTPS recommended in production (the Secure cookie flag is only added on HTTPS)
- Cloudflare recommended for optimal EEA detection (CF-IPCountry), but not required

## Installation

### Installation via ZIP upload (recommended)

1. Download `DataFireflyCookieConsent-1.0.1.zip` from your DataFirefly customer account
2. In the Shopware admin, go to **Extensions → My Extensions → Upload extension**
3. Select the ZIP file and confirm
4. Click **Install** then **Activate**
5. Clear the cache: `bin/console cache:clear`
6. Recompile the theme: `bin/console theme:compile`

### Installation via Composer (CLI)

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

# Refresh list, install, activate
bin/console plugin:refresh
bin/console plugin:install --activate DataFireflyCookieConsent
bin/console cache:clear
bin/console theme:compile
```

**Good to know:** the plugin's JavaScript is shipped pre-compiled in `Resources/app/storefront/dist/`. You do **not need** to run `build-storefront.sh` for the banner to work.

## General configuration

All configuration is done from **Extensions → My Extensions → DataFirefly Cookie Consent → ⋮ → Configure**. Options are scopable per sales channel (select the channel at the top of the config page).

### General section

- **Enabled**: enables or disables the plugin entirely (Shopware's native banner takes over when disabled)
- **Policy version**: version of your privacy policy (default `1.0`). Increment it when you change your policy to force re-consent
- **Policy URL**: URL to your privacy policy page (shown as a link in the banner)
- **Respect Do Not Track**: if enabled, automatically rejects cookies for visitors with DNT enabled in their browser

### Banner section

- **Layout**: `bar` (full-width bar), `card` (discreet corner card), or `modal` (blocking centered modal)
- **Position**: `bottom` or `top`
- **Theme**: `light`, `dark`, or `auto` (follows prefers-color-scheme)
- **Accent color**: customisable accent colour via color picker (default `#3b82f6`)
- **Show floating button**: shows the persistent floating button at the bottom-left to reopen preferences

### Categories section

Enable or disable individually the 3 optional categories. The _Strictly necessary_ category is always active.

- **Functional enabled**: personalisation cookies, user preferences
- **Analytics enabled**: Google Analytics 4, Matomo, audience measurement
- **Marketing enabled**: ad tracking, retargeting

## Google Consent Mode v2

The plugin automatically prints the `gtag('consent', 'default', ...)` block with priority 1 in the storefront head, with the 7 signals required since March 2024: `ad_storage`, `ad_user_data`, `ad_personalization`, `analytics_storage`, `functionality_storage`, `personalization_storage`, `security_storage`.

### Consent Mode section

- **GTM Container ID**: your GTM ID (`GTM-XXXXXXX`). If set, the plugin automatically loads GTM **after** the default block. Leave empty to skip GTM loading
- **GA4 Measurement ID**: your GA4 ID (`G-XXXXXXXXXX`). If set and GTM is empty, the plugin loads GA4 standalone. Leave empty if you load GA4 via GTM
- **URL passthrough**: preserves URL parameters for Ads conversions when consent is refused (recommended)
- **Ads data redaction**: anonymises ads data when consent is refused (recommended)
- **Wait for update (ms)**: delay before the first GA4/Ads ping, giving the visitor time to respond to the banner. Default `500` ms

**Execution order in the head:** 1) `gtag consent default` block with all signals set to `denied` — 2) GTM loader if configured — 3) GA4 loader if configured (and GTM empty) — 4) banner loads and signals updated via `gtag consent update` on visitor click.

### Categories to signals mapping

When the visitor clicks a button, selected categories are automatically mapped to Consent Mode v2 signals:

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

## EEA detection and eeaOnly mode

The plugin automatically detects the visitor's country to determine GDPR applicability (31 EU/EEA countries + United Kingdom + Switzerland).

### EEA section

- **EEA only mode**: if enabled, the banner is shown only to visitors detected in the EEA. Other visitors receive implicit consent and see nothing
- **Cloudflare support**: if enabled (true by default), reads the `CF-IPCountry` and `CF-Connecting-IP` headers added by Cloudflare in priority

**With Cloudflare:** detection is instant and reliable, the `CF-IPCountry` header is added free on every request. **Without Cloudflare:** fallback to `Accept-Language` to guess country from browser locale (less reliable but functional).

## Tracker audit

From the admin module (**Marketing → DataFirefly Cookie Consent → Audit**), launch an audit of your URL to detect actually present trackers and obtain a 0-100 compliance score.

### How to launch an audit

1. Go to **Marketing → DataFirefly Cookie Consent → Audit**
2. Enter the URL to audit (defaults to your current shop URL)
3. Click **Launch audit**
4. The result is displayed in a few seconds: visual score (conic ring), detected trackers, risky plugins, issues classified critical/warning/info

### What is detected

- **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, and more
- **11 risky Shopware plugins**: database query to detect server plugins known for setting non-compliant cookies

### Score interpretation

- **90-100**: excellent, optimal compliance
- **70-89**: good, a few minor adjustments to make
- **50-69**: medium, critical issues to address
- **0-49**: non-compliant, urgent action required

## Audit log and exports

Every consent event (accept_all, reject_all, custom, withdraw) is logged in the `dfcc_consent_log` table with millisecond timestamp, sales channel, language, policy version, snapshot of categories and Consent Mode v2 signals, double-protected IP and user agent.

### Visitor IP protection

Unique double protection:

- **SHA-256 hash** with a 64-character random salt generated at install and never exposed. Mathematically non-invertible.
- **Truncated version** in parallel: IPv4 → last octet zeroed (class C network), IPv6 → 64-bit prefix. Allows geographic analysis without re-identification.

### Consulting the log

1. Go to **Marketing → DataFirefly Cookie Consent → Log**
2. Filter by event type and date range if needed
3. The table paginates 50 entries per page

### Exporting for CNIL/DPA evidence

From the Log page, click **Export CSV** or **Export JSON**: the downloaded file contains all entries matching the active filters.

- **CSV**: BOM UTF-8 + semicolon separator (directly openable in French/Italian Excel)
- **JSON**: pretty (indented) with preserved unicode

### Log section

- **Retention days**: retention duration in days (1825 by default = 5 years, CNIL recommendation)
- A Shopware scheduled task automatically purges entries older than this every night

## Public JavaScript API

The plugin exposes a global `window.dfcc` API usable from any JavaScript code on your site.

```
// Open the banner and preferences modal
window.dfcc.open();

// Accept / reject all via code
window.dfcc.acceptAll();
window.dfcc.rejectAll();

// Withdraw consent (clears cookie + localStorage)
window.dfcc.withdraw();

// Get the current state
const cats = window.dfcc.getConsent();
// → { necessary: true, functional: false, analytics: true, marketing: false }
// or null if no consent yet given

// Check consent for a category
if (window.dfcc.hasConsent('analytics')) {
    // load your analytics script
}

// Diagnose storage state (debug)
console.log(window.dfcc.debug());
// → { cookieRaw, localStorageRaw, parsed, policyVersion, protocol, domain }

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

## DOM events

The plugin emits two custom events on `window`:

```
// Emitted as soon as the plugin is initialised on the page
window.addEventListener('dfcc:ready', (event) => {
    console.log('DFCC ready', event.detail.config);
});

// Emitted on every consent change (accept, reject, custom, withdraw)
window.addEventListener('dfcc:consent', (event) => {
    const { categories, eventType, consentMode } = event.detail;
    console.log('Consent changed:', eventType, categories);

    // Load a third-party script if marketing is accepted
    if (categories.marketing) {
        loadMyMarketingScript();
    }
});
```

## Multi-channel (sales channels)

All configuration is scopable per sales channel. To configure a specific channel differently:

1. Go to **Extensions → My Extensions → DataFirefly Cookie Consent → Configure**
2. At the top of the page, select the sales channel to configure
3. Modify the options: only modified options in this view override the default config

## Advanced customisation

### Banner wording

The banner text uses Shopware's standard storefront snippets. To customise a text, create your own snippet plugin and override the `dfcc.banner.*` and `dfcc.modal.*` keys:

```
<!-- custom-snippets/storefront.en-GB.json -->
{
    "dfcc": {
        "banner": {
            "title": "Your custom title",
            "body": "Your custom description."
        }
    }
}
```

### CSS styling

All banner elements use CSS classes prefixed with `.dfcc-` (e.g. `.dfcc-banner`, `.dfcc-modal`, `.dfcc-button--primary`). Override them from your theme or via the _Custom Code Manager DataFirefly_ plugin.

## Troubleshooting

### The banner does not appear

- Check that **Enabled** is ticked in the plugin config
- Check that **EEA only** mode is not enabled while you test from outside the EEA
- Check in DevTools console: `window.dfcc` must be defined. If not, the JS is not loaded → re-run `bin/console theme:compile`
- Clear the domain cookies in DevTools → Application → Cookies → Clear all, then reload

### Banner reappears on every page (bug in v1.0.0, fixed in v1.0.1)

1. Update to v1.0.1 if you haven't already
2. Run `window.dfcc.debug()` in the console to diagnose
3. If `cookieRaw` is empty but `localStorageRaw` is filled: your browser is blocking the cookie write (check HTTPS protocol and Secure/SameSite flags)
4. If both are empty but a consent was clicked: open a support ticket with the `debug()` result

### Google Ads conversions not feeding back

- Check that **GTM Container ID** or **GA4 Measurement ID** is set
- Check in DevTools → Network: the `gtag consent default` block must run **before** GTM/GA4 loads
- Enable **url_passthrough** and **ads_data_redaction** to preserve conversions from visitors who refused
- Check in GA4 → Admin → Data collection → Consent Mode that parameters are recognised

### CSV exports open badly in Excel

The file is generated with BOM UTF-8 and semicolon separator (French Excel standard). If your Excel expects a comma (English versions), use JSON export instead, or import via **Data → From CSV file** and specify the separator.

## Uninstallation

To deactivate temporarily:

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

Data remains in the database, Shopware's native banner takes over.

To uninstall completely:

```
bin/console plugin:uninstall --keep-user-data DataFireflyCookieConsent
# or to also delete the dfcc_consent_log table and config:
bin/console plugin:uninstall DataFireflyCookieConsent
```

**Warning:** without the `--keep-user-data` flag, the audit log (dfcc_consent_log) is lost. If you plan to reinstall later, always use `--keep-user-data`.

## Changelog

### 1.0.1 — May 23, 2026 (persistence patch)

- Complete rewrite of the client-side storage layer
- Direct cookie write with combined Max-Age and Expires
- Secure flag added only on HTTPS
- Automatic localStorage fallback if cookie write fails
- Write→read self-check with console log on desync
- New `window.dfcc.debug()` method

### 1.0.0 — May 23, 2026 (initial release)

- Shopware 6.6 and 6.7 compatibility
- v3 banner with 3 layouts, 2 positions, 3 themes
- Native Google Consent Mode v2 with 7 signals
- Real tracker audit (23 trackers + 11 risky plugins)
- Audit log with double-protected IP (SHA-256 + truncate)
- Smart EEA detection (31 countries + UK + CH, Cloudflare support)
- Vue 3 Admin module (mt-*): dashboard, audit, log
- CSV and JSON exports
- Storefront and admin snippets for 5 languages