Dokumentácia

Dokumentácia CookiePilot

Platforma na správu súhlasov s cookies (CMP), ktorá je v súlade s GDPR, slovenským zákonom o elektronických komunikáciách a s Google Consent Mode v2.

Úvod

CookiePilot je platforma na správu súhlasov s cookies (CMP), ktorá je v súlade s GDPR (všeobecné nariadenie o ochrane údajov), slovenským zákonom o ochrane súkromia v elektronických komunikáciách (zákon č. 452/2021 Z. z. o elektronických komunikáciách) a s Google Consent Mode v2.

Pre koho je určená

  • Majitelia stránok: nasadenie bez programovania.
  • Vývojári: API, eventy, integrácie s GTM.
  • Agentúry: white-label, správa viacerých domén.

Rýchly štart

Krok 1: Registrácia

  1. Založte si konto na app.cookiepilot.io/register.
  2. Pridajte doménu v paneli a skopírujte API kľúč (formát cp_live_...).

Krok 2: Inštalácia kódu

Priama inštalácia znamená dva skripty v sekcii <head>, v tomto poradí.

Krok 2a: Predvolené súhlasy (inline stub). Vložte ako prvý, pred akýmkoľvek iným skriptom (cookiepilot.js, GA, GTM, reklamné a sledovacie tagy):

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

Tento inline snippet okamžite nastaví všetky kategórie na denied (s wait_for_update: 500), takže predvolený stav Google Consent Mode v2 je pripravený skôr, než sa čokoľvek iné načíta. Pri vracajúcom sa používateľovi hneď načíta uložený súhlas z cookie a spustí consent update.

Krok 2b: Skript banera. Pridajte hneď za inline stub:

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

Krok 3: Konfigurácia banera

V paneli: Doména → Konfigurácia → Vzhľad:

  • pozícia banera (hore, dole, modálne okno),
  • farby a texty,
  • plávajúce tlačidlo „Nastavenia cookies“ pre vracajúcich sa používateľov.

Integrácia s Google Tag Managerom

Cez GTM nainštalujete CookiePilot jedným tagom typu Custom HTML, ktorý hneď nastaví predvolené súhlasy a načíta baner v najskoršej fáze GTM. Nepotrebujete samostatný stub súbor ani druhý tag.

Tag: CookiePilot - Consent Init + Banner

V GTM vytvorte tag Custom HTML (Tagy → Nový → Vlastný kód HTML) a vložte:

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

Trigger: Consent Initialization - All Pages. Tag sa musí spustiť raz na stránku. Google tagy (GA4, Google Ads), Facebook Pixel a ostatné marketingové tagy NEpoužívajú trigger Consent Initialization, ale spúšťajú sa neskôr (Consent Checks alebo trigger závislý od súhlasu). Uložte tag a publikujte kontajner GTM.

Poradie a triggery

PoradieTagTrigger
1CookiePilot - Consent Init + BannerConsent Initialization - All Pages
2GA4, Google Ads, UETAll Pages (Consent Mode si súhlasy ošetrí sám)
3Facebook Pixel, TikTok, LinkedIn atď.Custom Event cookiepilot_consent_update + podmienka súhlasu (pozri nižšie)

Tagy mimo Google (Facebook Pixel, TikTok, LinkedIn)

Google Consent Mode obsluhuje len Google tagy. Pre ostatné skripty widget pri každej zmene súhlasu pushuje do dataLayer event:

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

Event sa spúšťa aj pri každom príchode vracajúceho sa používateľa (keď widget načíta cookie so súhlasom), takže trigger v GTM zafunguje pri každej návšteve, nielen pri prvom rozhodnutí.

Spoločný vzor (vykonajte raz)

Tieto tri prvky nakonfigurujete raz a potom ich používate pre všetky tagy mimo Google.

  1. Trigger (Triggers → New → Custom Event): Event name cookiepilot_consent_update. Bez podmienok, bez „Once per page“ (tag sa musí dať spustiť znova po zmene rozhodnutia).
  2. Data Layer Variable pre každú kategóriu, ktorú používate:
    • Name cookiepilot_consent.marketing → premenná napr. dlv.cp_marketing
    • Name cookiepilot_consent.analytics → premenná napr. dlv.cp_analytics
    • Name cookiepilot_consent.preferences → premenná napr. dlv.cp_preferences
  3. Trigger Group alebo podmienka v triggeri: dlv.cp_marketing equals true (pre marketingové tagy) alebo príslušné pole.

V každom z nasledujúcich príkladov je Trigger ten istý Custom Event s pridanou podmienkou na správnu premennú.

Facebook Pixel

Tag v 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>
  • Trigger: cookiepilot_consent_update + podmienka dlv.cp_marketing equals true.
  • Tag firing options: Once per page.

Voliteľne, pre úplný súlad s Facebook Limited Data Use, pridajte druhý tag volajúci fbq('consent','revoke') s triggerom dlv.cp_marketing equals false.

