Dokumentatsioon

CookiePiloti arendaja dokumentatsioon

CookiePilot on küpsiste nõusolekute haldamise platvorm (CMP), mis vastab GDPR-ile, Eesti elektroonilise side seadusele ja Google Consent Mode v2-le.

Sissejuhatus

CookiePilot on küpsiste nõusolekute haldamise platvorm (CMP), mis vastab isikuandmete kaitse üldmäärusele (GDPR), Eesti elektroonilise side seadusele ja Google Consent Mode v2-le. Nende nõuete täitmist Eestis kontrollib Andmekaitse Inspektsioon (AKI).

Kellele

  • Veebilehtede omanikud: juurutamine ilma programmeerimiseta.
  • Arendajad: API, sündmused, integratsioonid GTM-iga.
  • Agentuurid: white-label, mitme domeeni haldamine.

Kiire alustamine

Samm 1: Registreerimine

  1. Loo konto aadressil app.cookiepilot.io/register.
  2. Lisa domeen halduspaneelis ja kopeeri API-võti (formaat cp_live_...).

Samm 2: Koodi paigaldamine

Otsene paigaldamine tähendab kahte skripti <head> sektsioonis, just selles järjekorras.

Samm 2a: Vaikimisi nõusolekud (inline stub). Aseta esimesena, enne mis tahes muud skripti (cookiepilot.js, GA, GTM, reklaami- ja jälgimissildid):

<script>"use strict";(function(){window.dataLayer=window.dataLayer||[];var d={ad_storage:"denied",ad_user_data:"denied",ad_personalization:"denied",analytics_storage:"denied",functionality_storage:"denied",personalization_storage:"denied",security_storage:"granted",wait_for_update:500},h=false;try{for(var i=0;i<window.dataLayer.length;i++){var x=window.dataLayer[i];if(x&&x[0]==="consent"&&x[1]==="default"){h=true;break}}}catch(err){}if(!h&&window.dataLayer.length)window.dataLayer.unshift(["consent","default",d]);window.gtag=function(){window.dataLayer.push(arguments)};if(!h)window.gtag("consent","default",d);var a=document.cookie.match(/(^|)cookiepilot_consent=([^;]+)/);if(a){try{var e=JSON.parse(decodeURIComponent(a[2]));window.gtag("consent","update",{analytics_storage:e.analytics?"granted":"denied",ad_storage:e.marketing?"granted":"denied",ad_user_data:e.marketing?"granted":"denied",ad_personalization:e.marketing?"granted":"denied",functionality_storage:e.preferences?"granted":"denied",personalization_storage:e.preferences?"granted":"denied",security_storage:"granted"})}catch(err){}}})();</script>

See inline-katke seab kohe kõik kategooriad olekusse denied (koos parameetriga wait_for_update: 500), nii et Google Consent Mode v2 vaikeolek on valmis enne, kui miski muu jõuab laadida. Korduvkülastaja puhul loeb see kohe küpsisest salvestatud nõusoleku ja saadab consent update.

Samm 2b: Banneri skript. Lisa kohe pärast inline stub'i:

<!-- CookiePilot -->
<script async src="https://cdn.cookiepilot.io/cookiepilot.js" data-cpkey="TWOJ_KLUCZ"></script>

Samm 3: Banneri seadistamine

Halduspaneelis: Domeen → Seadistus → Välimus:

  • banneri asukoht (üleval, all, modaalaken),
  • värvid ja tekstid,
  • hõljuv nupp „Küpsiste seaded" korduvkülastajatele.

Integratsioon Google Tag Manageriga

GTM-i kaudu paigaldad CookiePiloti ühe Custom HTML sildiga, mis seab kohe vaikimisi nõusolekud ja laadib banneri GTM-i kõige varasemas faasis. Sa ei vaja eraldi stub-faili ega teist silti.

Silt: CookiePilot - Consent Init + Banner

