Dokumentáció

CookiePilot fejlesztői dokumentáció

Cookie-hozzájárulás-kezelő platform (CMP), amely megfelel a GDPR-nek, a magyar elektronikus hírközlési törvénynek és a Google Consent Mode v2-nek.

Bevezetés

A CookiePilot egy cookie-hozzájárulás-kezelő platform (CMP), amely megfelel a GDPR-nek (általános adatvédelmi rendelet), az elektronikus hírközlésről szóló 2003. évi C. törvénynek és a Google Consent Mode v2-nek. Ezek betartatásáért Magyarországon a Nemzeti Adatvédelmi és Információszabadság Hatóság (NAIH) felel.

Kinek szól

  • Weboldal-tulajdonosoknak: programozás nélküli bevezetés.
  • Fejlesztőknek: API, eventek, GTM-integrációk.
  • Ügynökségeknek: white-label megoldás, több domain kezelése.

Gyors kezdés

1. lépés: Regisztráció

  1. Hozz létre fiókot az app.cookiepilot.io/register oldalon.
  2. Add hozzá a domaint a vezérlőpulton, és másold ki az API-kulcsot (cp_live_... formátum).

2. lépés: A kód telepítése

A közvetlen telepítés két szkriptből áll a <head> szekcióban, ebben a sorrendben.

2a. lépés: Alapértelmezett hozzájárulások (inline stub). Illeszd be elsőként, minden más szkript előtt (cookiepilot.js, GA, GTM, reklám- és követőcímkék):

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

Ez az inline snippet azonnal denied állapotra állítja az összes kategóriát (wait_for_update: 500 mellett), így a Google Consent Mode v2 alapértelmezett állapota készen áll, mielőtt bármi más betöltődne. Visszatérő felhasználó esetén azonnal beolvassa a cookie-ban tárolt hozzájárulást, és kiküld egy consent update eseményt.

2b. lépés: A banner szkriptje. Add hozzá közvetlenül az inline stub után:

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

3. lépés: A banner konfigurálása

A vezérlőpulton: Domain → Konfiguráció → Megjelenés:

  • a banner pozíciója (felül, alul, modal),
  • színek és szövegek,
  • lebegő „Cookie-beállítások" gomb a visszatérő felhasználóknak.

Integráció a Google Tag Managerrel

A GTM-en keresztül egyetlen Custom HTML címkével telepíted a CookiePilotot, amely azonnal beállítja az alapértelmezett hozzájárulásokat, és a GTM legkorábbi fázisában betölti a bannert. Nincs szükség külön stub fájlra vagy egy második címkére.

A GTM-ben hozz létre egy Custom HTML címkét (Címkék → Új → Egyéni HTML), és illeszd be:

<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. A címkének oldalanként egyszer kell lefutnia. A Google címkék (GA4, Google Ads), a Facebook Pixel és más marketingcímkék NEM a Consent Initialization triggert használják, hanem később futnak (Consent Checks vagy hozzájárulástól függő trigger). Mentsd el a címkét, és tedd közzé a GTM-konténert.

Sorrend és triggerek

SorrendCímkeTrigger
1CookiePilot - Consent Init + BannerConsent Initialization - All Pages
2GA4, Google Ads, UETAll Pages (a Consent Mode maga kezeli a hozzájárulásokat)
3Facebook Pixel, TikTok, LinkedIn stb.Custom Event cookiepilot_consent_update + hozzájárulási feltétel (lásd lent)

Google-on kívüli címkék (Facebook Pixel, TikTok, LinkedIn)

A Google Consent Mode csak a Google címkéket kezeli. A többi szkripthez a widget minden hozzájárulás-változáskor egy eventet pushol a dataLayer-be:

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

Az event a visszatérő felhasználó minden belépésekor is lefut (amikor a widget beolvassa a hozzájárulási cookie-t), így a GTM-trigger minden látogatáskor működik, nemcsak az első döntéskor.