TikTok Pixel

Tag v 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>
  • Trigger: cookiepilot_consent_update + podmienka dlv.cp_marketing equals true.
  • Tag firing options: Once per page.

ttq.grantConsent() je nové API TikTok (od roku 2024). Bez neho TikTok dostáva hashované údaje bez súhlasu, čo porušuje podmienky.

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>
  • Trigger: cookiepilot_consent_update + podmienka 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>
  • Trigger: cookiepilot_consent_update + podmienka dlv.cp_analytics equals true.
  • Tag firing options: Once per page.

Hotjar patrí pod analytics, nie marketing (meria správanie, nie reklamy). Skontrolujte si vlastnú politiku cookies, niektoré firmy klasifikujú Hotjar inak.

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>
  • Trigger: cookiepilot_consent_update + podmienka 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>
  • Trigger: cookiepilot_consent_update + podmienka dlv.cp_marketing equals true.
  • Tag firing options: Once per page.

Microsoft Ads (UET)

UET podporuje Google Consent Mode od konca roka 2023, takže Custom Event trigger nepotrebujete. Vložte tag štandardne (All Pages, Once per page) a UET si sám číta ad_storage z GCM, ktoré nastavuje widget.

Mapovanie kategórií (skrátene)

TagKategóriaPole v cookiepilot_consent
Facebook Pixelmarketingmarketing
TikTok Pixelmarketingmarketing
LinkedIn Insightmarketingmarketing
Pinterestmarketingmarketing
Hotjaranalyticsanalytics
Microsoft Clarityanalyticsanalytics
Mixpanel, Amplitudeanalyticsanalytics
Intercom, Drift, Crisppreferencespreferences
GA4, Google Ads, UET(GCM, bez triggera)spracované cez gtag('consent','update')

API Reference

CookiePilot sprístupňuje objekt window.CookiePilot:

MetódaPopis
CookiePilot.getConsent()Aktuálny stav súhlasov alebo null, ak rozhodnutie neexistuje.
CookiePilot.acceptAll()Súhlas so všetkými kategóriami.
CookiePilot.rejectAll()Odmietne všetko okrem necessary.
CookiePilot.updateConsent(partial)Aktualizuje vybrané kategórie, napr. { analytics: true }.
CookiePilot.showSettings()Otvorí modálne okno predvolieb.
CookiePilot.hideSettings()Zatvorí modálne okno predvolieb.
CookiePilot.showMyConsent() / hideMyConsent()Zobrazí/skryje plávajúce tlačidlo.

Príklad

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

CookiePilot.updateConsent({ analytics: true });

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

Odkaz „Spravovať cookies“ v pätičke

<a href="#" onclick="CookiePilot.showSettings(); return false;">Spravovať cookies</a>

JavaScript eventy

Widget dispatchuje natívny event cookiepilot:consent na window. Listener musí byť zaregistrovaný pred načítaním widgetu, ak chcete zachytiť event pre vracajúceho sa používateľa (dispatch sa spustí okamžite po štarte widgetu):

<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 obsahuje rovnaký payload ako getConsent(). Pre integráciu cez GTM použite namiesto toho dataLayer event opísaný vyššie, pretože dataLayer je persistent array a GTM prijíma aj historické eventy.

Kategórie súhlasov

KategóriaPopisPredvolene
necessaryNevyhnutné pre fungovanie stránkyVždy aktívne
analyticsŠtatistiky a analytikaVyžaduje súhlas
marketingReklamy a remarketingVyžaduje súhlas
preferencesPersonalizácia, jazykVyžaduje súhlas
Kategória CookiePilotPolia Consent Mode
analyticsanalytics_storage
marketingad_storage, ad_user_data, ad_personalization
preferencesfunctionality_storage, personalization_storage
(vždy)security_storage: granted

Verzia 2 pridala ad_user_data a ad_personalization (vyžadované od marca 2024 pre EU/EEA pri reklamách Google).

ParameterPopis
ad_storageReklamné cookies
analytics_storageAnalytické cookies
ad_user_dataOdosielanie údajov používateľa do Google
ad_personalizationPersonalizácia reklám
functionality_storageFunkčné cookies
personalization_storagePersonalizačné cookies
security_storageVždy granted

Mechanizmus:

  1. Stub nastaví všetky polia na denied synchrónne, s wait_for_update: 500.
  2. Po rozhodnutí používateľa widget spustí gtag('consent', 'update', {...}) s mapovaním uvedeným vyššie.
  3. Pri vracajúcom sa používateľovi sa bod 2 spustí okamžite po štarte widgetu, na základe cookie.

Konfigurácia vzhľadu

