DataFirefly Cookie Consent dla Shopware 6: dokumentacja

Wprowadzenie

DataFirefly Cookie Consent to plugin Shopware 6, który w całości zastępuje natywny baner cookies nowoczesnym systemem zgodnym z RODO i wytycznymi organów nadzorczych, z natywnym Google Consent Mode v2, rzeczywistym audytem trackerów i kryptograficznie chronionym dziennikiem audytu jako dowodem zgody.

Wymagania i zgodność

• Shopware 6.6.x albo 6.7.x (ograniczenie composera ~6.6.0||~6.7.0)
• PHP 8.2 lub nowszy
• Instalacja self-hosted (plugin nie działa na Shopware Cloud SaaS)
• HTTPS zalecane w produkcji (flaga cookie Secure jest dodawana wyłącznie po HTTPS)
• Cloudflare zalecany dla optymalnego wykrywania EOG (CF-IPCountry), ale nieobowiązkowy

Instalacja

Instalacja przez przesłanie ZIP (zalecana)

1. Pobierz plik DataFireflyCookieConsent-1.0.1.zip ze swojego konta klienta DataFirefly
2. W administracji Shopware wejdź w Rozszerzenia → Moje rozszerzenia → Prześlij rozszerzenie
3. Wybierz plik ZIP i zatwierdź
4. Kliknij Zainstaluj, a następnie Aktywuj
5. Wyczyść cache: bin/console cache:clear
6. Przekompiluj motyw: bin/console theme:compile

Instalacja przez Composer (CLI)

cd /var/www/shopware
# Unpack the ZIP into custom/plugins/
unzip DataFireflyCookieConsent-1.0.1.zip -d custom/plugins/

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

Konfiguracja ogólna

Cała konfiguracja odbywa się w Rozszerzenia → Moje rozszerzenia → DataFirefly Cookie Consent → ⋮ → Konfiguruj. Opcje można zawężać per sales channel (wybierz kanał u góry strony konfiguracji).

Sekcja Ogólne

• Enabled: włącza albo całkowicie wyłącza plugin (po wyłączeniu natywny baner Shopware przejmuje kontrolę)
• Policy version: wersja Twojej polityki prywatności (domyślnie 1.0). Zwiększ ją przy zmianie polityki, aby wymusić nową zgodę
• Policy URL: adres URL strony Twojej polityki prywatności (wyświetlany jako link w banerze)
• Respect Do Not Track: po włączeniu automatycznie odrzuca cookies dla odwiedzających z włączonym DNT w przeglądarce

Sekcja Baner