Közös minta (egyszer kell elvégezni)

Ezt a három elemet egyszer konfigurálod be, utána az összes Google-on kívüli címkéhez használod.

  1. Trigger (Triggers → New → Custom Event): Az event neve cookiepilot_consent_update. Feltételek nélkül, „Once per page" nélkül (a címkének tudnia kell újra lefutni a döntés megváltoztatása után).
  2. Data Layer Variable minden használt kategóriához:
    • Name cookiepilot_consent.marketing → változó, pl. dlv.cp_marketing
    • Name cookiepilot_consent.analytics → változó, pl. dlv.cp_analytics
    • Name cookiepilot_consent.preferences → változó, pl. dlv.cp_preferences
  3. Trigger Group vagy a triggerben szereplő feltétel: dlv.cp_marketing equals true (a marketingcímkékhez), vagy a megfelelő mező.

Az alábbi példák mindegyikében a Trigger ugyanaz a Custom Event, kiegészítve a megfelelő változóra vonatkozó feltétellel.

Facebook Pixel

Címke a GTM-ben: 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 + dlv.cp_marketing equals true feltétel.
  • Tag firing options: Once per page.

Opcionálisan, a Facebook Limited Data Use teljes megfeleléséhez adj hozzá egy második címkét, amely a fbq('consent','revoke') hívást futtatja dlv.cp_marketing equals false triggerrel.

TikTok Pixel

Címke a GTM-ben: 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 + dlv.cp_marketing equals true feltétel.
  • Tag firing options: Once per page.

A ttq.grantConsent() a TikTok új API-ja (2024 óta). Enélkül a TikTok hozzájárulás nélkül kap hashelt adatokat, ami sérti a feltételeket.

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 + dlv.cp_marketing equals true feltétel.
  • 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 + dlv.cp_analytics equals true feltétel.
  • Tag firing options: Once per page.

A Hotjar az analytics alá tartozik, nem a marketing alá (a viselkedést méri, nem a hirdetéseket). Ellenőrizd a saját cookie-szabályzatodat, egyes cégek máshogy sorolják be a Hotjart.

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 + dlv.cp_analytics equals true feltétel.
  • 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 + dlv.cp_marketing equals true feltétel.
  • Tag firing options: Once per page.

Microsoft Ads (UET)

Az UET 2023 vége óta támogatja a Google Consent Mode-ot, így nincs szükséged Custom Event triggerre. Helyezd el a címkét a szokásos módon (All Pages, Once per page), és az UET magától beolvassa az ad_storage értéket a GCM-ből, amelyet a widget állít be.

Kategória-leképezés (rövid összefoglaló)

CímkeKategóriaMező a cookiepilot_consent-ben
Facebook Pixelmarketingmarketing
TikTok Pixelmarketingmarketing
LinkedIn Insightmarketingmarketing
Pinterestmarketingmarketing
Hotjaranalyticsanalytics
Microsoft Clarityanalyticsanalytics
Mixpanel, Amplitudeanalyticsanalytics
Intercom, Drift, Crisppreferencespreferences
GA4, Google Ads, UET(GCM, trigger nélkül)gtag('consent','update') kezeli

API-referencia

A CookiePilot a window.CookiePilot objektumot teszi elérhetővé:

MetódusLeírás
CookiePilot.getConsent()Az aktuális hozzájárulási állapot, vagy null, ha nincs döntés.
CookiePilot.acceptAll()Hozzájárulás az összes kategóriához.
CookiePilot.rejectAll()Mindent elutasít a necessary kivételével.
CookiePilot.updateConsent(partial)Frissíti a kiválasztott kategóriákat, pl. { analytics: true }.
CookiePilot.showSettings()Megnyitja a beállítások modalt.
CookiePilot.hideSettings()Bezárja a beállítások modalt.
CookiePilot.showMyConsent() / hideMyConsent()Megjeleníti/elrejti a lebegő gombot.

Példa

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;">Cookie-k kezelése</a>