V paneli: Doména → Konfigurácia:

  • Vzhľad: pozícia, farby, rozloženie (BAR / BOX / MODAL).
  • Texty: nadpis, popis, štítky tlačidiel, popisy kategórií. 13 jazykov (EN, PL, DE, FR, ES, IT, NL, PT, SV, CS, RO, EL, HU).
  • Tlačidlo súhlasov: plávajúce tlačidlo „Nastavenia cookies“ viditeľné po prvom rozhodnutí (vľavo/vpravo dole).
  • Custom CSS: pole pre vlastné štýly. Widget sa renderuje v Shadow DOM, takže CSS selektory z hlavného dokumentu nebudú fungovať. Len cez toto pole.

Prístupnosť (WCAG 2.1 AA)

  • ✅ Navigácia klávesnicou (Tab, Shift+Tab, Enter, Escape).
  • ✅ ARIA labels, role="dialog", aria-modal.
  • ✅ Focus trap v modálnom okne.
  • ✅ Čítačka obrazovky (live regions pri zmene stavu).
  • ✅ Responzívnosť.

Integrácie

WordPress

Máme oficiálny plugin: CookiePilot na WordPress.org.

  1. WordPress admin → Pluginy → Pridať nový → vyhľadajte „CookiePilot“.
  2. Nainštalujte a aktivujte.
  3. Nastavenia → CookiePilot → vložte API kľúč z panela.

Plugin sám vloží stub a tag do <head> (so správnym poradím pred ostatnými skriptami) a poskytuje shortcode [cookiepilot_settings] pre odkaz „Spravovať cookies“ v pätičke.

Ak uprednostňujete riešenie bez pluginu: použite „Insert Headers and Footers“ a vložte snippet z kroku 2 Rýchleho štartu do sekcie Header.

Shopify

  1. Obchod → Motívy → Upraviť kód.
  2. V theme.liquid vložte snippet pred </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" zabezpečí, že skript banera sa vykoná skoro. Pamätajte, že inline stub z Kroku 2a (predvolené súhlasy) pridávate samostatne, do <head> pred týmto skriptom, napr. cez next/script s dangerouslySetInnerHTML alebo priamo v app/layout.tsx.

FAQ

Spomaľuje skript stránku?

Bundle má cca 12 KB gzip a načítava sa asynchrónne. Bez vplyvu na Core Web Vitals.

Ako dlho sa uchovávajú súhlasy?

Cookie s rozhodnutím používateľa: predvolene 365 dní (konfigurovateľné v paneli). Udalosti v analytike: 2 roky (TTL ClickHouse).

Áno. Widget načíta cookie pri štarte a pushuje event do dataLayer. Custom Event trigger v GTM sa spustí pri každej návšteve, nielen pri prvom rozhodnutí.

Kam nahlásiť problém?

kontakt@cookiepilot.io alebo chat v paneli.

Testovací checklist po nasadení

Po inštalácii CookiePilot skontrolujte konfiguráciu pred spustením reklamných kampaní.

1. Test pred súhlasom používateľa

  1. Otvorte stránku v režime incognito a vymažte cookies pre doménu.
  2. Otvorte DevTools → Network a obnovte stránku.
  3. Pred kliknutím na súhlas skontrolujte, že:
    • nevznikajú analytické/marketingové cookies, napr. _ga, _gcl_*, _fbp, _ttp,
    • marketingové tagy neodosielajú requesty na Meta/TikTok/LinkedIn pred marketingovým súhlasom,
    • v dataLayer je nastavený predvolený stav denied pre ad_storage, ad_user_data, ad_personalization a analytics_storage.

2. Test po prijatí súhlasov

  1. Kliknite na „Prijať všetko“.
  2. V DevTools skontrolujte, či sa objavil event cookiepilot_consent_update.
  3. Pre Google tagy overte v GTM Preview / Tag Assistant, či Consent Mode zmenil stav na granted pre príslušné kategórie.
  4. Pre GA4 skontrolujte DebugView, či eventy začali prichádzať po súhlase.
  5. Pre Meta Pixel / TikTok / LinkedIn skontrolujte, či sa tagy spúšťajú až po evente cookiepilot_consent_update a podmienke marketingového súhlasu.

3. Test odmietnutia súhlasov

  1. Vymažte cookies a obnovte stránku.
  2. Kliknite na „Odmietnuť všetko“.
  3. Skontrolujte, že marketingové cookies a requesty sa naďalej nespúšťajú.
  4. Skontrolujte, že nevyhnutné funkcie stránky naďalej fungujú.

4. Najčastejšie chyby

  • Tag GA4/Google Ads sa spúšťa na Consent Initialization namiesto neskoršieho triggera.
  • Meta Pixel alebo TikTok Pixel nemá podmienku na cookiepilot_consent.marketing.
  • Na stránke zostal starý, hardcodovaný tracker v <head> pred CookiePilot.
  • V dokumentácii alebo šablóne zostal neaktuálny URL skriptu alebo starý atribút identifikátora namiesto aktuálneho cookiepilot.js s data-cpkey.