Loo GTM-is Custom HTML silt (Sildid → Uus → Kohandatud HTML-kood) ja kleebi:

<script>"use strict";
(function() {
window.dataLayer=window.dataLayer||[];var d={ad_storage:"denied",ad_user_data:"denied",ad_personalization:"denied",analytics_storage:"denied",functionality_storage:"denied",personalization_storage:"denied",security_storage:"granted",wait_for_update:500},h=false;try{for(var i=0;i<window.dataLayer.length;i++){var x=window.dataLayer[i];if(x&&x[0]==="consent"&&x[1]==="default"){h=true;break}}}catch(err){}if(!h&&window.dataLayer.length)window.dataLayer.unshift(["consent","default",d]);window.gtag=function(){window.dataLayer.push(arguments)};if(!h)window.gtag("consent","default",d);var a=document.cookie.match(/(^|)cookiepilot_consent=([^;]+)/);if(a){try{var e=JSON.parse(decodeURIComponent(a[2]));window.gtag("consent","update",{analytics_storage:e.analytics?"granted":"denied",ad_storage:e.marketing?"granted":"denied",ad_user_data:e.marketing?"granted":"denied",ad_personalization:e.marketing?"granted":"denied",functionality_storage:e.preferences?"granted":"denied",personalization_storage:e.preferences?"granted":"denied",security_storage:"granted"})}catch(err){}}
var s = document.createElement('script');
s.src = 'https://cdn.cookiepilot.io/cookiepilot.js?cpkey=' + encodeURIComponent('TWOJ_KLUCZ');
document.head.appendChild(s);
})();
</script>

Päästik: Consent Initialization - All Pages. Silt peab käivituma üks kord lehe kohta. Google'i sildid (GA4, Google Ads), Facebook Pixel ja muud turundussildid EI kasuta Consent Initialization päästikut, vaid käivituvad hiljem (Consent Checks või nõusolekust sõltuv päästik). Salvesta silt ja avalda GTM-i konteiner.

Järjekord ja päästikud

JärjekordSiltPäästik
1CookiePilot - Consent Init + BannerConsent Initialization - All Pages
2GA4, Google Ads, UETAll Pages (Consent Mode haldab nõusolekud ise)
3Facebook Pixel, TikTok, LinkedIn jneCustom Event cookiepilot_consent_update + nõusoleku tingimus (vaata allpool)

Google'i-välised sildid (Facebook Pixel, TikTok, LinkedIn)

Google Consent Mode haldab ainult Google'i silte. Ülejäänud skriptide jaoks saadab vidin iga nõusoleku muutuse korral dataLayer-isse sündmuse:

dataLayer.push({
  event: 'cookiepilot_consent_update',
  cookiepilot_consent: {
    necessary: true,
    analytics: true,
    marketing: true,
    preferences: false
  }
});

Sündmus käivitub ka iga korduvkülastaja sisenemisel (kui vidin loeb nõusolekuga küpsise), nii et GTM-i päästik töötab igal külastusel, mitte ainult esimese otsuse korral.

Ühine muster (tee üks kord)

Need kolm elementi seadistad üks kord ja kasutad seejärel kõigi Google'i-väliste siltide jaoks.

  1. Päästik (Triggers → New → Custom Event): sündmuse nimi cookiepilot_consent_update. Ilma tingimusteta, ilma valikuta „Once per page" (silt peab saama otsuse muutmise järel uuesti käivituda).
  2. Data Layer Variable iga kasutatava kategooria jaoks:
    • Name cookiepilot_consent.marketing → muutuja nt dlv.cp_marketing
    • Name cookiepilot_consent.analytics → muutuja nt dlv.cp_analytics
    • Name cookiepilot_consent.preferences → muutuja nt dlv.cp_preferences
  3. Trigger Group või tingimus päästikus: dlv.cp_marketing equals true (turundussiltide jaoks) või vastav väli.

Kõigis allolevates näidetes on Trigger sama Custom Event, millele on lisatud tingimus õige muutuja kohta.

