PrivacyKit Web-komponentit

Julkinen web-komponenttidokumentaatio komponenteille consent-dialog, consent-guard, consent-missing ja compliance-monitor.

Sisällysluettelo

<consent-dialog>

PrivacyKitin suostumus-UI:n ja orkestrointilogiikan pääsisääntulokomponentti.

Attribuutit

Attribuutti	Tyyppi	Oletus / Pakollinen	Kuvaus
variant	standard \| panel \| modern \| modest	standard	Dialogin visuaalinen variantti.
theme	standard \| dark \| teal \| slate \| light \| vibrant \| high-contrast	standard	Dialogin visuaalinen teema.
expires-days	number	180	Evästeen elinikä päivinä.
version	number	0	Suostumusskeeman versio, jota käytetään uudelleensuostumuksen päätöksiin.
google-consent-mode	boolean	unset	Lähettää Google Consent Mode v2 -suostumussignaaleja käyttäjän PrivacyKit-suostumusvalintojen perusteella.
locale	da \| de \| en \| es \| fi \| fr \| it \| nl \| no \| pl \| sv	browser-derived	Kielen ohitus.
hide-summary-part-2	boolean	unset	Piilottaa valintaikkunan yhteenvedon osan 2 (dialog-summary-part-2).
hide-necessary	boolean	unset	Piilottaa Välttämätön-kategorian.
hide-preferences	boolean	unset	Piilottaa preferences-kategorian.
hide-analytics	boolean	unset	Piilottaa analytics-kategorian.
hide-marketing	boolean	unset	Piilottaa marketing-kategorian.
hide-readmore	boolean	unset	Piilottaa laajennettavan Lue lisää -osion.
hide-privacykit-badge	boolean	unset	Piilottaa PrivacyKit-merkin, joka näkyy suostumusdialogikentän alaosassa.
hide-privacy-policy-link	boolean	unset	Piilottaa oletusarvoisen tietosuojakäytännön linkin kokonaan. Käytä `privacy-policy-url` sen sijaan pitääksesi linkin näkyvissä ja ohjataksesi käyttäjät omalle tietosuojakäytäntösivullesi.
privacy-policy-url	string	unset	URL, johon käyttäjät ohjataan klikatessaan tietosuojakäytäntölinkkiä. Kun asetettu, linkki avaa tämän URL:n sisäänrakennetun tietosuojadialogín sijaan.
demo	boolean	unset	Demotila: poistaa automaattisen avauksen käytöstä ja rajoittaa tiettyjä ominaisuuksia. Ei GDPR-yhteensopiva eikä sitä saa käyttää tuotannossa.
dismissible	boolean	false	Määrittää, voiko dialogin sulkea taustaa klikkaamalla/escape-näppäimellä, jos hyväksy/hylkää-suostumusta ei ole annettu.
show-fab	boolean	false	Ottaa käyttöön suostumusasetusten painikkeen. Ei näy, ennen kuin suostumuseväste on olemassa.
fab-position	left \| right	left	Kiinnittää painikkeen näkymän vasempaan alakulmaan tai oikeaan alakulmaan.
dialog-position	left \| right	left	Määrittää, kummalla puolella näyttöä dialogi näytetään. Koskee vain modern- ja modest-variantteja — standard ja panel ovat aina keskitettyjä.

Esimerkki

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

Lokalisointi

<consent-dialog>-komponentissa on sisäänrakennetut käännökset englanniksi, norjaksi, saksaksi, puolaksi, espanjaksi, ranskaksi, italiaksi, hollanniksi, ruotsiksi, tanskaksi ja suomeksi — ei käännöstiedostoja ladattavaksi tai ylläpidettäväksi itse.

Automaattinen tunnistus

Oletuksena valintaikkuna lukee kävijän selainkielen ja näyttää vastaavan käännöksen automaattisesti. Jos selain on asetettu kielelle, jota PrivacyKit ei tue, se palautuu englantiin.

Kielen ohittaminen

Jos haluat pakottaa tietyn kielen kävijän selainasetuksista riippumatta, aseta locale-attribuutti — katso tuettujen koodien täydellinen luettelo yllä olevasta taulukosta.

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

Design tokenit

Design tokenit tarjoavat vakaan joukon CSS-muuttujia, joilla voit muokata ulkoasua — värejä, välistyksiä, typografiaa ja muuta — koskematta komponentin sisäiseen toteutukseen. Sisäänrakennetut teemat perustuvat samaan token-järjestelmään, joten voit yliajaa yksittäisiä tyylejä tai luoda täysin mukautetun ulkoasun.