JavaScript eventek

A widget natív cookiepilot:consent eventet diszpécsel a window objektumon. A listenert a widget betöltése előtt kell regisztrálni, ha el akarod kapni az eventet a visszatérő felhasználó esetében (a dispatch azonnal lefut a widget indulása után):

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

Az e.detail ugyanazt a payloadot tartalmazza, mint a getConsent(). GTM-en keresztüli integrációnál ehelyett a fent leírt dataLayer eventet használd, mert a dataLayer persistent tömb, és a GTM lenyeli a korábbi eventeket is.


Hozzájárulási kategóriák

KategóriaLeírásAlapértelmezetten
necessaryAz oldal működéséhez nélkülözhetetlenMindig aktív
analyticsStatisztika és analitikaHozzájárulás szükséges
marketingHirdetések és remarketingHozzájárulás szükséges
preferencesSzemélyre szabás, nyelvHozzájárulás szükséges
CookiePilot kategóriaConsent Mode mezők
analyticsanalytics_storage
marketingad_storage, ad_user_data, ad_personalization
preferencesfunctionality_storage, personalization_storage
(mindig)security_storage: granted

A 2-es verzió bevezette az ad_user_data és ad_personalization mezőket (2024 márciusától kötelező az EU/EGT területén a Google-hirdetéseknél).

ParaméterLeírás
ad_storageReklámcookie-k
analytics_storageAnalitikai cookie-k
ad_user_dataFelhasználói adatok küldése a Google-nek
ad_personalizationHirdetések személyre szabása
functionality_storageFunkcionális cookie-k
personalization_storageSzemélyre szabási cookie-k
security_storageMindig granted

Mechanizmus:

  1. A stub szinkron módon denied állapotra állítja az összes mezőt, wait_for_update: 500 mellett.
  2. A felhasználó döntése után a widget kiküldi a gtag('consent', 'update', {...}) hívást a fenti leképezéssel.
  3. Visszatérő felhasználó esetén a 2. pont azonnal lefut a widget indulása után, a cookie alapján.

Megjelenés konfigurálása

A vezérlőpulton: Domain → Konfiguráció:

  • Megjelenés: pozíció, színek, elrendezés (BAR / BOX / MODAL).
  • Szövegek: fejléc, leírás, gombfeliratok, kategórialeírások. 13 nyelv (EN, PL, DE, FR, ES, IT, NL, PT, SV, CS, RO, EL, HU).
  • Hozzájárulási gomb: lebegő „Cookie-beállítások" gomb, amely az első döntés után jelenik meg (bal/jobb alsó sarok).
  • Custom CSS: mező a saját stílusokhoz. A widget Shadow DOM-ban renderelődik, így a fődokumentumból származó CSS-szelektorok nem működnek. Csak ezen a mezőn keresztül.

Akadálymentesség (WCAG 2.1 AA)

  • ✅ Billentyűzetes navigáció (Tab, Shift+Tab, Enter, Escape).
  • ✅ ARIA labelek, role="dialog", aria-modal.
  • ✅ Focus trap a modalban.
  • ✅ Képernyőolvasó (live regions az állapotváltozáskor).
  • ✅ Reszponzivitás.

Integrációk

WordPress

Van hivatalos bővítményünk: CookiePilot a WordPress.org-on.

  1. WordPress admin → Bővítmények → Új hozzáadása → keress rá: „CookiePilot".
  2. Telepítsd és aktiváld.
  3. Beállítások → CookiePilot → illeszd be az API-kulcsot a vezérlőpultról.

A bővítmény magától beilleszti a stubot és a címkét a <head> szekcióba (a helyes, többi szkript előtti sorrendben), és biztosítja a [cookiepilot_settings] shortcode-ot a lábléc „Cookie-k kezelése" linkjéhez.

Ha a bővítmény nélkül szeretnéd: használd az „Insert Headers and Footers" eszközt, és illeszd be a snippetet a Gyors kezdés 2. lépéséből a Header szekcióba.

