Komponenty webowe PrivacyKit

Publiczna dokumentacja web komponentów consent-dialog, consent-guard, consent-missing i compliance-monitor.

Spis treści

<consent-dialog>

Główny komponent interfejsu zgody PrivacyKit oraz logiki orkiestracji.

Atrybuty

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 użytkownika 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

HTML
<consent-dialog theme="panel" variant="dark" expires-days="90" 
  version="1" locale="pl" hide-marketing hide-privacy-policy-link dismissible>
</consent-dialog>

Lokalizacja

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

Automatyczne wykrywanie

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.

Nadpisywanie języka

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.

HTML
<consent-dialog locale="pl"></consent-dialog>

Design tokens

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>

Sloty treści

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

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

Pływający przycisk dialogu

Gdy show-fab jest ustawione na true, <consent-dialog> pokazuje pływający przycisk akcji (FAB), który pozwala użytkownikom ponownie otworzyć swoje wybory zgody po pierwszym zatwierdzeniu. Użyj fab-position, aby przypiąć go do lewego dolnego lub prawego dolnego rogu widoku.

Zasady widoczności

Ukryty do momentu przesłania początkowej zgody.
Ukryty, gdy okno dialogowe zgody lub okno polityki prywatności jest otwarte.
Ukryty, jeśli show-fab nie jest ustawione lub jest ustawione na false.

HTML
<consent-dialog show-fab fab-position="left">
</consent-dialog>

Google Consent Mode v2

Gdy atrybut google-consent-mode jest włączony, PrivacyKit odczytuje wybory zgody użytkownika 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 użytkownik zmienia swoją zgodę. Nie jest wymagana żadna dodatkowa konfiguracja poza dodaniem atrybutu.

Zalecana konfiguracja

Połączenie <consent-guard> wokół fragmentu kodu GTM z atrybutem google-consent-mode na dialogu to podejście oparte na egzekwowaniu: GTM w ogóle nie może się załadować przed udzieleniem zgody, a sygnały Google Consent Mode v2 są wysyłane natychmiast, gdy tylko to nastąpi. GTM to tylko kontener — może zawierać tagi analityczne, marketingowe lub oba rodzaje, w zależności od tego, co w nim skonfigurowano. Ustaw wyrażenie consent na <consent-guard> odpowiednio: marketing, jeśli GTM uruchamia wyłącznie tagi marketingowe/reklamowe, analytics, jeśli dotyczy wyłącznie analityki, lub analytics+marketing, jeśli uruchamia oba rodzaje.

HTML
<!-- Match the consent expression to what GTM actually fires: "analytics" or "marketing" -->
<consent-guard consent="analytics">
  <script type="text/plain" data-src="https://www.googletagmanager.com/gtm.js?id=GTM-XXXXXXX"></script>
</consent-guard>

<consent-dialog google-consent-mode>
</consent-dialog>

Mapowanie sygnałów zgody

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.

Jak wysyłane są sygnały

PrivacyKit sprawdza, czy dostępny jest window.gtag (załadowany Google Tag Manager lub gtag.js). Jeśli tak, wywołuje:

JavaScript
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'
});

Jeśli gtag nie jest dostępny, ale dostępny jest window.dataLayer, PrivacyKit wysyła aktualizację zgody bezpośrednio do dataLayer. Jeśli żadne z nich nie jest dostępne, sygnał nie jest wysyłany i nic nie trafia do kolejki.

Gdy Google Tag Manager jest chroniony przez <consent-guard> — czyli ładuje się dopiero po udzieleniu zgody przez użytkownika — PrivacyKit automatycznie ponawia wysyłkę sygnału po zakończeniu ładowania GTM.

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 update emitted.
Sygnał zgody został wysłany do gtag lub dataLayer.
[PrivacyKit] Google Consent Mode v2 update skipped because no Google tag was detected.
Nie wykryto ani gtag, ani dataLayer w przeglądarce, więc nic nie zostało wysłane.

Metody dialogu

TypeScriptDokumentacja API

openConsentDialog(): void
onConsentDialogClosed(callback: () => void): () => void
openPrivacyPolicyDialog(): void

<consent-guard>

Warunkowo renderuje zawartość, gdy przekazane wyrażenie zgody zwróci true.

Atrybuty

Atrybut	Typ	Domyślna / Wymagana	Opis
consent	string	unset	Wyrażenie zgody, które musi zostać spełnione, zanim treść zostanie wyrenderowana.

Wyrażenia zgody

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 Compliance Monitor dla niezbędnych zasobów, które nie są automatycznie rozpoznawane przez PrivacyKit.
preferences	Preferencje
analytics	Analityka
marketing	Marketing
preferences+analytics	Preferencje I Analityka
preferences\|analytics	Preferencje LUB Analityka
preferences+marketing	Preferencje I Marketing
preferences\|marketing	Preferencje LUB Marketing
analytics+marketing	Analityka I Marketing
analytics\|marketing	Analityka LUB Marketing

Przykład 1 – Chroń skrypty

HTML
<consent-guard consent="marketing">
  <script type="text/plain" data-src="https://www.googletagmanager.com/gtm/js"></script>
</consent-guard>

Przykład 2 – Chroń osadzone treści

HTML
<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 Compliance Monitor.

<consent-missing>

Renderuj treść zastępczą, gdy powiązany consent-guard blokuje główne doświadczenie.

Atrybuty

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>

<compliance-monitor>

Compliance Monitor 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.

Atrybuty

Atrybut	Typ	Domyślna / Wymagana	Opis
debug	boolean	false	Włącza panel Compliance Monitor przy ładowaniu strony. Tylko dla środowisk programistycznych.
delay	number	5000	Okno obserwacji sieci (w milisekundach) przed rozpoczęciem przez Compliance Monitor 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 Compliance Monitor.

Przykład

HTML
<compliance-monitor debug delay="5000" ignore-first-party-subdomains="true" fab-position="left"></compliance-monitor>

Compliance Monitor pozostaje ukryty dla odwiedzających, nawet gdy jest zawarty w pakiecie produkcyjnym. Zalecany sposób aktywacji na działającej witrynie to dodanie ?privacykit=monitor do adresu URL — aktywuje monitor tylko dla tej sesji przeglądarki, nie wpływając na doświadczenie odwiedzających.

Przełącz programowo:

TypeScriptDokumentacja API

window.PrivacyKit?.toggleComplianceMonitor();

Załączniki

Fragmenty CSS

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.

NPM

CSS
consent-dialog:not(:defined) [slot] {
  display: none;
}

consent-guard:not([active]) {
  display: none;
}

consent-missing:not([active]) {
  display: none;
}
Jeśli używasz treści w slotach lub używasz consent-guards z HTML, umieść ten fragment w globalnym arkuszu stylów lub w znaczniku <style>, który wykona się zanim web komponenty PrivacyKit zostaną wyrenderowane.