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ó
- Hozz létre fiókot az app.cookiepilot.io/register oldalon.
- 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.
Címke: CookiePilot - Consent Init + Banner
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
| Sorrend | Címke | Trigger |
|---|---|---|
| 1 | CookiePilot - Consent Init + Banner | Consent Initialization - All Pages |
| 2 | GA4, Google Ads, UET | All Pages (a Consent Mode maga kezeli a hozzájárulásokat) |
| 3 | Facebook 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.
- 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). - 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
- Name
- 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 truefelté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 truefelté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 truefelté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 truefelté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 truefelté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 truefelté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ímke | Kategória | Mező a cookiepilot_consent-ben |
|---|---|---|
| Facebook Pixel | marketing | marketing |
| TikTok Pixel | marketing | marketing |
| LinkedIn Insight | marketing | marketing |
| marketing | marketing | |
| Hotjar | analytics | analytics |
| Microsoft Clarity | analytics | analytics |
| Mixpanel, Amplitude | analytics | analytics |
| Intercom, Drift, Crisp | preferences | preferences |
| 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ódus | Leí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();
});
„Cookie-k kezelése" link a láblécben
<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ória | Leírás | Alapértelmezetten |
|---|---|---|
necessary | Az oldal működéséhez nélkülözhetetlen | Mindig aktív |
analytics | Statisztika és analitika | Hozzájárulás szükséges |
marketing | Hirdetések és remarketing | Hozzájárulás szükséges |
preferences | Személyre szabás, nyelv | Hozzájárulás szükséges |
Leképezés a Google Consent Mode-ra
| CookiePilot kategória | Consent Mode mezők |
|---|---|
analytics | analytics_storage |
marketing | ad_storage, ad_user_data, ad_personalization |
preferences | functionality_storage, personalization_storage |
| (mindig) | security_storage: granted |
Google Consent Mode v2
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éter | Leírás |
|---|---|
ad_storage | Reklámcookie-k |
analytics_storage | Analitikai cookie-k |
ad_user_data | Felhasználói adatok küldése a Google-nek |
ad_personalization | Hirdetések személyre szabása |
functionality_storage | Funkcionális cookie-k |
personalization_storage | Személyre szabási cookie-k |
security_storage | Mindig granted |
Mechanizmus:
- A stub szinkron módon
deniedállapotra állítja az összes mezőt,wait_for_update: 500mellett. - A felhasználó döntése után a widget kiküldi a
gtag('consent', 'update', {...})hívást a fenti leképezéssel. - 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.
- WordPress admin → Bővítmények → Új hozzáadása → keress rá: „CookiePilot".
- Telepítsd és aktiváld.
- 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
- Bolt → Témák → Kód szerkesztése.
- A
theme.liquidfá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).
Lefut a cookiepilot_consent_update event a visszatérő felhasználónál?
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
- Nyisd meg az oldalt inkognitó módban, és töröld a domain cookie-jait.
- Nyisd meg a DevTools → Network fület, és frissítsd az oldalt.
- 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 adeniedalapértelmezett állapot azad_storage,ad_user_data,ad_personalizationésanalytics_storagemezőkre.
- nem jönnek létre analitikai/marketing cookie-k, pl.
2. Teszt a hozzájárulás elfogadása után
- Kattints az „Összes elfogadása" gombra.
- A DevTools-ban ellenőrizd, hogy megjelent-e a
cookiepilot_consent_updateevent. - 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. - 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.
- A Meta Pixel / TikTok / LinkedIn esetén ellenőrizd, hogy a címkék csak a
cookiepilot_consent_updateevent és a marketinghozzájárulási feltétel után futnak-e le.
3. A hozzájárulás elutasításának tesztje
- Töröld a cookie-kat, és frissítsd az oldalt.
- Kattints az „Összes elutasítása" gombra.
- Ellenőrizd, hogy a marketing cookie-k és requestek továbbra sem indulnak el.
- 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 Initializationtriggeren fut a későbbi trigger helyett. - A Meta Pixelnek vagy a TikTok Pixelnek nincs feltétele a
cookiepilot_consent.marketingmező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ésdata-cpkeyhelyett.