• Layout: bar (pasek pełnej szerokości), card (dyskretna karta w rogu) albo modal (blokujące okno na środku)
• Position: bottom albo top
• Theme: light, dark albo auto (podąża za prefers-color-scheme)
• Accent color: personalizowalny kolor akcentu przez color picker (domyślnie #3b82f6)
• Show floating button: wyświetla trwały pływający przycisk w lewym dolnym rogu do ponownego otwarcia preferencji

Sekcja Kategorie

Włącz albo wyłącz indywidualnie 3 kategorie opcjonalne. Kategoria Ściśle niezbędne jest zawsze aktywna.

• Functional enabled: cookies personalizacji, preferencje użytkownika
• Analytics enabled: Google Analytics 4, Matomo, pomiar oglądalności
• Marketing enabled: śledzenie reklamowe, retargeting

Google Consent Mode v2

Plugin automatycznie drukuje blok gtag('consent', 'default', ...) z priorytetem 1 w sekcji head storefrontu, z 7 sygnałami wymaganymi od marca 2024: ad_storage, ad_user_data, ad_personalization, analytics_storage, functionality_storage, personalization_storage, security_storage.

Sekcja Consent Mode

• GTM Container ID: Twoje ID GTM (GTM-XXXXXXX). Po uzupełnieniu plugin ładuje GTM automatycznie po bloku default. Zostaw puste, aby nie ładować GTM
• GA4 Measurement ID: Twoje ID GA4 (G-XXXXXXXXXX). Po uzupełnieniu i przy pustym GTM plugin ładuje GA4 samodzielnie. Zostaw puste, jeśli ładujesz GA4 przez GTM
• URL passthrough: zachowuje parametry URL dla konwersji Ads przy odmowie zgody (zalecane)
• Ads data redaction: anonimizuje dane reklamowe przy odmowie zgody (zalecane)
• Wait for update (ms): czas oczekiwania przed pierwszym pingiem GA4/Ads, aby odwiedzający zdążył odpowiedzieć na baner. Domyślnie 500 ms

Mapowanie kategorii na sygnały

Gdy odwiedzający klika przycisk, wybrane kategorie są automatycznie mapowane na sygnały Consent Mode v2:

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

Wykrywanie EOG i tryb eeaOnly

Plugin automatycznie wykrywa kraj odwiedzającego, aby ustalić, czy podlega RODO (31 krajów UE/EOG plus Wielka Brytania i Szwajcaria).

Sekcja EOG

• EEA only mode: po włączeniu baner wyświetla się wyłącznie odwiedzającym wykrytym jako znajdujący się w EOG. Pozostali otrzymują zgodę dorozumianą i nie widzą niczego
• Cloudflare support: po włączeniu (domyślnie true) czyta w pierwszej kolejności nagłówki CF-IPCountry i CF-Connecting-IP dodawane przez Cloudflare

Audyt trackerów

Z poziomu modułu administracji (Marketing → DataFirefly Cookie Consent → Audyt) uruchom audyt swojego adresu URL, aby wykryć realnie obecne trackery i uzyskać wynik zgodności od 0 do 100.

Jak uruchomić audyt

1. Wejdź w Marketing → DataFirefly Cookie Consent → Audyt
2. Uzupełnij adres URL do zaudytowania (domyślnie bieżący adres Twojego sklepu)
3. Kliknij Uruchom audyt
4. Wynik wyświetla się w kilka sekund: wizualny wynik (pierścień stożkowy), wykryte trackery, ryzykowne pluginy, problemy sklasyfikowane jako critical/warning/info

Co jest wykrywane

• 23 trackery 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, osadzenia YouTube, osadzenia Vimeo, Stripe Elements i inne
• 11 ryzykownych pluginów Shopware: odpytanie bazy w celu wykrycia pluginów serwerowych znanych z zapisywania niezgodnych cookies

Interpretacja wyniku

• 90-100: doskonale, optymalna zgodność
• 70-89: dobrze, kilka drobnych korekt do wykonania
• 50-69: średnio, są problemy critical do obsłużenia
• 0-49: niezgodne, wymagane pilne działanie

Dziennik audytu i eksporty

Każde zdarzenie zgody (accept_all, reject_all, custom, withdraw) jest zapisywane w tabeli dfcc_consent_log ze znacznikiem czasu co do milisekundy, sales channelem, językiem, wersją polityki, snapshotem kategorii i sygnałów Consent Mode v2, podwójnie chronionym IP i user agentem.

Ochrona IP odwiedzającego

Unikalna podwójna ochrona:

• Hash SHA-256 z losową solą o długości 64 znaków generowaną przy instalacji i nigdy nieujawnianą. Matematycznie nieodwracalny.
• Wersja skrócona równolegle: IPv4 → ostatni oktet wyzerowany (sieć klasy C), IPv6 → prefiks 64-bitowy. Umożliwia analizę geograficzną bez ponownej identyfikacji.

Przeglądanie dziennika

1. Wejdź w Marketing → DataFirefly Cookie Consent → Dziennik
2. W razie potrzeby filtruj po typie zdarzenia i zakresie dat
3. Tabela stronicuje po 50 wpisów na stronę

Eksport jako dowód dla organu nadzorczego

Na stronie Dziennik kliknij Eksport CSV albo Eksport JSON: pobrany plik zawiera wszystkie wpisy odpowiadające aktywnym filtrom.

• CSV: BOM UTF-8 plus separator średnik (otwierany bezpośrednio w Excelu w wersji francuskiej/włoskiej)
• JSON: pretty (wcięty), z zachowanym unicode

Sekcja Dziennik

• Retention days: czas przechowywania w dniach (domyślnie 1825, czyli 5 lat, zgodnie z zaleceniami)
• Zadanie cykliczne Shopware co noc automatycznie czyści starsze wpisy

Publiczne API JavaScript

Plugin udostępnia globalne API window.dfcc, którego możesz użyć z dowolnego kodu JavaScript swojej witryny.

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

// Accept / reject everything programmatically
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 has been given yet

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

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

// Plugin version
console.log(window.dfcc.version);
// -> "1.0.1"

Zdarzenia DOM

Plugin emituje dwa niestandardowe zdarzenia na 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 the marketing category is accepted
    if (categories.marketing) {
        loadMyMarketingScript();
    }
});

Wiele kanałów (sales channels)

Cała konfiguracja może być zawężona per sales channel. Aby skonfigurować konkretny kanał inaczej niż pozostałe:

