Dokumentacija

CookiePilot dokumentacija

Slapukų sutikimų valdymo platforma (CMP), atitinkanti BDAR, Lietuvos Elektroninių ryšių įstatymą ir Google Consent Mode v2.

Įvadas

CookiePilot – tai slapukų sutikimų valdymo platforma (CMP), atitinkanti BDAR (Bendrasis duomenų apsaugos reglamentas), Lietuvos Elektroninių ryšių įstatymą bei Google Consent Mode v2. Šių reikalavimų laikymąsi Lietuvoje prižiūri Valstybinė duomenų apsaugos inspekcija (VDAI).

Kam skirta

  • Svetainių savininkams: įdiegimas be programavimo.
  • Programuotojams: API, įvykiai, integracijos su GTM.
  • Agentūroms: white-label sprendimas, kelių domenų valdymas.

Greitas startas

1 žingsnis: registracija

  1. Susikurkite paskyrą app.cookiepilot.io/register.
  2. Pridėkite domeną valdymo skydelyje ir nukopijuokite API raktą (formatas cp_live_...).

2 žingsnis: kodo įdiegimas

Tiesioginis įdiegimas – tai du skriptai <head> sekcijoje, būtent šia tvarka.

2a žingsnis: numatytieji sutikimai (inline stub). Įklijuokite jį pirmąjį, prieš bet kurį kitą skriptą (cookiepilot.js, GA, GTM, reklamos ir sekimo žymas):

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

Šis inline kodo fragmentas iškart nustato visas kategorijas į denied (su wait_for_update: 500), tad numatytoji Google Consent Mode v2 būsena būna paruošta dar prieš tai, kai užkraunama bet kas kita. Grįžtančiam lankytojui jis iškart perskaito išsaugotą sutikimą iš slapuko ir paleidžia consent update.

2b žingsnis: banerio skriptas. Pridėkite jį iškart po inline stub:

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

3 žingsnis: banerio konfigūracija

Valdymo skydelyje: Domenas → Konfigūracija → Išvaizda:

  • banerio padėtis (viršuje, apačioje, modalas),
  • spalvos ir tekstai,
  • plaukiojantis mygtukas „Slapukų nustatymai“ grįžtantiems lankytojams.

Integracija su Google Tag Manager

Per GTM CookiePilot įdiegiate viena Custom HTML žyma, kuri iškart nustato numatytuosius sutikimus ir užkrauna banerį ankstyviausioje GTM fazėje. Atskiro stub failo ar antros žymos nereikia.

Žyma: CookiePilot - Consent Init + Banner

GTM sukurkite Custom HTML žymą (Žymos → Naujas → Tinkintas HTML kodas) ir įklijuokite:

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

Trigeris: Consent Initialization - All Pages. Žyma turi suveikti vieną kartą per puslapį. Google žymos (GA4, Google Ads), Facebook Pixel ir kitos rinkodaros žymos Consent Initialization trigerio NENAUDOJA – jos suveikia vėliau (Consent Checks arba nuo sutikimo priklausantis trigeris). Išsaugokite žymą ir paskelbkite GTM konteinerį.

Tvarka ir trigeriai

TvarkaŽymaTrigeris
1CookiePilot - Consent Init + BannerConsent Initialization - All Pages
2GA4, Google Ads, UETAll Pages (Consent Mode pats apdoros sutikimus)
3Facebook Pixel, TikTok, LinkedIn ir kt.Custom Event cookiepilot_consent_update + sutikimo sąlyga (žr. žemiau)

Žymos ne iš Google (Facebook Pixel, TikTok, LinkedIn)

Google Consent Mode apdoroja tik Google žymas. Kitiems skriptams valdiklis prie kiekvieno sutikimo pakeitimo perduoda į dataLayer įvykį:

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

Įvykis siunčiamas ir kiekvieną kartą grįžtančiam lankytojui apsilankius (kai valdiklis perskaito slapuką su sutikimu), tad GTM trigeris suveiks kiekvieno apsilankymo metu, ne tik priimant pirmąjį sprendimą.

