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.

Właściwość	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.
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-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.

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>

Przycisk preferencji zgody

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>

Dostosuj treść

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	Opcjonalna zawartość logo wyświetlana w nagłówku okna dialogowego.
dialog-logo-alt	Alternatywne miejsce na logo marki, wyświetlane w prawym górnym rogu tekstu dialog-summary-part-1.
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" 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>

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-bg-color	Kolor tła całej powłoki dialogu.
--pk-paper-color	Kolor papieru dla kart, akordeonów i paneli wewnątrz okna dialogowego.
--pk-text-color	Podstawowy kolor tekstu dla nagłówków i treści.
--pk-primary-color	Główny akcent dla CTA, obramowań focus i linków.
--pk-text-color-on-primary	Kolor tekstu używany na elementach wypełnionych kolorem podstawowym, takich jak pełne przyciski.
--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-border-color	Kolor obramowania paneli, tabel i linii podziału.
--pk-border-width	Grubość obramowania paneli, tabel i linii podziału.
--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-radius	Promień zaokrągleń dla przycisków, pól i interaktywnych kontrolek.
--pk-dialog-radius	Promień zaokrągleń zewnętrznego kontenera dialogu zgody.
--pk-dialog-shadow	Cień pola dialogu wyrażenia zgody.
--pk-dialog-max-height	Maksymalna wysokość okna dialogowego zgody; gdy treść przekroczy ten limit, korpus okna będzie przewijany.

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-radius: 10px;
  --pk-dialog-radius: 20px;
  --pk-dialog-shadow: 10px 20px rgba(0, 0, 0, 0.5);
  --pk-dialog-max-height: 50vh;
">
</consent-dialog>

Metody

TypeScriptDokumentacja API

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

<consent-guard>

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

Właściwość	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 - blokuj/ładuj skrypty

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

Przykład 2 - blokuj/ładuj treści HTML

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.

Właściwość	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.

Właściwość	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();