Publiczna dokumentacja web komponentów consent-dialog, consent-guard, consent-missing i consent-validator.
Główny komponent interfejsu zgody PrivacyKit oraz logiki orkiestracji.
| Atrybut | Typ | Domyślna / Wymagana | Opis |
|---|---|---|---|
| variant | standard | panel | modern | modest | standard | Wariant wizualny dialogu. |
| theme | standard | dark | teal | slate | light | vibrant | high-contrast | standard | Motyw wizualny dialogu. |
| expires-days | number | 180 | Czas życia cookie w dniach. |
| version | number | 0 | Wersja schematu zgód używana do decyzji o ponownym pytaniu. |
| google-consent-mode | boolean | unset | Emituje sygnały zgody Google Consent Mode v2 na podstawie wyborów zgody odwiedzającego w PrivacyKit. |
| locale | da | de | en | es | fi | fr | it | nl | no | pl | sv | według przeglądarki | Wymusza konkretne ustawienia językowe. |
| hide-summary-part-2 | boolean | unset | Ukrywa sekcję podsumowania część 2 (dialog-summary-part-2) w oknie dialogowym. |
| hide-necessary | boolean | unset | Ukrywa kategorię Niezbędne. |
| hide-preferences | boolean | unset | Ukrywa kategorię Preferencje. |
| hide-analytics | boolean | unset | Ukrywa kategorię Analityka. |
| hide-marketing | boolean | unset | Ukrywa kategorię Marketing. |
| hide-readmore | boolean | unset | Ukrywa rozwijaną sekcję "Czytaj więcej". |
| hide-privacykit-badge | boolean | unset | Ukrywa odznakę PrivacyKit wyświetlaną na dole treści okna zgody. |
| hide-privacy-policy-link | boolean | unset | Ukrywa domyślny link do polityki prywatności całkowicie. Użyj `privacy-policy-url`, aby zachować widoczny link i przekierować użytkowników do własnej strony polityki prywatności. |
| privacy-policy-url | string | unset | URL, do którego użytkownicy są przekierowywani po kliknięciu linku do polityki prywatności. Po ustawieniu link otwiera ten URL zamiast wbudowanego okna dialogowego polityki prywatności. |
| demo | boolean | unset | Tryb demo: wyłącza auto-open i ogranicza niektóre funkcje. Nie spełnia wymogów RODO i nie może być używany w produkcji. |
| dismissible | boolean | false | Kontroluje, czy dialog można zamknąć kliknięciem tła/ESC, gdy użytkownik jeszcze nie podjął decyzji. |
| show-fab | boolean | false | Włącza przycisk preferencji zgody. Nie ma widocznego efektu, dopóki nie istnieje plik cookie zgody. |
| fab-position | left | right | left | Przypina przycisk do lewego dolnego lub prawego dolnego rogu widoku. |
| dialog-position | left | right | left | Określa, po której stronie ekranu pojawia się okno dialogowe. Dotyczy tylko wariantów modern i modest — standard i panel są zawsze wyśrodkowane. |
Przykład
<consent-dialog theme="panel" variant="dark" expires-days="90"
version="1" locale="pl" hide-marketing hide-privacy-policy-link dismissible>
</consent-dialog>Design tokens udostępniają stabilny zestaw zmiennych CSS, które pozwalają dostosować kolory, odstępy, typografię i inne aspekty wyglądu bez ingerencji w implementację komponentu. Wbudowane motywy są oparte na tym samym systemie tokenów, dzięki czemu możesz nadpisywać pojedyncze style lub stworzyć całkowicie niestandardowy wygląd.
| Design tokens | Opis |
|---|---|
| --pk-transparency | Przezroczystość powierzchni dialogu oraz zagnieżdżonych kart/akordeonów, podana w procentach. 0% (domyślnie) oznacza pełną kryjącą barwę; wartość jest ograniczana do maksymalnie 50%. |
| --pk-bg-color | Tło powierzchni całej powłoki okna dialogowego. Łączone z --pk-transparency w celu uzyskania ostatecznego koloru. |
| --pk-paper-color | Kolor papieru dla kart, akordeonów i paneli wewnątrz okna dialogowego. Również łączony z --pk-transparency. |
| --pk-text-color | Podstawowy kolor tekstu dla nagłówków i treści. |
| --pk-text-color-on-primary | Kolor tekstu używany na elementach wypełnionych kolorem podstawowym, takich jak pełne przyciski. |
| --pk-primary-color | Główny akcent dla CTA, obramowań focus i linków. |
| --pk-secondary-color | Drugi akcent używany głównie w przełącznikach. |
| --pk-focus-ring-color | Kolor obrysu fokusu (outline) dla stanów fokusu klawiaturą. |
| --pk-font-family | Rodzina fontów dla całego tekstu; w razie potrzeby wraca do fontu body. |
| --pk-spacing-unit | Jednostka odstępów sterująca paddingami i przerwami między sekcjami. |
| --pk-control-border-color | Kolor obramowania kontrolek wewnątrz okna dialogowego — kart, akordeonów, przycisków i podobnych elementów. |
| --pk-control-border-width | Grubość obramowania kontrolek wewnątrz okna dialogowego — kart, akordeonów, przycisków i podobnych elementów. |
| --pk-control-border-radius | Promień zaokrągleń dla przycisków, pól i interaktywnych kontrolek. |
| --pk-dialog-border-color | Kolor obramowania samego okna dialogowego — kontur zewnętrznego panelu oraz linie podziału w nagłówku/stopce. |
| --pk-dialog-border-width | Grubość obramowania samego okna dialogowego — kontur zewnętrznego panelu oraz linie podziału w nagłówku/stopce. |
| --pk-dialog-border-radius | Promień zaokrągleń zewnętrznego kontenera dialogu zgody. |
| --pk-dialog-max-height | Maksymalna wysokość okna dialogowego zgody; gdy treść przekroczy ten limit, korpus okna będzie przewijany. |
| --pk-dialog-shadow | Cień pola dialogu wyrażenia zgody. |
Przykład
<consent-dialog theme="light" style="
--pk-bg-color: #faf7f2;
--pk-paper-color: #f7eede;
--pk-primary-color: #b08968;
--pk-font-family: 'Segoe UI', Tahoma, sans-serif;
--pk-control-border-radius: 10px;
--pk-dialog-border-radius: 20px;
--pk-dialog-max-height: 50vh;
--pk-dialog-shadow: 10px 20px rgba(0, 0, 0, 0.5);
">
</consent-dialog>Wstrzykuj własną treść do konkretnych części komponentu za pomocą nazwanych slotów HTML — zyskujesz pełną kontrolę nad treścią i stylowaniem bez modyfikowania samego komponentu.
| Nazwa slotu | Opis |
|---|---|
| dialog-logo-top | Opcjonalne logo lub obraz marki wyświetlany w nagłówku okna dialogowego zgody. |
| dialog-logo-right | Opcjonalne logo lub obraz marki wyświetlany w prawym górnym rogu okna dialogowego zgody. |
| dialog-title | Zastępuje tytuł w nagłówku okna dialogowego. |
| dialog-summary-part-1 | Wstawia własną treść w pierwszym akapicie wprowadzającym pod tytułem okna dialogowego. |
| dialog-summary-part-2 | Wstawia własną treść w drugim akapicie wprowadzającym, który opisuje opcje zgody. |
| necessary-content | Zastępuje domyślny opis kategorii Niezbędne. |
| preferences-content | Własna treść w akordeonie kategorii Preferencje. |
| analytics-content | Własna treść w akordeonie kategorii Analityka. |
| marketing-content | Własna treść w akordeonie kategorii Marketing. |
| read-more-title | Ustawia nagłówek sekcji "Czytaj więcej" na dole. |
| read-more-content | Treść pokazywana po rozwinięciu sekcji "Czytaj więcej". |
| privacy-policy-content | Zastępuje domyślną treść polityki prywatności. Używaj wyłącznie tekstu zatwierdzonego przez własnych doradców prawnych, ponieważ PrivacyKit nie może potwierdzić GDPR compliance po wprowadzeniu zmian. |
Przykład
<consent-dialog theme="standard" variant="standard" locale="pl" version="1">
<img slot="dialog-logo-top" width="100px" src="/logo.png" alt="Logo firmy" />
<div slot="dialog-title" class="twoja-klasa">
<h2>Używamy plików cookie</h2>
</div>
<span slot="marketing-content">
<b>Obecnie nie zbieramy cookies do celów marketingowych.</b>
</span>
</consent-dialog>
PrivacyKit automatycznie stosuje odpowiedni profil prywatności na podstawie wykrytej lokalizacji odwiedzającego. Nie jest wymagana dodatkowa konfiguracja.
Odwiedzającym znajdującym się w Europie prezentowany jest model zgody GDPR/ePrivacy. Analityka, marketing i inne nieistotne technologie pozostają zablokowane, dopóki odwiedzający nie wyrazi zgody.
Odwiedzającym spoza Europy prezentowany jest model prywatności CPRA. Zgoda jest udzielana automatycznie, co pozwala witrynie działać bez początkowego okna dialogowego zgody. Odwiedzający mogą w dowolnym momencie otworzyć okno dialogowe PrivacyKit, aby przejrzeć lub wycofać swoje wybory dotyczące prywatności. Jeśli zgoda zostanie wycofana, PrivacyKit prosi o odświeżenie strony, aby zablokowane technologie nie były już uruchamiane.
PrivacyKit automatycznie określa, czy odwiedzający znajduje się w Europie. Nie jest wymagana żadna konfiguracja.
<consent-dialog> zawiera wbudowane tłumaczenia na angielski, norweski, niemiecki, polski, hiszpański, francuski, włoski, niderlandzki, szwedzki, duński i fiński — bez konieczności wczytywania czy utrzymywania własnych plików tłumaczeń.
Domyślnie okno dialogowe odczytuje język przeglądarki odwiedzającego i automatycznie wyświetla odpowiednie tłumaczenie. Jeśli przeglądarka jest ustawiona na język, którego PrivacyKit nie obsługuje, stosowany jest domyślnie angielski.
Aby wymusić konkretny język niezależnie od ustawień przeglądarki odwiedzającego, ustaw atrybut locale — pełną listę obsługiwanych kodów znajdziesz w tabeli powyżej.
<consent-dialog locale="pl"></consent-dialog>Gdy atrybut google-consent-mode jest włączony, PrivacyKit odczytuje wybory zgody odwiedzającego i przekazuje je do Google Tag Managera lub gtag za pomocą protokołu Google Consent Mode v2. Dzieje się to automatycznie przy ładowaniu strony oraz za każdym razem, gdy odwiedzający zmienia swoją zgodę. Nie jest wymagana żadna dodatkowa konfiguracja poza dodaniem atrybutu.
PrivacyKit mapuje swoje trzy kategorie zgody na siedem pól Google Consent Mode v2:
| Pole GCM v2 | Zmapowane z | Wartość |
|---|---|---|
| analytics_storage | Analityka | granted / denied |
| ad_storage | Marketing | granted / denied |
| ad_user_data | Marketing | granted / denied |
| ad_personalization | Marketing | granted / denied |
| functionality_storage | Preferencje | granted / denied |
| personalization_storage | Preferencje | granted / denied |
| security_storage | — | Always granted |
security_storage jest zawsze granted, ponieważ obejmuje przechowywanie danych w przeglądarce niezbędne ze względów bezpieczeństwa i nie podlega opcjonalnej zgodzie na śledzenie.
Podczas ładowania strony PrivacyKit dba o to, by istniały window.dataLayer i funkcja gtag, korzystając ze standardowego fragmentu kodu Google i zachowując te, które już są na stronie. Umieszcza w kolejce wartość domyślną z odmową wszystkich zgód, następnie bieżącą zgodę odwiedzającego, a przy każdej zmianie zgody dodaje aktualizację do kolejki:
gtag('consent', 'update', {
analytics_storage: 'granted' | 'denied',
ad_storage: 'granted' | 'denied',
ad_user_data: 'granted' | 'denied',
ad_personalization: 'granted' | 'denied',
functionality_storage: 'granted' | 'denied',
personalization_storage: 'granted' | 'denied',
security_storage: 'granted'
});dataLayer to kolejka w pamięci strony; nic nie jest zapisywane. Google Tag Manager i gtag.js przetwarzają polecenia z kolejki po kolei podczas ładowania, dzięki czemu stan zgody obowiązuje, zanim uruchomi się jakikolwiek tag Google, także wtedy, gdy Google ładuje się później.
Jeśli strona ma własny fragment kodu Google, musi zachować istniejący dataLayer (window.dataLayer = window.dataLayer || [], tak jak robią to fragmenty Google).
Wskazówka dotycząca debugowania: PrivacyKit rejestruje swoją aktywność Google Consent Mode v2 w konsoli przeglądarki, dzięki czemu możesz zweryfikować działanie bezpośrednio w DevTools:
[PrivacyKit] Google Consent Mode v2 enabled.
Wyświetlany raz podczas ładowania strony, gdy ustawiono google-consent-mode. Jednocześnie do kolejki trafia wartość domyślna z odmową wszystkich zgód.
[PrivacyKit] Google Consent Mode v2 update queued.
Aktualizacja zgody została dodana do kolejki dataLayer – podczas ładowania strony i przy każdej zmianie zgody. Google stosuje ją, gdy ładują się jego tagi.
openConsentDialog(): void
onConsentDialogClosed(callback: () => void): () => void
openPrivacyPolicyDialog(): voidWarunkowo renderuje zawartość, gdy przekazane wyrażenie zgody zwróci true.
| Atrybut | Typ | Domyślna / Wymagana | Opis |
|---|---|---|---|
| consent | string | unset | Wyrażenie zgody, które musi zostać spełnione, zanim treść zostanie wyrenderowana. |
| source | string | unset | Skąd odczytywana jest zgoda. Gdy nie jest ustawiony, guard używa zgody z okna dialogowego zgód PrivacyKit. "google-consent-mode" odczytuje zgodę zebraną przez Twój obecny baner zgód za pomocą Google Consent Mode v2. Nieznane wartości pozostawiają guard zablokowany. |
| Wyrażenie | Wymagana zgoda | Opis |
|---|---|---|
| Wszystkie kategorie | Jeśli atrybut consent zostanie pominięty, wszystkie kategorie muszą być zaakceptowane, aby guard się aktywował. | |
| necessary | Żadna | Zapobiega fałszywym alarmom w Consent Validator dla niezbędnych zasobów, które nie są automatycznie rozpoznawane przez PrivacyKit. |
| preferences | Preferencje | |
| analytics | Analityka | |
| marketing | Marketing | |
| preferences+analytics | Preferencje I Analityka | Dla skryptów, które wymagają obu rodzajów zgody, np. śledzenie HubSpot. |
| preferences|analytics | Preferencje LUB Analityka | Dla kontenerów, które sprawdzają zgodę dla każdego tagu, np. Google Tag Manager. |
| preferences+marketing | Preferencje I Marketing | Dla skryptów, które wymagają obu rodzajów zgody, np. śledzenie HubSpot. |
| preferences|marketing | Preferencje LUB Marketing | Dla kontenerów, które sprawdzają zgodę dla każdego tagu, np. Google Tag Manager. |
| analytics+marketing | Analityka I Marketing | Dla skryptów, które wymagają obu rodzajów zgody, np. śledzenie HubSpot. |
| analytics|marketing | Analityka LUB Marketing | Dla kontenerów, które sprawdzają zgodę dla każdego tagu, np. Google Tag Manager. |
Przykład 1 – Chroń skrypty
<consent-guard consent="analytics">
<script type="text/plain" data-src="https://static.hotjar.com/c/hotjar-XXXXXXX.js?sv=6" data-async></script>
</consent-guard>
Przykład 2 – Chroń osadzone treści
<consent-guard consent="analytics+marketing">
<iframe
title="YouTube video"
data-src="https://www.youtube.com/embed/abc123"
width="560"
height="315"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen>
</iframe>
</consent-guard>
Ważne: Zwróć uwagę, że zarządzane zasoby w przykładach używają data-src zamiast src oraz type="text/plain" jest używane dla skryptów. PrivacyKit aktywuje zarządzaną zawartość dopiero po udzieleniu zgody — w przeciwnym razie zasoby mogą ładować się od razu i wyglądać jak zahardkodowane w Consent Validator.
Guardy mogą egzekwować zgodę zebraną przez Twój obecny baner. Dodaj source="google-consent-mode" do <consent-guard>, a guard odczyta zgodę z Twojego banera zamiast z okna dialogowego zgód PrivacyKit. Skrypty i osadzone treści w guardzie ładują się dopiero po wyrażeniu zgody przez odwiedzającego.
window.dataLayer, przy każdym załadowaniu strony i przy każdej zmianie wyboru.Użyj zgody z obecnego banera
<!-- Twój obecny baner zgód z włączonym Google Consent Mode v2. -->
<script src="https://cdn.your-consent-banner.com/banner.js"></script>
<!-- PrivacyKit -->
<script type="module" src="https://cdn.privacykit.eu/v1/privacykit.esm.js"></script>
<!-- Hotjar ładuje się dopiero, gdy odwiedzający zaakceptuje analitykę w Twoim banerze -->
<consent-guard consent="analytics" source="google-consent-mode">
<script type="text/plain" data-src="https://static.hotjar.com/c/hotjar-XXXXXXX.js?sv=6" data-async></script>
</consent-guard>
<!-- Osadzone treści wymagające zgody marketingowej -->
<consent-guard consent="marketing" source="google-consent-mode">
<iframe title="YouTube video" data-src="https://www.youtube.com/embed/abc123" width="560" height="315"></iframe>
</consent-guard>
PrivacyKit możesz używać z Google Tag Managerem na dwa sposoby: w trybie ścisłym, w którym Tag Manager czeka na zgodę, albo elastycznym, w którym Tag Manager ładuje się od razu, a jego własne ustawienia zgód decydują, które tagi się uruchamiają. W obu przypadkach dodaj google-consent-mode do <consent-dialog>, aby tagi w Tag Managerze wiedziały, co wybrał odwiedzający.
Nic z Tag Managera się nie ładuje i nic nie jest wysyłane do Google, dopóki odwiedzający nie wyrazi zgody. Niemiecki sąd (VG Hannover, 2025) orzekł, że ładowanie Google Tag Managera wymaga zgody, a tryb ścisły stosuje tę interpretację. Ustaw zgodę guarda zgodnie z tym, co uruchamia kontener: analytics lub marketing, jeśli uruchamia jeden rodzaj tagów, albo analytics|marketing, jeśli uruchamia tagi obu rodzajów, aby ładował się, gdy tylko odwiedzający zaakceptuje którykolwiek z nich. Od tego momentu Tag Manager zarządza zgodą dla każdego tagu.
<consent-dialog google-consent-mode></consent-dialog>
<consent-guard consent="analytics|marketing">
<script type="text/plain" data-src="https://www.googletagmanager.com/gtm.js?id=GTM-XXXXXXX" data-async></script>
</consent-guard>
Załaduj Tag Managera jak zwykle. Tagi Google stosują się do sygnałów Consent Mode z okna dialogowego. Pozostałe tagi w kontenerze, np. Meta lub LinkedIn, wymagają ustawień zgód w Tag Managerze. Consent Validator pokazuje Tag Managera jako niechroniony przez guarda. To zamierzone: Validator zgłasza wszystko, co nie znajduje się w guardzie.
Tryb elastyczny to także konfiguracja dla stron, które celowo korzystają z Consent Mode Advanced. Przy odmowie zgody tagi Google nadal wysyłają dane bez plików cookie, takie jak adres strony i informacje o urządzeniu, aby Google mógł modelować konwersje. PrivacyKit obsługuje tę konfigurację. To, czy jest ona odpowiednia dla Twojej strony, zależy od Ciebie i Twojego doradcy prawnego.
Renderuj treść zastępczą, gdy powiązany consent-guard blokuje główne doświadczenie.
| Atrybut | Typ | Domyślna / Wymagana | Opis |
|---|---|---|---|
| for | string | wymagana | Id powiązanego elementu <consent-guard>. |
Przykład
<consent-guard id="analytics-guard" consent="analytics">
<script type="text/plain" data-src="https://example.com/analytics.js"></script>
</consent-guard>
<consent-missing for="analytics-guard">
Akceptuj pliki cookie analityczne, aby kontynuować.
</consent-missing>
Consent Validator monitoruje wychodzące żądania i weryfikuje pokrycie strażników zgody na Twojej witrynie, wykrywając niezarządzane trackery i regresje wywołane zmianami w witrynie. Domyślnie nieaktywny pozostaje niewidoczny dla odwiedzających i można go bezpiecznie wdrożyć na produkcji.
| Atrybut | Typ | Domyślna / Wymagana | Opis |
|---|---|---|---|
| debug | boolean | false | Włącza panel Consent Validator przy ładowaniu strony. Tylko dla środowisk programistycznych. |
| delay | number | 5000 | Okno obserwacji sieci (w milisekundach) przed rozpoczęciem przez Consent Validator walidacji użycia punktów końcowych i pokrycia strażników zgody. |
| ignore-first-party-subdomains | boolean | true | Gdy ma wartość true, żądania do subdomen bieżącej domeny są po cichu ignorowane. |
| fab-position | left | right | right | Określa, do której strony viewportu przypięty jest przycisk FAB Consent Validator. |
Przykład
<consent-validator debug delay="5000" ignore-first-party-subdomains="true" fab-position="left"></consent-validator>
Consent Validator pozostaje ukryty dla odwiedzających, nawet gdy jest zawarty w pakiecie produkcyjnym. Zalecany sposób aktywacji na działającej witrynie to dodanie ?privacykit=validate do adresu URL — aktywuje walidator tylko dla tej sesji przeglądarki, nie wpływając na doświadczenie odwiedzających.
Przełącz programowo:
window.PrivacyKit?.toggleConsentValidator();
Unikaj migotania zanim web komponenty się załadują. Bez tego fragmentu HTML w slotach lub za guardami może na chwilę mignąć, gdy:
consent-dialog może mignąć, jeśli slottowane elementy wyrenderują się zanim komponent zostanie zdefiniowany.consent-guard może mignąć na chwilę, jeśli jest używany do warunkowego HTML i treść wyrenderuje się zanim komponent się aktywuje.consent-missing może mignąć na chwilę, jeśli jest używany jako fallback i wyrenderuje się zanim komponent się aktywuje.Dodaj style w swoim light DOM, aby zapobiec migotaniu.
consent-dialog:not(:defined) [slot] {
display: none;
}
consent-guard:not([active]) {
display: none;
}
consent-missing:not([active]) {
display: none;
}