Bendras šablonas (atlikite vieną kartą)

Šiuos tris elementus sukonfigūruojate vieną kartą, paskui naudojate visoms ne Google žymoms.

  1. Trigeris (Triggers → New → Custom Event): įvykio pavadinimas cookiepilot_consent_update. Be sąlygų, be „Once per page“ (žyma turi galėti suveikti dar kartą pakeitus sprendimą).
  2. Data Layer Variable kiekvienai naudojamai kategorijai:
    • Name cookiepilot_consent.marketing → kintamasis, pvz. dlv.cp_marketing
    • Name cookiepilot_consent.analytics → kintamasis, pvz. dlv.cp_analytics
    • Name cookiepilot_consent.preferences → kintamasis, pvz. dlv.cp_preferences
  3. Trigger Group arba sąlyga trigeryje: dlv.cp_marketing equals true (rinkodaros žymoms) arba atitinkamas laukas.

Kiekviename žemiau pateiktame pavyzdyje Trigger yra tas pats Custom Event su pridėta sąlyga atitinkamam kintamajam.

Facebook Pixel

Žyma GTM: 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>
  • Trigeris: cookiepilot_consent_update + sąlyga dlv.cp_marketing equals true.
  • Tag firing options: Once per page.

Pasirinktinai, kad būtų visiškai laikomasi Facebook Limited Data Use, pridėkite antrą žymą, kuri iškviečia fbq('consent','revoke') su trigeriu dlv.cp_marketing equals false.

TikTok Pixel

Žyma GTM: 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>
  • Trigeris: cookiepilot_consent_update + sąlyga dlv.cp_marketing equals true.
  • Tag firing options: Once per page.

ttq.grantConsent() – tai naujasis TikTok API (nuo 2024 m.). Be jo TikTok gauna maišos (hash) duomenis be sutikimo, o tai pažeidžia naudojimo sąlygas.

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>
  • Trigeris: cookiepilot_consent_update + sąlyga 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>
  • Trigeris: cookiepilot_consent_update + sąlyga dlv.cp_analytics equals true.
  • Tag firing options: Once per page.

Hotjar priskiriamas analytics, ne marketing (jis matuoja elgseną, o ne reklamą). Pasitikrinkite savo slapukų politiką – kai kurios įmonės Hotjar klasifikuoja kitaip.

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>
  • Trigeris: cookiepilot_consent_update + sąlyga 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>
  • Trigeris: cookiepilot_consent_update + sąlyga dlv.cp_marketing equals true.
  • Tag firing options: Once per page.

Microsoft Ads (UET)

UET palaiko Google Consent Mode nuo 2023 m. pabaigos, tad Custom Event trigerio nereikia. Įdėkite žymą įprastai (All Pages, Once per page), o UET pats nuskaitys ad_storage iš GCM, kurią nustato valdiklis.

Kategorijų atvaizdavimas (santrauka)

ŽymaKategorijaLaukas cookiepilot_consent
Facebook Pixelmarketingmarketing
TikTok Pixelmarketingmarketing
LinkedIn Insightmarketingmarketing
Pinterestmarketingmarketing
Hotjaranalyticsanalytics
Microsoft Clarityanalyticsanalytics
Mixpanel, Amplitudeanalyticsanalytics
Intercom, Drift, Crisppreferencespreferences
GA4, Google Ads, UET(GCM, be trigerio)apdorojama per gtag('consent','update')

API nuoroda

CookiePilot pateikia objektą window.CookiePilot:

MetodasAprašymas
CookiePilot.getConsent()Dabartinė sutikimų būsena arba null, jei sprendimo nėra.
CookiePilot.acceptAll()Sutikimas visoms kategorijoms.
CookiePilot.rejectAll()Atmeta viską, išskyrus necessary.
CookiePilot.updateConsent(partial)Atnaujina pasirinktas kategorijas, pvz. { analytics: true }.
CookiePilot.showSettings()Atidaro nustatymų modalą.
CookiePilot.hideSettings()Uždaro nustatymų modalą.
CookiePilot.showMyConsent() / hideMyConsent()Rodo / paslepia plaukiojantį mygtuką.