Design tokenit	Kuvaus
--pk-transparency	Dialogin pinnan sekä sen sisäkkäisten korttien/accordion-elementtien läpinäkyvyys prosentteina. 0 % (oletus) on täysin peittävä; arvo rajataan enintään 50 %:iin.
--pk-bg-color	Pintatausta koko dialogin rungolle. Sekoitetaan --pk-transparency-arvon kanssa lopullisen värin muodostamiseksi.
--pk-paper-color	Paperipinta korteille, accordion-elementeille ja paneeleille dialogin sisällä. Sekoitetaan myös --pk-transparency-arvon kanssa.
--pk-text-color	Perustekstiväri otsikoille ja leipätekstille.
--pk-text-color-on-primary	Tekstiväri, jota käytetään ensisijaisella värillä täytetyissä elementeissä, kuten täysissä painikkeissa.
--pk-primary-color	Ensisijainen korostus CTAs-painikkeille, fokusrenkaille ja linkeille.
--pk-secondary-color	Toissijainen korostus, pääasiassa switch/thumb UI -tilaa varten.
--pk-focus-ring-color	Fokuskehyksen väri näppäimistöfokuksen tiloille.
--pk-font-family	Fonttipino kaikille tekstielementeille; käyttää oletuksena body-font tokeniasi.
--pk-spacing-unit	Välistysasteikon yksikkö, joka ohjaa paddings/gaps-arvoja osioiden välillä.
--pk-control-border-color	Reunaväri dialogin sisäisille kontrolleille — korteille, accordion-elementeille, painikkeille ja vastaaville elementeille.
--pk-control-border-width	Reunapaksuus dialogin sisäisille kontrolleille — korteille, accordion-elementeille, painikkeille ja vastaaville elementeille.
--pk-control-border-radius	Kulmasäde painikkeille, syötteille ja interaktiivisille kontrolleille.
--pk-dialog-border-color	Reunaväri itse dialogin kehykselle — ulomman paneelin ääriviivalle sekä ylä-/alatunnisteen jakoviivoille.
--pk-dialog-border-width	Reunapaksuus itse dialogin kehykselle — ulomman paneelin ääriviivalle sekä ylä-/alatunnisteen jakoviivoille.
--pk-dialog-border-radius	Kulmasäde ulommalle suostumusdialogin kontille.
--pk-dialog-max-height	Suostumusdialogin enimmäiskorkeus; kun sisältö ylittää tämän rajan, dialogin runko vierittyy.
--pk-dialog-shadow	Laatikkovarjo suostumusdialogin overlaylle.

Esimerkki

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

Sisältöpaikat

Lisää mukautettua sisältöä komponentin tiettyihin kohtiin nimettyjen HTML-slottien avulla — saat täyden hallinnan sisällöstä ja tyyleistä muuttamatta itse komponenttia.

Slotin nimi	Kuvaus
dialog-logo-top	Valinnainen logo tai brändin kuva, joka näytetään suostumusvalintaikkunan otsikossa.
dialog-logo-right	Valinnainen logo tai brändin kuva, joka näytetään suostumusvalintaikkunan oikeassa yläkulmassa.
dialog-title	Korvaa otsikon dialogin yläosassa.
dialog-summary-part-1	Lisää oma teksti ensimmäiseen intro-kappaleeseen dialogin otsikon alle.
dialog-summary-part-2	Lisää oma teksti toiseen intro-kappaleeseen, joka selittää suostumusvalinnat.
necessary-content	Korvaa oletuskuvauksen Necessary-kategoriassa.
preferences-content	Oma teksti Preferences-kategorian accordion-sisällössä.
analytics-content	Oma teksti Analytics-kategorian accordion-sisällössä.
marketing-content	Oma teksti Marketing-kategorian accordion-sisällössä.
read-more-title	Asettaa laajennettavan “Lue lisää” -osion otsikon alareunassa.
read-more-content	Antaa rungon sisällön, joka näytetään, kun “Lue lisää” -osio avautuu.
privacy-policy-content	Korvaa oletusarvoisen tietosuojakäytännön tekstin. Käytä oman lakitiimisi hyväksymää sanamuotoa, koska PrivacyKit ei voi varmistaa GDPR-yhteensopivuutta, kun muokkaat sitä.

Esimerkki

HTML
<consent-dialog theme="standard" variant="standard" locale="fi" version="1">
  <img slot="dialog-logo-top" width="100px" src="/logo.png" alt="Yrityksen logo" />
  <div slot="dialog-title" class="your-class">
    <h2>Käytämme evästeitä</h2>
  </div>
  <span slot="marketing-content">
    <b>Emme tällä hetkellä kerää evästeitä markkinointitarkoituksiin.</b>
  </span>
