# 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,…

- Strona: <https://www.datafirefly.com/pl/documentation/df-cookie-consent/>
- Język: pl
- Zaktualizowano: 2026-07-29
- Inne języki: [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), [de](https://www.datafirefly.com/de/documentation/df-cookie-consent/index.md), [it](https://www.datafirefly.com/it/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)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

## 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.

**W jednym zdaniu:** trzy wymogi regulacyjne pokryte jednym pluginem: Consent Mode v2 (marzec 2024), równoważność Akceptuj/Odrzuć i dowód zgody (RODO).

## 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
```

**Warto wiedzieć:** JavaScript pluginu jest dostarczany prekompilowany w `Resources/app/storefront/dist/`. **Nie musisz** uruchamiać `build-storefront.sh`, aby baner działał.

## 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

**Kolejność wykonania w sekcji head:** 1) blok `gtag consent default` ze wszystkimi sygnałami na `denied`, 2) loader GTM, jeśli skonfigurowany, 3) loader GA4, jeśli skonfigurowany (i GTM puste), 4) załadowanie banera i aktualizacja sygnałów przez `gtag consent update` zaraz po kliknięciu odwiedzającego.

### 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

**Z Cloudflare:** wykrywanie jest natychmiastowe i wiarygodne, nagłówek `CF-IPCountry` jest dodawany bezpłatnie przy każdym żądaniu. **Bez Cloudflare:** fallback na `Accept-Language`, aby odgadnąć kraj z ustawień językowych przeglądarki (mniej wiarygodne, ale działające).

## 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
```

**Uwaga:** bez flagi `--keep-user-data` dziennik audytu (dfcc_consent_log) zostaje utracony. Jeśli planujesz późniejszą ponowną instalację, zawsze używaj `--keep-user-data`.

## 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