Shopify

  1. Bolt → Témák → Kód szerkesztése.
  2. A theme.liquid fájlban illeszd be a snippetet a </head> elé.

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

A strategy="beforeInteractive" biztosítja, hogy a banner szkriptje korán lefusson. Ne feledd, hogy a 2a. lépésből származó inline stubot (alapértelmezett hozzájárulások) külön kell hozzáadnod, a <head> szekcióban e szkript előtt, pl. next/script-tel dangerouslySetInnerHTML használatával, vagy közvetlenül az app/layout.tsx-ben.


GYIK

Lassítja a szkript az oldalt?

A bundle kb. 12 KB gzip, aszinkron módon töltődik be. Nincs hatással a Core Web Vitals-ra.

Meddig őrződnek meg a hozzájárulások?

A felhasználói döntést tároló cookie: alapértelmezetten 365 nap (a vezérlőpulton konfigurálható). Az analitikai események: 2 év (ClickHouse TTL).

Igen. A widget induláskor beolvassa a cookie-t, és az eventet a dataLayer-be pusholja. A GTM Custom Event triggere minden látogatáskor lefut, nemcsak az első döntéskor.

Hová jelenthetem a problémát?

kontakt@cookiepilot.io vagy a vezérlőpulton lévő chat.


Bevezetés utáni teszt checklist

A CookiePilot telepítése után ellenőrizd a konfigurációt, mielőtt reklámkampányokat publikálnál.

1. Teszt a felhasználói hozzájárulás előtt

  1. Nyisd meg az oldalt inkognitó módban, és töröld a domain cookie-jait.
  2. Nyisd meg a DevTools → Network fület, és frissítsd az oldalt.
  3. A hozzájárulásra kattintás előtt ellenőrizd, hogy:
    • nem jönnek létre analitikai/marketing cookie-k, pl. _ga, _gcl_*, _fbp, _ttp,
    • a marketingcímkék nem küldenek requestet a Meta/TikTok/LinkedIn felé a marketinghozzájárulás előtt,
    • a dataLayer-ben be van állítva a denied alapértelmezett állapot az ad_storage, ad_user_data, ad_personalization és analytics_storage mezőkre.

2. Teszt a hozzájárulás elfogadása után

  1. Kattints az „Összes elfogadása" gombra.
  2. A DevTools-ban ellenőrizd, hogy megjelent-e a cookiepilot_consent_update event.
  3. A Google címkéknél a GTM Preview / Tag Assistant felületen ellenőrizd, hogy a Consent Mode granted állapotra váltott-e a megfelelő kategóriáknál.
  4. A GA4-nél a DebugView-ban ellenőrizd, hogy a hozzájárulás után megkezdődött-e az események beérkezése.
  5. A Meta Pixel / TikTok / LinkedIn esetén ellenőrizd, hogy a címkék csak a cookiepilot_consent_update event és a marketinghozzájárulási feltétel után futnak-e le.

3. A hozzájárulás elutasításának tesztje

  1. Töröld a cookie-kat, és frissítsd az oldalt.
  2. Kattints az „Összes elutasítása" gombra.
  3. Ellenőrizd, hogy a marketing cookie-k és requestek továbbra sem indulnak el.
  4. Ellenőrizd, hogy az oldal nélkülözhetetlen funkciói továbbra is működnek.

4. Leggyakoribb hibák

  • A GA4/Google Ads címke a Consent Initialization triggeren fut a későbbi trigger helyett.
  • A Meta Pixelnek vagy a TikTok Pixelnek nincs feltétele a cookiepilot_consent.marketing mezőre.
  • Az oldalon maradt egy régi, hardcode-olt tracker a <head>-ben a CookiePilot előtt.
  • A dokumentációban vagy a sablonban elavult szkript-URL vagy régi azonosító-attribútum maradt az aktuális cookiepilot.js és data-cpkey helyett.