</consent-dialog>

Kelluva valintaikkunapainike

Kun show-fab on asetettu arvoon true, <consent-dialog> näyttää kelluvan toimintopainikkeen (FAB), jonka avulla käyttäjät voivat avata suostumusvalintansa uudelleen alkuperäisen lähetyksen jälkeen. Käytä fab-position -asetusta kiinnittääksesi sen näkymän vasempaan alakulmaan tai oikeaan alakulmaan.

Näkyvyyssäännöt

Piilotettu, kunnes alkuperäinen suostumus on lähetetty.
Piilotettu, kun suostumusvalintaikkuna tai tietosuojakäytäntö-ikkuna on auki.
Piilotettu, jos show-fab ei ole asetettu tai se on asetettu arvoon false.

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

Google Consent Mode v2

Kun google-consent-mode on käytössä, PrivacyKit lukee käyttäjän suostumusvalinnat ja välittää ne Google Tag Managerille tai gtagille Google Consent Mode v2 -protokollan avulla. Tämä tapahtuu automaattisesti sivun latautuessa ja aina, kun käyttäjä muuttaa suostumustaan. Muuta määritystä ei tarvita kuin attribuutin lisääminen.

Suositeltu asennus

<consent-guard>-elementin yhdistäminen GTM-katkelmasi ympärille yhdessä google-consent-mode-attribuutin kanssa valintaikkunassa on täytäntöönpanoon perustuva lähestymistapa: GTM ei voi ladata lainkaan ennen kuin suostumus on annettu, ja Google Consent Mode v2 -signaalit lähetetään heti, kun näin tapahtuu. GTM on vain säiliö — se voi sisältää analytiikkatageja, markkinointitageja tai molempia sen mukaan, mitä olet määrittänyt siihen. Aseta consent-lauseke elementtiin <consent-guard> vastaavasti: marketing, jos GTM laukaisee vain markkinointi-/mainostageja, analytics, jos kyseessä on pelkkä analytiikka, tai analytics+marketing, jos se laukaisee molemmat.

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>

Suostumussignaalien yhdistäminen

PrivacyKit yhdistää kolme suostumuskategoriaansa Googlen seitsemään Consent Mode v2 -kenttään:

GCM v2 -kenttä	Yhdistetty kohteesta	Arvo
analytics_storage	Analytiikka	granted / denied
ad_storage	Markkinointi	granted / denied
ad_user_data	Markkinointi	granted / denied
ad_personalization	Markkinointi	granted / denied
functionality_storage	Asetukset	granted / denied
personalization_storage	Asetukset	granted / denied
security_storage	—	Always granted

security_storage on aina granted, koska se kattaa turvallisuuden kannalta välttämättömän selaintallennuksen eikä ole valinnaisen seurantasuostumuksen alainen.

Miten signaalit lähetetään

PrivacyKit tarkistaa, onko window.gtag saatavilla (Google Tag Manager tai gtag.js ladattu). Jos on, se kutsuu:

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

Jos gtag ei ole saatavilla mutta window.dataLayer on, PrivacyKit lähettää suostumuspäivityksen suoraan dataLayeriin. Jos kumpaakaan ei ole, signaalia ei lähetetä eikä mitään jonoteta.

Kun Google Tag Manager on suojattu <consent-guard>-elementillä — eli se latautuu vasta, kun käyttäjä on antanut suostumuksensa — PrivacyKit yrittää automaattisesti lähettää signaalin uudelleen sen jälkeen, kun GTM on latautunut loppuun.

Virheenkorjausvihje: PrivacyKit kirjaa Google Consent Mode v2 -toimintansa selaimen konsoliin, jotta voit tarkistaa toiminnan suoraan DevToolsista:

[PrivacyKit] Google Consent Mode v2 update emitted.
Suostumussignaali lähetettiin gtagille tai dataLayerille.
[PrivacyKit] Google Consent Mode v2 update skipped because no Google tag was detected.
Selaimesta ei löytynyt gtagia eikä dataLayeria, joten mitään ei lähetetty.

Valintaikkunan metodit

TypeScriptAPI-viite

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

<consent-guard>

Renderöi lapset ehdollisesti, kun annettu suostumuslauseke arvioituu todeksi.

Attribuutit

Attribuutti	Tyyppi	Oletus / Pakollinen	Kuvaus
consent	string	unset	Suostumuslauseke, joka arvioidaan ennen kuin lapset renderöidään.