Facebook Pixel

Silt GTM-is: Tags → New → Custom HTML.

<script>
!function(f,b,e,v,n,t,s){if(f.fbq)return;n=f.fbq=function(){n.callMethod?
n.callMethod.apply(n,arguments):n.queue.push(arguments)};if(!f._fbq)f._fbq=n;
n.push=n;n.loaded=!0;n.version='2.0';n.queue=[];t=b.createElement(e);t.async=!0;
t.src=v;s=b.getElementsByTagName(e)[0];s.parentNode.insertBefore(t,s)}(window,
document,'script','https://connect.facebook.net/en_US/fbevents.js');
fbq('init', 'YOUR_PIXEL_ID');
fbq('track', 'PageView');
</script>
  • Päästik: cookiepilot_consent_update + tingimus dlv.cp_marketing equals true.
  • Tag firing options: Once per page.

Valikuliselt, täielikuks vastavuseks Facebook Limited Data Use'ga, lisa teine silt, mis kutsub fbq('consent','revoke') koos päästikuga dlv.cp_marketing equals false.

TikTok Pixel

Silt GTM-is: Tags → New → Custom HTML.

<script>
!function (w, d, t) {
  w.TiktokAnalyticsObject=t;var ttq=w[t]=w[t]||[];ttq.methods=["page","track","identify","instances","debug","on","off","once","ready","alias","group","enableCookie","disableCookie","holdConsent","revokeConsent","grantConsent"],ttq.setAndDefer=function(t,e){t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}};for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(ttq,ttq.methods[i]);ttq.instance=function(t){for(var e=ttq._i[t]||[],n=0;n<ttq.methods.length;n++)ttq.setAndDefer(e,ttq.methods[n]);return e},ttq.load=function(e,n){var r="https://analytics.tiktok.com/i18n/pixel/events.js",o=n&&n.partner;ttq._i=ttq._i||{},ttq._i[e]=[],ttq._i[e]._u=r,ttq._t=ttq._t||{},ttq._t[e]=+new Date,ttq._o=ttq._o||{},ttq._o[e]=n||{};n=document.createElement("script");n.type="text/javascript",n.async=!0,n.src=r+"?sdkid="+e+"&lib="+t;e=document.getElementsByTagName("script")[0];e.parentNode.insertBefore(n,e)};
  ttq.load('YOUR_TIKTOK_PIXEL_ID');
  ttq.grantConsent();
  ttq.page();
}(window, document, 'ttq');
</script>
  • Päästik: cookiepilot_consent_update + tingimus dlv.cp_marketing equals true.
  • Tag firing options: Once per page.

ttq.grantConsent() on TikToki uus API (alates 2024). Ilma selleta saab TikTok räsitud andmeid ilma nõusolekuta, mis rikub kasutustingimusi.

LinkedIn Insight Tag

<script type="text/javascript">
_linkedin_partner_id = "YOUR_LINKEDIN_PARTNER_ID";
window._linkedin_data_partner_ids = window._linkedin_data_partner_ids || [];
window._linkedin_data_partner_ids.push(_linkedin_partner_id);
</script>
<script type="text/javascript">
(function(l) {
if (!l){window.lintrk = function(a,b){window.lintrk.q.push([a,b])};
window.lintrk.q=[]}
var s = document.getElementsByTagName("script")[0];
var b = document.createElement("script");
b.type = "text/javascript";b.async = true;
b.src = "https://snap.licdn.com/li.lms-analytics/insight.min.js";
s.parentNode.insertBefore(b, s);})(window.lintrk);
</script>
  • Päästik: cookiepilot_consent_update + tingimus dlv.cp_marketing equals true.
  • Tag firing options: Once per page.

Hotjar

