Integracja JavaScript API - szybki start

Twoja aplikacja ma uruchomić kod dopiero po zgodzie użytkownika? Trzy snippety i koniec. Pełna specyfikacja dostępna jest tutaj: Pełna Referencja JavaScript API.

Korzystasz z Agentów AI typu Cursor, Claude Code lub Codex? Pobierz paczkę cookiezen-docs-api.md, która zawiera kompletną referencję API w jednym miejscu. Plik został dostosowany w celu przyspieszenia pracy z narzędziami LLM.

1. Oczekiwanie na zgodę przed uruchomieniem

Kod

try {
  await CookieZen.require('marketing', { timeout: 30000 });
  initMarketingWidget();
} catch (err) {
  if (err.code === 'CONSENT_DECLINED' || err.code === 'CONSENT_TIMEOUT') {
    showFallback('Włącz cookies marketingowe.');
  } else if (err.code === 'CONSENT_ABORTED') {
    // np. odmontowanie komponentu SPA: ciche czyszczenie, bez fallbacku
  } else throw err; // INVALID_CATEGORY: błąd w kodzie integratora
}

Snippet zakłada moduł ES lub funkcję async. W zwykłym <script> bez type="module" użyj wzoru z trzeciego punktu poniżej (.then() zamiast await).

Kategorie: marketing, analytics, preferences. Kody błędów: CONSENT_DECLINED, CONSENT_TIMEOUT, CONSENT_ABORTED, INVALID_CATEGORY.

2. Wycofanie lub zmiana zgody przez użytkownika

Kod

CookieZen.on('change', function ({ categories }) {
  if (categories.marketing) initWidget();
  else destroyWidget();
});

W komponentach SPA / React pamiętaj o CookieZen.off('change', handler) przy czyszczeniu.

Metoda CookieZen.on('change', …) z powyższego snippetu nasłuchuje zmian zgody. Uruchamia się, gdy zgoda faktycznie się zmienia: przy pierwszej decyzji użytkownika (np. akceptacji marketingu) oraz przy późniejszej zmianie lub wycofaniu wcześniejszej zgody. Nie uruchamia się przy samym wejściu na stronę, gdy zgoda była zapisana wcześniej.

Przy starcie aplikacji osobno: wywołaj CookieZen.require('marketing', …) jak w pierwszym snippecie powyżej albo sprawdź CookieZen.hasConsent('marketing') i wtedy załaduj widget.

> Ważne: idempotencja. Jeśli łączysz require() (start) z on('change', …), obie ścieżki zasygnalizują tę samą pierwszą akceptację, więc Twoja funkcja ładująca może zostać wywołana dwukrotnie przy jednej decyzji. Zadbaj, aby funkcje ładujące/usuwające były idempotentne (bezpieczne do wielokrotnego wywołania), inaczej ryzykujesz np. podwojony piksel lub zdublowany widget. Wzorzec z takim zabezpieczeniem pokazuje trzeci snippet poniżej.

3. Asynchroniczne ładowanie kodu

Aplikacje na wielu platformach, np. Shoper lub IdoSell, ładują się asynchronicznie. Nie ma gwarancji, że CookieZen załaduje się na stronie jako pierwszy. Użyj globalnej funkcji CookieZenCallback_OnReady. Wtedy CookieZen wywoła ją po inicjalizacji niezależnie od kolejności ładowania.

Kod

<script>
// Zabezpieczenie przed podwójnym wywołaniem: require() i zdarzenie 'change'
// mogą zasygnalizować tę samą (pierwszą) zgodę, więc SDK ładujemy/usuwamy dokładnie raz.
var sdkLoaded = false;
function ensureSdk() { if (sdkLoaded) return; sdkLoaded = true; loadSdk(); }
function removeSdk() { if (!sdkLoaded) return; sdkLoaded = false; unloadSdk(); }

window.CookieZenCallback_OnReady = function (CookieZen) {
  // Kontrola zgody: jeśli fallback poniżej zdążył załadować SDK zanim CookieZen
  // się pojawił, a zgody nie ma - usuń SDK. require() załaduje je po zgodzie.
  if (sdkLoaded && !CookieZen.hasConsent('marketing')) removeSdk();

  CookieZen.require('marketing', { timeout: 30000 })
    .then(ensureSdk)
    .catch(removeSdk); // odmowa lub timeout: nie ładuj / usuń SDK

  CookieZen.on('change', function (p) {
    if (p.categories.marketing) ensureSdk();
    else removeSdk();
  });
};

// Sklep bez loadera CookieZen: załaduj SDK po 2s.
setTimeout(function () {
  if (typeof window.CookieZen === 'undefined') ensureSdk();
}, 2000);
</script>

loadSdk() i unloadSdk() to Twoje własne funkcje, które ładują i usuwają aplikację wymagającą zgody, np. widget opinii, piksel reklamowy, czat. CookieZen ich nie dostarcza - podstawiasz w nie kod swojej integracji.

Fallback nie zastąpi działającego CMP: jeśli loader CookieZen jest na stronie, stub window.CookieZen pojawia się od razu i warunek undefined nie zadziała. Uwaga na sklepy, które wstrzykują loader CookieZen asynchronicznie później niż po 2 sekundach: fallback załaduje wtedy SDK bez zgody, ale kontrola zgody na początku CookieZenCallback_OnReady usunie je zaraz po inicjalizacji CookieZen. Jeśli Twoja platforma ładuje skrypty późno, zwiększ próg (np. 5000 ms) albo zrezygnuj z fallbacku.

Kompletny, gotowy do wklejenia przykład z loadSdk() / unloadSdk() (czyszczenie cookies, usuwanie SDK), typy TypeScript i pozostałe przepisy integracyjne znajdziesz w Pełnej Referencji lub w pliku cookiezen-docs-api.md.