Dokumentacja CookiePilot

Wprowadzenie

CookiePilot to polska platforma do zarządzania zgodami cookies (CMP), zgodna z RODO, PKE i Google Consent Mode v2. Ta dokumentacja pomoże Ci szybko wdrożyć i skonfigurować CookiePilot na Twojej stronie.

Dla kogo jest CookiePilot?

• Właściciele stron — szybkie wdrożenie bez programowania
• Developerzy — API, eventy, integracje z GTM
• Agencje — white-label, zarządzanie wieloma domenami

---

Szybki Start

Krok 1: Rejestracja

1. Załóż konto na app.cookiepilot.io/register
2. Dodaj swoją domenę w panelu

Krok 2: Instalacja kodu

Wklej poniższy kod przed zamknięciem tagu </head>:

<script src="https://cdn.cookiepilot.io/cookiepilot.js" data-cpkey="TWOJ_ID"></script>

Ważne: Kod CookiePilot musi być załadowany przed Google Tag Manager i innymi skryptami analitycznymi.

Krok 3: Konfiguracja banera

W panelu CookiePilot → Ustawienia → Wygląd:

• Wybierz pozycję banera (dół, góra, modal)
• Dostosuj kolory i teksty
• Włącz Google Consent Mode v2

---

Integracja z Google Tag Manager

CookiePilot integruje się z GTM w dwóch krokach: najpierw ustawia domyślne zgody inline w HTML, a następnie ładuje baner przez tag GTM.

Krok 1: Tag GTM — domyślne zgody (Consent Initialization)

Utwórz tag Custom HTML w GTM: Tagi → Nowy → Niestandardowy kod HTML. Wklej ten kod:

<script>"use strict";(function(){window.dataLayer=window.dataLayer||[];window.gtag=function(){window.dataLayer.push(arguments)};window.gtag("consent","default",{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});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>

• Trigger: Consent Initialization - All Pages (Inicjacja zgody)

Ważne: Trigger "Consent Initialization - All Pages" gwarantuje, że ten tag wykona się jako pierwszy — przed GTM i wszystkimi innymi tagami. Dzięki temu domyślne zgody są ustawione synchronicznie, zanim załadują się skrypty analityczne i reklamowe.

Krok 2: Tag GTM — CookiePilot Banner

Utwórz tag Custom HTML w GTM: Tagi → Nowy → Niestandardowy kod HTML. Wklej ten kod:

<script>
(function() {
  var s = document.createElement('script');
  s.src = 'https://cdn.cookiepilot.io/cookiepilot.js';
  s.setAttribute('data-cpkey', 'TWOJ_ID');
  document.head.appendChild(s);
})();
</script>

• Trigger: All Pages
• W opcjach uruchamiania tagu wybierz "Raz na stronę"

Kolejność uruchamiania tagów w GTM

Jak działa integracja

Po udzieleniu zgody przez użytkownika, CookiePilot automatycznie aktualizuje wartości Consent Mode:

gtag('consent', 'update', {
  'ad_storage': 'granted',
  'analytics_storage': 'granted',
  'ad_user_data': 'granted',
  'ad_personalization': 'granted'
});

---

API Reference

Globalne metody

CookiePilot udostępnia obiekt window.CookiePilot z następującymi metodami:

Przykład użycia

// Sprawdź stan zgód
const consent = CookiePilot.getConsent();
console.log(consent);
// { necessary: true, analytics: true, marketing: false, preferences: false }

// Programowo ustaw zgody
CookiePilot.setConsent({
  analytics: true,
  marketing: true
});

// Przycisk "Zmień ustawienia cookies"
document.getElementById('cookie-settings').addEventListener('click', () => {
  CookiePilot.show();
});

---

Eventy JavaScript

CookiePilot emituje eventy, które możesz nasłuchiwać:

Przykład

document.addEventListener('cookiepilot:consent', (event) => {
  console.log('Nowe zgody:', event.detail.consent);

  if (event.detail.consent.marketing) {
    // Załaduj skrypty marketingowe
    loadFacebookPixel();
  }
});

---

Kategorie Zgód

CookiePilot obsługuje 4 kategorie cookies:

Mapowanie na Consent Mode

---

Google Consent Mode v2

Czym jest Consent Mode?

Google Consent Mode to mechanizm przekazywania informacji o zgodach do usług Google (Analytics, Ads). Wersja 2 dodaje parametry ad_user_data i ad_personalization.

Parametry

Włączanie w CookiePilot

1. Panel → Ustawienia → Integracje
2. Włącz "Google Consent Mode v2"
3. Zapisz zmiany

CookiePilot automatycznie:

• Ustawia domyślne wartości denied
• Aktualizuje wartości po zgodzie użytkownika
• Obsługuje wait_for_update dla GTM

---

Konfiguracja wyglądu

Visual Builder

W panelu CookiePilot → Wygląd możesz dostosować:

• Pozycja: dół strony, góra, modal
• Kolory: tło, tekst, przyciski
• Teksty: nagłówek, opis, przyciski
• Logo: własne logo w banerze

Custom CSS

Dla zaawansowanych użytkowników — własne style CSS:

/* Własny kolor przycisku akceptacji */
.cookiepilot-btn-accept {
  background: #your-brand-color !important;
}

/* Własna czcionka */
.cookiepilot-banner {
  font-family: 'Your Font', sans-serif;
}

---

Dostępność (WCAG)

CookiePilot spełnia wymagania WCAG 2.1 AA:

• ✅ Nawigacja klawiaturą (Tab, Enter, Escape)
• ✅ Obsługa czytników ekranu (ARIA labels)
• ✅ Wystarczający kontrast kolorów
• ✅ Focus indicators
• ✅ Responsywność (mobile-first)

---

Integracje

WordPress

1. Zainstaluj wtyczkę "Insert Headers and Footers"
2. Wklej kod CookiePilot w sekcję <head>
3. Zapisz zmiany

Shopify

1. Otwórz Sklep → Motywy → Edytuj kod
2. Otwórz theme.liquid
3. Wklej kod przed </head>

Next.js / React

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

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

---

FAQ

Czy skrypt spowalnia stronę?

Nie. Skrypt CookiePilot waży poniżej 15KB (gzipped) i ładuje się asynchronicznie. Nie wpływa negatywnie na Core Web Vitals.

Jak długo przechowujecie zgody?

Przez 5-6 lat, zgodnie z zaleceniami EDPB i terminami przedawnienia roszczeń.

Gdzie zgłosić problem?

Napisz na kontakt@cookiepilot.io lub skorzystaj z chatu w panelu.