Pavyzdys

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

CookiePilot.updateConsent({ analytics: true });

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

Nuoroda „Tvarkyti slapukus“ poraštėje

<a href="#" onclick="CookiePilot.showSettings(); return false;">Tvarkyti slapukus</a>

JavaScript įvykiai

Valdiklis išsiunčia natyvų įvykį cookiepilot:consent į window. Klausytojas turi būti užregistruotas prieš užkraunant valdiklį, jei norite pagauti įvykį grįžtančiam lankytojui (išsiuntimas įvyksta iškart po valdiklio paleidimo):

<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 turi tą patį turinį (payload) kaip ir getConsent(). Integracijai per GTM verčiau naudokite aukščiau aprašytą dataLayer įvykį, nes dataLayer yra nuolatinis masyvas (persistent array) ir GTM apdoroja istorinius įvykius.

Sutikimų kategorijos

KategorijaAprašymasNumatytoji būsena
necessaryBūtini svetainės veikimuiVisada aktyvūs
analyticsStatistika ir analitikaReikalingas sutikimas
marketingReklama ir remarketingasReikalingas sutikimas
preferencesPersonalizavimas, kalbaReikalingas sutikimas
CookiePilot kategorijaConsent Mode laukai
analyticsanalytics_storage
marketingad_storage, ad_user_data, ad_personalization
preferencesfunctionality_storage, personalization_storage
(visada)security_storage: granted

2-oji versija pridėjo ad_user_data ir ad_personalization (privaloma nuo 2024 m. kovo ES/EEE teritorijoje, vykdant Google reklamą).

ParametrasAprašymas
ad_storageReklamos slapukai
analytics_storageAnalitikos slapukai
ad_user_dataNaudotojo duomenų siuntimas į Google
ad_personalizationReklamos personalizavimas
functionality_storageFunkciniai slapukai
personalization_storagePersonalizavimo slapukai
security_storageVisada granted

Mechanizmas:

  1. Stub sinchroniškai nustato visus laukus į denied, su wait_for_update: 500.
  2. Naudotojui priėmus sprendimą, valdiklis paleidžia gtag('consent', 'update', {...}) su aukščiau pateiktu atvaizdavimu.
  3. Grįžtančiam lankytojui 2 punktas suveikia iškart po valdiklio paleidimo, remiantis slapuku.

Išvaizdos konfigūracija

Valdymo skydelyje: Domenas → Konfigūracija:

  • Išvaizda: padėtis, spalvos, išdėstymas (BAR / BOX / MODAL).
  • Tekstai: antraštė, aprašymas, mygtukų etiketės, kategorijų aprašymai. 13 kalbų (EN, PL, DE, FR, ES, IT, NL, PT, SV, CS, RO, EL, HU).
  • Sutikimų mygtukas: plaukiojantis mygtukas „Slapukų nustatymai“, matomas po pirmojo sprendimo (apačioje kairėje / dešinėje).
  • Custom CSS: laukas savo stiliams. Valdiklis atvaizduojamas Shadow DOM, tad pagrindinio dokumento CSS selektoriai neveiks. Tik per šį lauką.

Prieinamumas (WCAG 2.1 AA)

  • ✅ Navigacija klaviatūra (Tab, Shift+Tab, Enter, Escape).
  • ✅ ARIA etiketės, role="dialog", aria-modal.
  • ✅ Fokuso gaudyklė (focus trap) modale.
  • ✅ Ekrano skaitytuvas (live regions būsenos pokyčiui).
  • ✅ Pritaikymas įvairiems ekranams.

Integracijos

WordPress

Turime oficialų įskiepį: CookiePilot WordPress.org svetainėje.

  1. WordPress administravimas → Įskiepiai → Pridėti naują → ieškokite „CookiePilot“.
  2. Įdiekite ir suaktyvinkite.
  3. Nustatymai → CookiePilot → įklijuokite API raktą iš valdymo skydelio.