1. Wejdź w Rozszerzenia → Moje rozszerzenia → DataFirefly Cookie Consent → Konfiguruj
2. U góry strony wybierz sales channel do skonfigurowania
3. Zmień opcje: wyłącznie opcje zmienione w tym widoku nadpisują konfigurację domyślną

Zaawansowana personalizacja

Treść banera

Tekst banera korzysta ze standardowych snippetów storefrontu Shopware. Aby spersonalizować tekst, utwórz własny plugin snippetów i nadpisz klucze dfcc.banner.* i dfcc.modal.*:

<!-- custom-snippets/storefront.pl-PL.json -->
{
    "dfcc": {
        "banner": {
            "title": "Twoj wlasny tytul",
            "body": "Twoj wlasny opis."
        }
    }
}

Style CSS

Wszystkie elementy banera używają klas CSS z prefiksem .dfcc- (na przykład .dfcc-banner, .dfcc-modal, .dfcc-button--primary). Nadpisz je w swoim motywie albo przez plugin Custom Code Manager DataFirefly.

Rozwiązywanie problemów

Baner się nie wyświetla

• Sprawdź, czy Enabled jest zaznaczone w konfiguracji pluginu
• Sprawdź, czy tryb EEA only nie jest włączony, podczas gdy testujesz spoza EOG
• Sprawdź w konsoli DevTools: window.dfcc musi być zdefiniowane. Jeśli nie, JS nie jest załadowany → uruchom ponownie bin/console theme:compile
• Wyczyść cookies domeny w DevTools → Application → Cookies → Clear all, a następnie przeładuj

Baner wraca po każdej stronie (błąd v1.0.0 naprawiony w v1.0.1)

1. Zaktualizuj do v1.0.1, jeśli jeszcze tego nie zrobiono
2. Uruchom window.dfcc.debug() w konsoli w celu diagnozy
3. Jeśli cookieRaw jest puste, a localStorageRaw wypełnione: Twoja przeglądarka blokuje zapis cookie (sprawdź protokół HTTPS oraz flagi Secure/SameSite)
4. Jeśli oba są puste, mimo że zgoda została kliknięta: otwórz zgłoszenie do wsparcia z wynikiem debug()

Konwersje Google Ads nie są raportowane

• Sprawdź, czy GTM Container ID albo GA4 Measurement ID jest uzupełnione
• Sprawdź w DevTools → Network: blok gtag consent default musi wykonać się przed załadowaniem GTM/GA4
• Włącz url_passthrough i ads_data_redaction, aby zachować konwersje odwiedzających, którzy odmówili
• Sprawdź w GA4 → Administracja → Zbieranie danych → Consent Mode, czy parametry są rozpoznawane

Eksporty CSV źle otwierają się w Excelu

Plik jest generowany z BOM UTF-8 i separatorem średnik (standard Excela w wersji francuskiej). Jeśli Twój Excel oczekuje przecinka (wersje angielskie), użyj zamiast tego eksportu JSON albo zaimportuj przez Dane → Z pliku CSV i wskaż separator.

Odinstalowanie

Aby tymczasowo wyłączyć:

bin/console plugin:deactivate DataFireflyCookieConsent

Dane pozostają w bazie, natywny baner Shopware przejmuje kontrolę.

Aby odinstalować całkowicie:

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

Changelog

1.0.1, 23 maja 2026 (poprawka trwałości)

• Pełne przepisanie warstwy storage po stronie JavaScriptu
• Bezpośredni zapis cookie z połączonym Max-Age i Expires
• Flaga Secure dodawana wyłącznie przy HTTPS
• Automatyczny fallback na localStorage, gdy zapis cookie zawiedzie
• Autokontrola zapis-odczyt z logiem w konsoli przy rozsynchronizowaniu
• Nowa metoda window.dfcc.debug()

1.0.0, 23 maja 2026 (wydanie początkowe)

• Zgodność z Shopware 6.6 i 6.7
• Baner v3 z 3 układami, 2 pozycjami, 3 motywami
• Natywny Google Consent Mode v2 z 7 sygnałami
• Rzeczywisty audyt trackerów (23 trackery plus 11 ryzykownych pluginów)
• Dziennik audytu z podwójnie chronionym IP (SHA-256 plus skrócenie)
• Inteligentne wykrywanie EOG (31 krajów plus UK i CH, wsparcie Cloudflare)
• Moduł administracji Vue 3 (mt-*): pulpit, audyt, dziennik
• Eksporty CSV i JSON
• Snippety storefrontu i administracji w 5 językach