<script>
(function(h,o,t,j,a,r){
  h.hj=h.hj||function(){(h.hj.q=h.hj.q||[]).push(arguments)};
  h._hjSettings={hjid:YOUR_HOTJAR_ID,hjsv:6};
  a=o.getElementsByTagName('head')[0];
  r=o.createElement('script');r.async=1;
  r.src=t+h._hjSettings.hjid+j+h._hjSettings.hjsv;
  a.appendChild(r);
})(window,document,'https://static.hotjar.com/c/hotjar-',".js?sv=");
</script>
  • Päästik: cookiepilot_consent_update + tingimus dlv.cp_analytics equals true.
  • Tag firing options: Once per page.

Hotjar kuulub kategooriasse analytics, mitte marketing (mõõdab käitumist, mitte reklaame). Kontrolli oma küpsiste poliitikat, sest mõned ettevõtted klassifitseerivad Hotjari teisiti.

Microsoft Clarity

<script type="text/javascript">
(function(c,l,a,r,i,t,y){
  c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
  t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
  y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
})(window, document, "clarity", "script", "YOUR_CLARITY_PROJECT_ID");
</script>
  • Päästik: cookiepilot_consent_update + tingimus dlv.cp_analytics equals true.
  • Tag firing options: Once per page.

Pinterest Tag

<script>
!function(e){if(!window.pintrk){window.pintrk = function () {
window.pintrk.queue.push(Array.prototype.slice.call(arguments))};var
n=window.pintrk;n.queue=[],n.version="3.0";var
t=document.createElement("script");t.async=!0,t.src=e;var
r=document.getElementsByTagName("script")[0];
r.parentNode.insertBefore(t,r)}}("https://s.pinimg.com/ct/core.js");
pintrk('load', 'YOUR_PINTEREST_TAG_ID');
pintrk('page');
</script>
  • Päästik: cookiepilot_consent_update + tingimus dlv.cp_marketing equals true.
  • Tag firing options: Once per page.

Microsoft Ads (UET)

UET toetab Google Consent Mode'i alates 2023. aasta lõpust, seega sa ei vaja Custom Event päästikut. Lisa silt tavapäraselt (All Pages, Once per page) ja UET loeb ise vidina seatud ad_storage väärtuse GCM-ist.

Kategooriate vastendus (kokkuvõte)

SiltKategooriaVäli cookiepilot_consent-is
Facebook Pixelmarketingmarketing
TikTok Pixelmarketingmarketing
LinkedIn Insightmarketingmarketing
Pinterestmarketingmarketing
Hotjaranalyticsanalytics
Microsoft Clarityanalyticsanalytics
Mixpanel, Amplitudeanalyticsanalytics
Intercom, Drift, Crisppreferencespreferences
GA4, Google Ads, UET(GCM, ilma päästikuta)hallatud gtag('consent','update') kaudu

API viide

CookiePilot teeb kättesaadavaks objekti window.CookiePilot:

MeetodKirjeldus
CookiePilot.getConsent()Nõusolekute praegune olek või null, kui otsust pole.
CookiePilot.acceptAll()Nõusolek kõikidele kategooriatele.
CookiePilot.rejectAll()Lükkab tagasi kõik peale necessary.
CookiePilot.updateConsent(partial)Uuendab valitud kategooriaid, nt { analytics: true }.
CookiePilot.showSettings()Avab eelistuste modaalakna.
CookiePilot.hideSettings()Sulgeb eelistuste modaalakna.
CookiePilot.showMyConsent() / hideMyConsent()Kuvab/peidab hõljuva nupu.

Näide

const consent = CookiePilot.getConsent();
// { necessary: true, analytics: true, marketing: false, preferences: false }

CookiePilot.updateConsent({ analytics: true });

document.getElementById('cookie-settings').addEventListener('click', () => {
  CookiePilot.showSettings();
});

<a href="#" onclick="CookiePilot.showSettings(); return false;">Halda küpsiseid</a>

JavaScripti sündmused