Suostumuslausekkeet

Lauseke	Vaadittu suostumus	Kuvaus
	Kaikki kategoriat	Jos consent-attribuutti puuttuu, kaikkien kategorioiden täytyy olla hyväksyttyjä, jotta guard aktivoituu.
necessary	Ei mitään	Estää virheelliset positiiviset Compliance Monitor -havainnot välttämättömille resursseille, joita PrivacyKit ei tunnista automaattisesti.
preferences	Asetukset
analytics	Analytiikka
marketing	Markkinointi
preferences+analytics	Asetukset JA Analytiikka
preferences\|analytics	Asetukset TAI Analytiikka
preferences+marketing	Asetukset JA Markkinointi
preferences\|marketing	Asetukset TAI Markkinointi
analytics+marketing	Analytiikka JA Markkinointi
analytics\|marketing	Analytiikka TAI Markkinointi

Esimerkki 1 – Suojaa skriptit

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

Esimerkki 2 – Suojaa upotettu sisältö

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>

Tärkeää: Huomaa, että esimerkkien hallitut resurssit käyttävät data-src -attribuuttia src-attribuutin sijaan ja type="text/plain" käytetään skripteille. PrivacyKit aktivoi hallitun sisällön vasta, kun suostumus on annettu — muuten resurssit voivat latautua heti ja näkyä Compliance Monitorissa kovakoodattuina.

<consent-missing>

Renderöi varasisältö aina, kun siihen liitetty consent-guard estää ensisijaisen kokemuksen.

Attribuutit

Attribuutti	Tyyppi	Oletus / Pakollinen	Kuvaus
for	string	pakollinen	Liittyvän <consent-guard>-elementin id.

Esimerkki

<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">
  Hyväksy analytiikkaevästeet jatkaaksesi.
</consent-missing>

<compliance-monitor>

Compliance Monitor seuraa lähteviä pyyntöjä ja validoi suostumusvartioinnin kattavuuden verkkosivustollasi, paljastaen hallitsemattomat seurantaohjelmat ja regressiot, joita verkkosivuston muutokset aiheuttavat. Oletuksena epäaktiivisena se pysyy näkymättömänä vierailijoille ja on turvallista sisällyttää tuotantoon.

Attribuutit

Attribuutti	Tyyppi	Oletus / Pakollinen	Kuvaus
debug	boolean	false	Ottaa Compliance Monitor -paneelin käyttöön sivun latauksen yhteydessä. Vain kehitysympäristöihin.
delay	number	5000	Verkon havaintoikkuna (millisekunteina) ennen kuin Compliance Monitor alkaa validoida päätepisteen käyttöä ja suostumusvartioinnin kattavuutta.
ignore-first-party-subdomains	boolean	true	Kun arvo on true, nykyisen verkkotunnuksen aliverkkotunnuksiin kohdistuvat pyynnöt ohitetaan hiljaisesti.
fab-position	left \| right	right	Määrittää, kummalle viewportin sivulle Compliance Monitorin FAB-painike kiinnitetään.

Esimerkki

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

Compliance Monitor pysyy piilossa vierailijoilta, vaikka se sisältyy tuotantopakettiin. Suositeltu tapa aktivoida se live-verkkosivustolla on lisätä ?privacykit=monitor URL-osoitteeseen — tämä aktivoi monitorin vain kyseiselle selainistunnolle vaikuttamatta vierailijakokemukseen.

Vaihda ohjelmallisesti:

TypeScriptAPI-viite

window.PrivacyKit?.toggleComplianceMonitor();

Liitteet

CSS-pätkät

Vältä välkkymistä ennen kuin web-komponentit ovat ladanneet. Ilman tätä pätkää sloteilla tai guardilla suojattu HTML voi näkyä hetken, kun:

consent-dialog voi välähtää, jos sloteilla lisättyjä elementtejä käytetään ja ne renderöityvät ennen kuin komponentin määrittely latautuu.
consent-guard voi välähtää, jos sitä käytetään ehdolliseen HTML:ään ja se renderöityy ennen kuin komponentti aktivoituu.
consent-missing voi välähtää, jos consent-missing renderöityy ennen kuin komponentti aktivoituu.

Lisää tyylit light DOMiin välttääksesi välkkymisen.

NPM

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

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

consent-missing:not([active]) {
  display: none;
}
Jos käytät slottattua sisältöä tai käytät consent-guardseja HTML:n kanssa, lisää tämä pätkä globaaliin tyylitiedostoosi tai <style>-tagiin, joka suoritetaan ennen kuin PrivacyKitin web-komponentit renderöidään.