Dokumentacja

Uruchom CJakCiasteczko w dwóch linijkach.

Wszystko, czego potrzebujesz, żeby zainstalować, skonfigurować i obsługiwać skrypt CJakCiasteczko. Jeśli czegoś brakuje, napisz na cjakciasteczko@aveneo.pl.

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.CookieConsentConfig = { domain: "twojadomena.pl" };
</script>
<script async src="https://cjakciasteczko.pl/v1/cjakciasteczko.js"></script>

To wszystko. Skrypt pobiera konfigurację banera (theme, layout, język, copy, polityka prywatności) z naszego panelu — edytujesz w Domeny → Konfiguracja, zmiana propaguje się w ~60 sekund bez podmiany kodu po Twojej stronie. Banner pojawia się przy pierwszej wizycie, decyzja jest zapamiętana, a sygnały Google Consent Mode v2 propagują się automatycznie.

Możesz też nadpisać konfigurację lokalnie — dowolne pole z tabeli poniżej w obiekcie window.CookieConsentConfig wygrywa z wartością z panelu. theme, buttons imanager są deep-merge — przebicie pojedynczej barwy nie wymazuje reszty konfiguracji z panelu.

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.
`theme.backdrop`	"dim" \| "none"	`"dim"`	Tylko dla layout=modal. Dim blokuje stronę, none zostawia ją klikalną.
`manager.show`	boolean	`true`	Floating button "Cookies" po dokonaniu pierwszej zgody — pozwala wycofać/zmienić decyzję (RODO art. 7(3)).
`manager.position`	"bottom-left" \| "bottom-right"	`"bottom-left"`	Pozycja floating buttona.
`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;             // np. "0.0.1" — z buildu skryptu

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 — jeśli widzisz [CookieConsent] window.CookieConsentConfig.domain missing, snippet jest niekompletny.
Jeśli widzisz [CookieConsent] X: unregistered — banner suppressed, dodaj swoją domenę w panelu (Twoje domeny → Dodaj domenę). Bez tego skrypt świadomie pozostaje cichy (kontrola dostępu).
Niektóre adblockery blokują CMP-y. Sprawdź zakładkę network — jeśli cjakciasteczko.js jest blokowany, problem jest po stronie użytkownika.
Jeśli wcześniej wyraziłeś zgodę, banner jest schowany — w prawym dolnym rogu masz mały floating button "Cookies", który otwiera preferencje. Można też wymusić ponowny banner: 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`

Apache na cjakciasteczko.pl ustawia Access-Control-Allow-Origin: * + obsługuje OPTIONS preflight. Jeśli wciąż widzisz błędy, zweryfikuj, czy Twój hostname jest zarejestrowany w panelu dokładnie tak, jak w pasku adresu przeglądarki (case-sensitive, bez www.).
Skrypt nigdy nie używa navigator.sendBeacon — on wymusza credentials=include i wybucha z wildcard CORS. Używamy zwykłego fetch() z credentials: "omit".