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. unmount komponentu SPA: cichy cleanup, 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. Error codes: 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) w cleanup.

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.

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>
window.CookieZenCallback_OnReady = function (CookieZen) {
  CookieZen.require('marketing', { timeout: 30000 })
    .then(loadSdk)
    .catch(function () { /* odmowa lub timeout: nie ładuj SDK */ });

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

// Sklep bez loadera CookieZen: załaduj SDK po 2s.
setTimeout(function () {
  if (typeof window.CookieZen === 'undefined') loadSdk();
}, 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.

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