Vidin saadab window-ile natiivse sündmuse cookiepilot:consent. Kuulaja peab olema registreeritud enne vidina laadimist, kui soovid püüda sündmuse korduvkülastaja jaoks (dispatch käivitub kohe pärast vidina käivitumist):

<script>
  window.addEventListener('cookiepilot:consent', (e) => {
    if (e.detail.marketing) {
      fbq('init', 'YOUR_PIXEL_ID');
    }
  });
</script>
<script src="https://cdn.cookiepilot.io/cookiepilot.js" data-cpkey="TWOJ_KLUCZ"></script>

e.detail sisaldab sama andmekogumit nagu getConsent(). GTM-i kaudu integreerimisel kasuta selle asemel ülal kirjeldatud dataLayer sündmust, sest dataLayer on püsiv massiiv ja GTM neelab ka varasemad sündmused.

Nõusolekute kategooriad

KategooriaKirjeldusVaikimisi
necessaryLehe tööks hädavajalikAlati aktiivne
analyticsStatistika ja analüütikaVajab nõusolekut
marketingReklaamid ja remarketingVajab nõusolekut
preferencesPersonaliseerimine, keelVajab nõusolekut
CookiePiloti kategooriaConsent Mode'i väljad
analyticsanalytics_storage
marketingad_storage, ad_user_data, ad_personalization
preferencesfunctionality_storage, personalization_storage
(alati)security_storage: granted

