Dokumentacja

Uruchom CookieGuard w trzech linijkach.

Wszystko, czego potrzebujesz, żeby zainstalować, skonfigurować i obsługiwać skrypt CookieGuard. Jeśli czegoś brakuje, napisz na hello@cisforcook.ie.

Instalacja

Wklej ten snippet w <head> swojej strony, przed jakimkolwiek tagiem third-party (Google Analytics, Meta Pixel, LinkedIn Insight, …). Kolejność ma znaczenie — CookieGuard wysyła defaulty Google Consent Mode v2 jako denied w momencie, gdy parser go zobaczy, a każdy tag załadowany później przeczyta te defaulty.

<script>
  window.CookieGuardConfig = {
    domain: "twojadomena.pl",
    theme: { primary: "#0F62FE" },
    language: "auto",
    geoMode: "eea-strict"
  };
</script>
<script async src="https://cisforcook.ie/v1/cookieguard.js"></script>

To wszystko. Banner pojawia się przy pierwszej wizycie, decyzja użytkownika jest zapamiętana, a sygnały Google Consent Mode v2 propagują się automatycznie.

Schemat konfiguracji

Każdy klucz jest opcjonalny poza domain. Defaulty są rozsądne — większość klientów zadowala się tylko snippetem powyżej.

Pole	Typ	Default	Notatki
`domain`	string	—	Wymagane. Twój hostname.
`layout`	"banner" \| "modal" \| "floating"	`"modal"`	Kształt bannera.
`position`	5 opcji	`"center"`	top / bottom / center / bottom-left / bottom-right.
`language`	"auto" \| "pl" \| "en" \| "de"	`"auto"`	Fallback do navigator.language.
`geoMode`	"eea-strict" \| "eea-only" \| "off"	`"eea-strict"`	Gdzie wymuszać opt-in.
`theme.primary`	hex	`#0F62FE`	Kolor CTA i akcent.
`theme.background`	hex	`#FFFFFF`
`theme.text`	hex	`#161616`
`theme.radius`	number (px)	`12`	Promień zaokrąglenia.
`theme.shadow`	"none" \| "sm" \| "md" \| "lg"	`"lg"`
`theme.logoUrl`	URL	—	Wyświetla się nad tytułem.
`theme.animation`	5 opcji	`"fade"`	fade / slide-up / slide-down / scale / none.
`policyUrl`	URL	—	Link z body bannera.
`consentVersion`	integer	`1`	Zwiększ, żeby wymusić ponowną zgodę.
`consentDurationDays`	integer	`365`	Jak długo pamiętać decyzję.
`googleConsentMapping`	obiekt	patrz niżej	Mapuje kategorie na sygnały GCMv2.
`reportUrl`	URL \| `false`	auto	Gdzie wysyłać rekordy zgody. Auto-derived ze script src.

Mapowanie Google Consent Mode v2 (default)

googleConsentMapping: {
  ad_storage:              "marketing",
  ad_user_data:            "marketing",
  ad_personalization:      "marketing",
  analytics_storage:       "analytics",
  functionality_storage:   "necessary",
  personalization_storage: "preferences",
  security_storage:        "necessary"
}

API JavaScript

Skrypt udostępnia window.cookieguard po zakończeniu loadera. Poczekaj przez ready(), jeśli musisz go wywołać przy starcie strony.

// Czekaj aż gotowe
await window.cookieguard.ready();

// Odczytaj stan zgody
const allowed = window.cookieguard.getConsent("analytics"); // true | false
const record  = window.cookieguard.getConsentState();       // ConsentRecord | null

// Reaguj na zmiany
const off = window.cookieguard.onConsentChange((rec) => {
  console.log("user changed consent:", rec.choices);
});
// off()  do unsubscribe

// Imperatywne
window.cookieguard.showBanner();        // otwórz banner
window.cookieguard.showPreferences();   // otwórz preferencje
window.cookieguard.revoke();            // wyczyść zapisaną zgodę

window.cookieguard.version;             // "0.0.1"

Typowy wzorzec to bramować non-essential skrypty na onConsentChange, a nie tylko przy load — wtedy reagujesz, gdy użytkownik później otworzy preferencje i zmieni zdanie.

Google Tag Manager

Dla użytkowników GTM — zainstaluj CookieGuard przez tag Custom HTML z triggerem Consent Initialization — All Pages. Ten trigger odpala się przed wszystkim innym, co gwarantuje, że denied defaulty dotrą przed jakimkolwiek pixelem.

GTM → Container Settings → włącz Consent Overview.
Tagi → Nowy → Custom HTML. Wklej snippet z Instalacji.
Triggering → Consent Initialization — All Pages.
Dla każdego istniejącego tagu (GA4, Meta Pixel, …) otwórz jego Consent settings i dodaj odpowiednie wartości required consent z tablicy w Konfiguracji.

Głębszy walkthrough: Jak wdrożyć CMP przez Google Tag Manager.

WordPress i Shopify

Natywny plugin WordPress i aplikacja Shopify są na bezpośrednim roadmapie. Do tego czasu wklej snippet przez:

WordPress — Wygląd → Edytor plików → header.php, przed </head>. Albo dowolny plugin „Header & Footer Scripts”.
Shopify — Online Store → Themes → Edit code → theme.liquid, przed </head>.
Webflow — Project Settings → Custom Code → Head code.
Wix / Squarespace — Settings → Custom Code → Head.

Webhooki i rekordy zgody

Za każdym razem, gdy użytkownik zapisze decyzję, skrypt wysyła event do POST /api/consent na origin CookieGuard. Możesz:

Zobaczyć każdy rekord w Panel → Domena → Zgody
Wyeksportować jako CSV albo NDJSON z tej samej strony
Zweryfikować łańcuch hash — każdy wiersz linkuje do poprzedniego przez prevHash / thisHash (SHA-256), więc jakakolwiek manipulacja zrywa łańcuch

Outbound webhooki (push do Twojego endpointu przy każdym evencie zgody) są na roadmapie. Do tego czasu polluj endpoint eksportu albo przeglądaj stronę zgód bezpośrednio.

Rozwiązywanie problemów

Banner się nie pokazuje

Sprawdź konsolę przeglądarki w poszukiwaniu [CookieGuard] window.CookieGuardConfig.domain missing.
Niektóre adblockery blokują CMP-y. Sprawdź zakładkę network — jeśli cookieguard.js jest blokowany, problem jest po stronie użytkownika, nie Twojej.
Jeśli wcześniej wyraziłeś zgodę, banner jest schowany. Otwórz DevTools > Application > Local Storage, usuń klucz cg_consent_v1::* i odśwież.

Tag odpala się przed udzieleniem zgody

Upewnij się, że Consent settings tagu w GTM zawierają odpowiedni wymóg analytics_storage / ad_storage.
Default wait_for_update: 500 daje Twojemu CMP 500 ms — jeśli skrypt ładuje się wolniej, zwiększ tę wartość w snippecie.

Dostaję błędy CORS na endpoincie `/api/consent`

Endpoint ustawia Access-Control-Allow-Origin: *. Jeśli wciąż widzisz błędy, zweryfikuj, czy Twój hostname jest zarejestrowany w panelu dokładnie tak, jak w pasku adresu przeglądarki.