Įskiepis pats įterpia stub ir žymą <head> (su teisinga tvarka prieš kitus skriptus) ir pateikia trumpinį [cookiepilot_settings] nuorodai „Tvarkyti slapukus“ poraštėje.

Jei norite be įskiepio: naudokite „Insert Headers and Footers“ ir įklijuokite kodo fragmentą iš Greito starto 2 žingsnio į Header sekciją.

Shopify

  1. Parduotuvė → Temos → Redaguoti kodą.
  2. Faile theme.liquid įklijuokite kodo fragmentą prieš </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" užtikrina, kad banerio skriptas suveiks anksti. Atminkite, kad inline stub iš 2a žingsnio (numatytieji sutikimai) pridedate atskirai, <head> sekcijoje prieš šį skriptą, pvz. per next/script su dangerouslySetInnerHTML arba tiesiai app/layout.tsx.

DUK

Ar skriptas lėtina svetainę?

Paketas (bundle) – apie 12 KB gzip, užkraunamas asinchroniškai. Neturi įtakos Core Web Vitals.

Kiek laiko saugomi sutikimai?

Slapukas su naudotojo sprendimu: numatytai 365 dienos (konfigūruojama valdymo skydelyje). Analitikos įvykiai: 2 metai (ClickHouse TTL).

Taip. Valdiklis paleidimo metu perskaito slapuką ir perduoda įvykį į dataLayer. Custom Event trigeris GTM suveiks kiekvieno apsilankymo metu, ne tik priimant pirmąjį sprendimą.

Kur pranešti apie problemą?

kontakt@cookiepilot.io arba per pokalbį valdymo skydelyje.

Patikros sąrašas po įdiegimo

Įdiegę CookiePilot, prieš paleisdami reklamos kampanijas patikrinkite konfigūraciją.

1. Testas prieš naudotojo sutikimą

  1. Atidarykite svetainę inkognito režimu ir išvalykite domeno slapukus.
  2. Atidarykite DevTools → Network ir atnaujinkite puslapį.
  3. Prieš spustelėdami sutikimą įsitikinkite, kad:
    • nesukuriami analitikos / rinkodaros slapukai, pvz. _ga, _gcl_*, _fbp, _ttp,
    • rinkodaros žymos nesiunčia užklausų į Meta / TikTok / LinkedIn prieš rinkodaros sutikimą,
    • dataLayer nustatyta numatytoji denied būsena laukams ad_storage, ad_user_data, ad_personalization ir analytics_storage.

2. Testas po sutikimų priėmimo

  1. Spustelėkite „Priimti visus“.
  2. DevTools patikrinkite, ar atsirado įvykis cookiepilot_consent_update.
  3. Google žymoms GTM Preview / Tag Assistant patikrinkite, ar Consent Mode pakeitė būseną į granted atitinkamoms kategorijoms.
  4. GA4 atveju DebugView patikrinkite, ar įvykiai pradėjo plaukti po sutikimo.
  5. Meta Pixel / TikTok / LinkedIn atveju patikrinkite, ar žymos suveikia tik po įvykio cookiepilot_consent_update ir rinkodaros sutikimo sąlygos.

3. Sutikimų atmetimo testas

  1. Išvalykite slapukus ir atnaujinkite puslapį.
  2. Spustelėkite „Atmesti visus“.
  3. Įsitikinkite, kad rinkodaros slapukai ir užklausos vis dar nepaleidžiami.
  4. Įsitikinkite, kad būtinos svetainės funkcijos vis dar veikia.

4. Dažniausios klaidos

  • GA4 / Google Ads žyma suveikia ties Consent Initialization, o ne vėlesniu trigeriu.
  • Meta Pixel ar TikTok Pixel neturi sąlygos ties cookiepilot_consent.marketing.
  • Svetainėje liko senas, įkoduotas (hardcoded) trekeris <head> sekcijoje prieš CookiePilot.
  • Dokumentacijoje ar šablone liko pasenęs skripto URL arba senas identifikatoriaus atributas vietoj dabartinio cookiepilot.js su data-cpkey.