Versioon 2 lisas ad_user_data ja ad_personalization (nõutud alates 2024. aasta märtsist EU/EEA jaoks Google'i reklaamide puhul).

ParameeterKirjeldus
ad_storageReklaamiküpsised
analytics_storageAnalüütikaküpsised
ad_user_dataKasutajaandmete saatmine Google'ile
ad_personalizationReklaamide personaliseerimine
functionality_storageFunktsionaalsed küpsised
personalization_storagePersonaliseerimisküpsised
security_storageAlati granted

Mehhanism:

  1. Stub seab kõik väljad sünkroonselt olekusse denied, koos parameetriga wait_for_update: 500.
  2. Pärast kasutaja otsust saadab vidin gtag('consent', 'update', {...}) ülaloleva vastendusega.
  3. Korduvkülastaja jaoks käivitub punkt 2 kohe pärast vidina käivitumist, küpsise põhjal.

Välimuse seadistamine

Halduspaneelis: Domeen → Seadistus:

  • Välimus: asukoht, värvid, paigutus (BAR / BOX / MODAL).
  • Tekstid: pealkiri, kirjeldus, nuppude sildid, kategooriate kirjeldused. 13 keelt (EN, PL, DE, FR, ES, IT, NL, PT, SV, CS, RO, EL, HU).
  • Nõusolekunupp: hõljuv nupp „Küpsiste seaded", nähtav pärast esimest otsust (vasak/parem alanurk).
  • Custom CSS: väli omaenda stiilide jaoks. Vidin renderdatakse Shadow DOM-is, seega põhidokumendi CSS-selektorid ei toimi. Ainult selle välja kaudu.

Ligipääsetavus (WCAG 2.1 AA)

  • ✅ Klaviatuurinavigatsioon (Tab, Shift+Tab, Enter, Escape).
  • ✅ ARIA labels, role="dialog", aria-modal.
  • ✅ Fookuse lõks (focus trap) modaalaknas.
  • ✅ Ekraanilugeja (live regions oleku muutmisel).
  • ✅ Responsiivsus.

Integratsioonid

WordPress

Meil on ametlik pistikprogramm: CookiePilot WordPress.org-is.

  1. WordPressi admin → Pistikprogrammid → Lisa uus → otsi „CookiePilot".
  2. Installi ja aktiveeri.
  3. Seaded → CookiePilot → kleebi API-võti halduspaneelist.

Pistikprogramm lisab ise stub'i ja sildi <head>-i (õiges järjekorras enne teisi skripte) ning pakub lühikoodi [cookiepilot_settings] jaluse lingi „Halda küpsiseid" jaoks.

Kui eelistad ilma pistikprogrammita: kasuta „Insert Headers and Footers" ja kleebi katke kiire alustamise sammust 2 Header-sektsiooni.

Shopify

  1. Pood → Kujundused → Muuda koodi.
  2. Failis theme.liquid kleebi katke enne </head>.

Next.js

// app/layout.tsx
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <Script
          src="https://cdn.cookiepilot.io/cookiepilot.js"
          data-cpkey="TWOJ_KLUCZ"
          strategy="beforeInteractive"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

strategy="beforeInteractive" tagab, et banneri skript käivitub varakult. Pea meeles, et sammu 2a inline stub'i (vaikimisi nõusolekud) lisad eraldi, <head>-i enne seda skripti, nt next/script kaudu koos dangerouslySetInnerHTML-iga või otse failis app/layout.tsx.

KKK

Kas skript aeglustab lehte?

Bundle on umbes 12 KB gzip, laaditakse asünkroonselt. Mõjuta Core Web Vitals'i.

Kui kaua nõusolekuid hoitakse?

Kasutaja otsusega küpsis: vaikimisi 365 päeva (halduspaneelis seadistatav). Analüütikasündmused: 2 aastat (ClickHouse'i TTL).

Jah. Vidin loeb küpsise käivitumisel ja saadab sündmuse dataLayer-isse. GTM-i Custom Event päästik käivitub igal külastusel, mitte ainult esimese otsuse korral.

Kuhu probleemist teatada?

kontakt@cookiepilot.io või vestlus halduspaneelis.

Testimise kontrollnimekiri pärast juurutamist

Pärast CookiePiloti paigaldamist kontrolli seadistust enne reklaamikampaaniate avaldamist.

1. Test enne kasutaja nõusolekut

  1. Ava leht inkognito-režiimis ja kustuta domeeni küpsised.
  2. Ava DevTools → Network ja värskenda lehte.
  3. Enne nõusoleku klõpsamist kontrolli, et:
    • ei tekiks analüütika-/turundusküpsiseid, nt _ga, _gcl_*, _fbp, _ttp,
    • turundussildid ei saadaks päringuid Meta/TikTok/LinkedIn-i enne turundusnõusolekut,
    • dataLayer-is on seatud vaikeolek denied väljadele ad_storage, ad_user_data, ad_personalization ja analytics_storage.

2. Test pärast nõusolekute andmist

  1. Klõpsa „Nõustu kõigiga".
  2. Kontrolli DevTools-is, kas ilmus sündmus cookiepilot_consent_update.
  3. Google'i siltide puhul kontrolli GTM Preview / Tag Assistant'is, kas Consent Mode muutis vastavate kategooriate oleku väärtuseks granted.
  4. GA4 puhul kontrolli DebugView's, kas sündmused hakkasid pärast nõusolekut saabuma.
  5. Meta Pixeli / TikToki / LinkedIni puhul kontrolli, kas sildid käivituvad alles pärast sündmust cookiepilot_consent_update ja turundusnõusoleku tingimust.

3. Test nõusolekute tagasilükkamisel

  1. Kustuta küpsised ja värskenda lehte.
  2. Klõpsa „Lükka kõik tagasi".
  3. Kontrolli, et turundusküpsiseid ja -päringuid endiselt ei käivitataks.
  4. Kontrolli, et lehe hädavajalikud funktsioonid endiselt töötaksid.

4. Levinumad vead

  • Silt GA4/Google Ads käivitub päästikul Consent Initialization hilisema päästiku asemel.
  • Meta Pixelil või TikTok Pixelil puudub tingimus cookiepilot_consent.marketing kohta.
  • Lehel on jäänud vana, kõvakodeeritud jälgija <head>-i CookiePiloti ette.
  • Dokumentatsiooni või šablooni on jäänud aegunud skripti URL või vana identifikaatori atribuut praeguse cookiepilot.js ja data-cpkey asemel.