Dokumentacja dla integratorów

Instalacja HTML

Dodaj dokładny host w panelu, zainstaluj kod, zweryfikuj instalację i opublikuj konfigurację. W Instalacji skopiuj kod swojej witryny. Zastąp YOUR_SITE_KEY publicznym kluczem; użyj adresu swojej platformy: https://biscotti.dev na produkcji albo https://dev.biscotti.dev dla osobnej platformy dev. Publiczny klucz nie daje dostępu administracyjnego.

Umieść jeden SDK w head, przed integracjami wymagającymi zgody. Wybierz jedną metodę i jeden klucz na dokument. Zwykły aktywny skrypt może wykonać się przed odroczonym SDK: oznacz zależne skrypty jako inert. W stopce zachowaj stałe ustawienia cookies.

Automatyczne aktualizacje (zalecane)

Wklejasz kod raz. Poprawki skryptu otrzymujesz automatycznie, bez ręcznej wymiany kodu. Dotychczasowe instalacje i WordPress działają tak samo.

<script id="biscotti-sdk" src="https://biscotti.dev/consent.js" data-site-key="YOUR_SITE_KEY" defer></script>

<script id="biscotti-sdk" src="https://biscotti.dev/sdk/9c2bc03275827be7431adcc709a295afb1f7778553dbaf3c3c4f8a2df233f702/consent.js" integrity="sha384-VtJRmbHcw1tU2ZG0b1SkNpDBvF0Wk2fuFyZG/CNH7stj+z9FgY8pbYK6eyk5KqmD" crossorigin="anonymous" data-site-key="YOUR_SITE_KEY" defer></script>

WordPress

Pobierz ZIP, zainstaluj i aktywuj wtyczkę w WordPressie. W Biscotti → Instalacja → WordPress skopiuj adres platformy i publiczny klucz do wtyczki. Administrator może wygenerować tymczasowy, jednorazowy kod parowania. Kod i dane połączenia zachowaj prywatnie; nie umieszczaj ich w HTML.

Połącz właściwy host, opublikuj konfigurację i usuń podwójną instalację SDK. Parowanie i import ustawień nie publikują szkicu i nie blokują automatycznie wszystkich wtyczek. Sprawdź rzeczywiste skrypty motywu i wtyczek.

Google Tag Manager — Basic

Zainstaluj Biscotti bezpośrednio lub przez WordPress, poza kontenerem. Usuń zwykły kod GTM i iframe noscript. Pod SDK wstaw loader i zastąp GTM-XXXXXXX. Kontener czeka na analitykę; mieszany kontener wymaga osobnych reguł każdego taga.

Wklej pobrany szablon do zakładki Kod natywnego szablonu GTM, nie Custom HTML. Dodaj zapis access_consent dla siedmiu sygnałów z tabeli, wykonanie access_globals: Biscotti.onConsentChange, Biscotti.canActivate i dataLayer.push oraz odczyt/zapis dataLayer. Wyzwalacz: Consent Initialization – All Pages. W tagach ustaw dodatkowe wymagania zgody i sprawdź Preview / Tag Assistant. Szablon emituje biscotti_consent_update w dataLayer; to inne zdarzenie niż DOM biscotti:consentchange. Tagi reguł wymagają dodatniej bramki canActivate dla opublikowanej reguły. Szablon nie jest dostępny w Community Template Gallery.

<script type="text/plain" data-consent-category="analytics">
(function () {
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({ 'gtm.start': Date.now(), event: 'gtm.js' });
  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://www.googletagmanager.com/gtm.js?id=GTM-XXXXXXX';
  document.head.appendChild(script);
})();
</script>

API i gotowość

window.Biscotti powstaje przy wykonaniu skryptu. Obecność API ani load nie oznaczają gotowości. Pobieranie konfiguracji zaczyna się przed DOMContentLoaded; UI czeka na gotowy DOM. Ready oznacza zwalidowaną publikację, rozstrzygnięte preferencje, gotowe bramki i Consent Mode, UI i nasłuch drugiej karty. Brak decyzji i zapisana odmowa są poprawne.

Gotowość nie czeka na audyt, odsłony, fonty ani tagi zewnętrzne. Odtwarzane adaptery startują po zdarzeniach początkowych; callback Promise może wykonać się po synchronicznym adapterze. ready i error są końcowymi stanami inicjalizacji dokumentu. Błąd działania nie zmienia ready na error. Po błędzie startu późniejszy poprawny wybór nadal emituje zmiany, ale whenReady pozostaje odrzucone do nowego dokumentu.

Zdarzenia DOM i payloady

Nasłuchuj na window, przed skryptem SDK, jeżeli potrzebujesz zdarzeń początkowych. biscotti:ready występuje raz; biscotti:consentchange dodaje reason do snapshotu; biscotti:error dodaje code i phase. To CustomEvent z bubbles=false i cancelable=false. Późny listener nie dostaje historii: użyj whenReady, getConsent i getLastError.

Start: stan/GCM/UI → dotychczasowe callbacki → ready → początkowe consentchange → adaptery. Zmiana: stan → callbacki → consentchange → aktywacja lub reload. Błąd: odmowa opcjonalnych → consentchange, jeśli stan się zmienił → error; błąd startu nie emituje ready. Snapshot i consents są zamrożone, bez ID decyzji, URL odwiedzającego, wartości cookies i wyjątków. hasDecision odróżnia jawną odmowę od braku decyzji; metadane publikacji są null przed walidacją. Wyjątek listenera nie zatrzymuje egzekwowania. Potwierdzenie audytu nie powiela zdarzenia zmiany.

W17 — biscotti:beforereload poprzedza wymagany reload/replace po wycofaniu. BeforeReloadDetail = SdkSnapshot + reason + navigation. Kod synchroniczny listenera na window wykonuje się przed nawigacją. SDK nie czeka na operacje asynchroniczne; szczegóły i przykład znajdziesz w sekcji o wycofaniu zgody.

window.addEventListener('biscotti:ready', ({ detail }) => {
  document.documentElement.dataset.biscottiReady = String(detail.apiVersion);
});
window.addEventListener('biscotti:consentchange', ({ detail }) => {
  document.documentElement.dataset.analyticsConsent = String(detail.consents.analytics);
});
window.addEventListener('biscotti:error', ({ detail }) => {
  console.warn('Biscotti', detail.code, detail.phase);
});

type SdkSnapshot = {
  readonly apiVersion: 1;
  readonly siteKey: string | null;
  readonly publicationVersion: number | null;
  readonly consentEpoch: number | null;
  readonly environment?: 'development';
  readonly hasDecision: boolean;
  readonly consents: Readonly<{
    necessary: true;
    functional: boolean; analytics: boolean; performance: boolean;
    advertising: boolean; unclassified: boolean;
  }>;
};
type ConsentChangeDetail = SdkSnapshot & {
  readonly reason: 'initial' | 'choice' | 'storage' | 'expiry' | 'error';
};
type BeforeReloadDetail = SdkSnapshot & {
  readonly reason: ConsentChangeDetail['reason'];
  readonly navigation: 'reload' | 'replace';
};
type SdkErrorDetail = SdkSnapshot & {
  readonly code:
    | 'INVALID_SITE_KEY' | 'CONFIGURATION_UNAVAILABLE'
    | 'INVALID_CONFIGURATION' | 'STORAGE_UNAVAILABLE'
    | 'CONSENT_MODE_FAILED' | 'ADAPTER_FAILED'
    | 'SYNC_FAILED' | 'INITIALIZATION_FAILED';
  readonly phase: 'initialization' | 'runtime';
};

Aplikacje SPA

Uruchom przykład, gdy element script SDK jest już w DOM; plik może być jeszcze w trakcie ładowania albo już załadowany. Zainstaluj SDK raz w szkielecie dokumentu. Subskrybuj zmiany niezależnie od powodzenia whenReady. Przykład aktualizuje atrybut danych w DOM; zastąp tę instrukcję własną integracją uwzględniającą zgodę. Przy demontażu wywołaj disconnectBiscotti.

whenReady zawsze zwraca początkowy snapshot, także po późniejszej decyzji. Aktualny wybór odczytuj przez getConsent lub subskrypcję. Nawigacja w tym samym dokumencie nie uruchamia inicjalizacji ani nie pobiera nowej publikacji. Nowe elementy inert mogą uruchomić się raz na element. Nie zastępuj window.Biscotti atrapą ani kolejką metod.

function connectBiscotti() {
  const api = window.Biscotti;
  if (!api || api.apiVersion !== 1) return () => {};
  const unsubscribe = api.onConsentChange(consents => {
    document.documentElement.dataset.analyticsConsent = String(consents.analytics);
  });
  void api.whenReady().catch(error => {
    console.warn('Biscotti initialization', error.code);
  });
  return unsubscribe;
}
const script = document.getElementById('biscotti-sdk');
let disconnect = () => {};
const onLoad = () => { disconnect(); disconnect = connectBiscotti(); };
if (window.Biscotti) onLoad();
else script?.addEventListener('load', onLoad, { once: true });
const onError = () => { document.documentElement.dataset.analyticsConsent = 'false'; };
script?.addEventListener('error', onError);
function disconnectBiscotti() {
  script?.removeEventListener('load', onLoad);
  script?.removeEventListener('error', onError);
  disconnect();
}

Adaptery skryptów inert

Użyj type="text/plain", data-consent-category, a dla skryptu zewnętrznego data-consent-src zamiast src. Zastąp przykładowy URL adresem integracji. Opcjonalne kategorie zaczynają wyłączone. Adapter uruchamia się raz na element w dokumencie, po wymaganej zgodzie.

Obsługiwane są klasyczne skrypty inline i zewnętrzne HTTP(S), z kopiowaniem nonce, integrity i crossorigin. Moduły JS, nomodule, iframe noscript, dowolne piksele i cookies backendu są poza tym kontraktem. Adapter kategorii jest niezależny od pauzy reguł. canActivate(ruleId) sprawdza opublikowaną regułę, ale nie uruchamia taga. Mieszane tagi wymagają osobnego przeglądu.

<script type="text/plain" data-consent-category="analytics">
  window.exampleAnalyticsStarted = true;
</script>
<script type="text/plain" data-consent-category="analytics"
        data-consent-src="https://analytics.example.com/sdk.js"></script>

Kategorie i Google Consent Mode

SDK ustawia opcjonalne sygnały Google na denied, security_storage na granted, a następnie aktualizuje mapowane sygnały według wyboru. Integracja działa w Basic: tagi Google muszą czekać na zgodę. Nie instaluje GA/GTM i nie włącza automatycznie Advanced.

Tabela pokazuje dokładne mapowanie. performance i unclassified nie mają natywnego sygnału Google: egzekwuj ich kategorię lub dodatnią bramkę reguły. Brak sygnału nie uprawnia do uruchomienia taga. Wyłączonych kategorii nie można przyznać. W GTM dodaj wymagania zgody oraz odpowiednie bramki reguł.

performance oznacza pomiar techniczny: szybkość ładowania i stabilność witryny. Pomiar ruchu, zachowania odwiedzających, GA4 i Clarity przypisz do analytics; pomiar kampanii i remarketing do advertising, nawet jeśli narzędzie mierzy też szybkość. Klasyfikuj według faktycznego celu, a narzędzie o kilku celach rozdziel lub wymagaj wszystkich odpowiednich zgód. performance i unclassified nie mają natywnego sygnału Google. Sama zgoda performance nie przyznaje analytics_storage ani zgód reklamowych. Dla skryptów performance wymagaj tej kategorii lub dodatniej bramki opublikowanej reguły; brak sygnału Google nie oznacza pozwolenia. W GTM użyj warunku biscottiPerformance równa się true, a dla reguły również jej dodatniej bramki. Nie dodawaj fikcyjnego performance_storage. Mapowanie i znaczenie zapisanych zgód nie zmieniają się; ta poprawka nie wymaga ponownej decyzji. Gdy zmieniasz cel narzędzia lub zakres zgody, opublikuj zmianę z odnowieniem zgód.

Google Consent Mode · Tag Assistant

Domeny i środowiska testowe

Publikacja odpowiada jednemu dokładnemu hostname. example.com, www.example.com i shop.example.com to różne hosty. Walidacja SDK i CORS porównują host publikacji; klucz witryny nie omija tej kontroli. Preferencje są host-only, bez automatycznego współdzielenia subdomen.

Osobny klucz do testów localhost i stagingu. Dane testowe nie trafiają do raportów produkcyjnych ani rozliczeń. Najpierw zapisz szkic banera i zatwierdź informacje o cookies. Kopia testowa używa tych danych oraz ostatnich opublikowanych reguł blokowania (bez publikacji: brak reguł). Każdy zapis odnawia zgodę testową. Localhost, 127.0.0.1 i [::1] wymagają dokładnego portu. Staging wymaga HTTPS na porcie 443 oraz sprawdzenia instalacji z kluczem testowym. Host produkcyjny jest wykluczony.

W panelu witryny wybierz Instalacja → Tryb deweloperski → Zapisz konfigurację testową, dodaj http://localhost:5173 i skopiuj kod z kluczem dev_. Uruchom przykład poniżej w tym originie, używając hostowanej platformy Biscotti. Nie musisz uruchamiać platformy lokalnie. Dane produkcji i jej klucz site_ pozostają osobne. Staging dodaj jako dokładny origin HTTPS, wstaw kod z kluczem testowym na jego stronie głównej, a następnie wybierz Sprawdź instalację. Weryfikator nie łączy się z prywatnymi adresami.

Preferencje i kolejka testowa są oddzielone kluczem oraz originem, także portem. Snapshot SDK i zdarzenia mają dodatkowe environment: development, a baner oznaczenie testowe. Wyłączenie, usunięcie originu lub odnowienie klucza blokuje kolejne żądania; otwarty dokument wymaga przeładowania. Testowy klucz jest publiczny. Kontrola Origin ogranicza przeglądarkę, nie uwierzytelnia żądań serwerowych. Adaptery i tagi po udzieleniu zgody nadal wykonują prawdziwe integracje: użyj własnych kont testowych. Nie tworzysz dodatkowej licencjonowanej witryny ani powiązanego stagingu. Odnowienie klucza usuwa wyłącznie dane testowe; weryfikację stagingu trzeba powtórzyć.

Limity testów: 10 originów, 20 konfiguracji, 1000 decyzji i 1000 odsłon. Po osiągnięciu limitu odnów klucz.

Publiczny staging musi być właściwą subdomeną domeny produkcyjnej, np. staging.example.com dla example.com lub www.example.com (pomijamy tylko jedno początkowe www.); do testów na innej domenie dodaj osobną witrynę.

<script>
window.addEventListener('biscotti:ready', ({ detail }) => {
  console.assert(detail.environment === 'development');
});
</script>
<script src="https://biscotti.dev/consent.js" data-site-key="YOUR_TEST_KEY" defer></script>
<script type="text/plain" data-consent-category="analytics">
  document.documentElement.dataset.testAnalytics = 'active';
</script>
<button type="button" data-biscotti-preferences>Cookies</button>

Zmiana i wycofanie zgody

Zachowaj ten przycisk w stopce witryny. openPreferences otwiera ustawienia i nie przyznaje zgody. Jeśli SDK uruchomił adaptery, wycofanie także części zgód wymaga przeładowania dokumentu, aby usunąć ich działający kod.

Nasłuchuj na window zdarzenia biscotti:beforereload. Zamrożony BeforeReloadDetail zawiera bieżący SdkSnapshot, reason (choice, storage, expiry lub error) i navigation (reload lub replace). Przy jawnym wyborze zapis preferencji, aktualizacja Consent Mode, zamknięcie bramek i consentchange poprzedzają to zdarzenie. Przy awaryjnej odmowie SDK najpierw odmawia lokalnie, próbuje zaktualizować Consent Mode i usunąć zapis (synchronizacja kart nie usuwa wyboru innej karty), emituje consentchange, jeśli stan się zmienił, oraz ewentualny error, potem beforereload i replace z wymuszoną odmową. Jeśli Consent Mode zawiedzie, bramki pozostają zamknięte, a error informuje o awarii.

Zapisz potrzebny stan aplikacji synchronicznie, np. identyfikator widoku w sessionStorage. Zdarzenie nie jest anulowalne; preventDefault, wyjątek listenera i zwrócony Promise nie anulują nawigacji. SDK nie czeka na operacje asynchroniczne. Kod synchroniczny listenera wykonuje się przed nawigacją. Sygnał dotyczy zmiany lokalnej, innej karty, wygaśnięcia i awaryjnej odmowy; bez wymaganego przeładowania nie występuje. Nie zastępuje kontroli cookies i przetwarzania po stronie serwera. Nie traktuj niepodpisanego cookie jako uwierzytelnienia.

Jeśli wybierzesz „Zostań” w dialogu beforeunload przeglądarki, kolejne wycofanie ponowi sygnał i próbę przeładowania.

<button type="button" data-biscotti-preferences>Ustawienia cookies</button>

window.addEventListener('biscotti:beforereload', ({ detail }) => {
  try {
    sessionStorage.setItem('app:view', document.documentElement.dataset.currentView ?? 'home');
  } catch { /* Storage may be unavailable; consent withdrawal still proceeds. */ }
  document.documentElement.dataset.biscottiReloadReason = detail.reason;
});

CSP, CORS i integralność

Dopuść origin platformy w script-src i connect-src, a fonty /brand/fonts w font-src. Dopuść wybrane integracje zewnętrzne. Adapter inline wymaga odpowiedniego nonce lub hasha CSP; SDK kopiuje nonce skryptu. Aktualny SDK dodaje style do Shadow DOM bez przekazania nonce stylu. Restrykcyjna polityka musi uwzględnić ten styl; sam nonce skryptu nie wystarczy. Nie ma jednego nagłówka CSP pasującego do każdej witryny.

CORS przeglądarki dopuszcza host publikacji, a SDK pomija credentials. To nie jest uwierzytelnienie połączeń serwer–serwer. Wklejasz kod raz. Poprawki skryptu otrzymujesz automatycznie, bez ręcznej wymiany kodu. Dotychczasowe instalacje i WordPress działają tak samo. Automatyczne aktualizacje (zalecane): /consent.js. Przypięta wersja z SRI (zaawansowane): /sdk/<SHA-256>/consent.js, integrity SHA-384, crossorigin="anonymous". Publiczny plik SDK i manifest mają CORS *, ale API nadal sprawdza host witryny. SRI weryfikuje plik JavaScript, nie konfigurację API, fonty ani tagi zewnętrzne. /consent.js pozostaje zmiennym adresem zgodności dla dotychczasowych instalacji i WordPressa; nie przypinaj do niego SRI.

Baner może użyć zwalidowanego cache konfiguracji w localStorage przez 15 minut, osobno dla platformy, klucza i originu. Każdy dokument potwierdza aktualną publikację i host na serwerze; ETag/304 pomija ponowne przesyłanie niezmienionej konfiguracji. Do potwierdzenia akceptacja i opcjonalne skrypty pozostają wyłączone, a odmowa działa od razu. Odmowa podczas awarii usuwa lokalną zgodę; dowód decyzji można wysłać dopiero z aktualną konfiguracją. Zmiana publikacji lub consentEpoch daje nową konfigurację; wycofana publikacja, usunięty host, błędna odpowiedź i awaria usuwają cache oraz blokują granty. Cache nie dodaje opóźnienia uprawnień w nowym dokumencie; żądanie ma limit 8 sekund, po którym pozostaje odmowa. Otwarty dokument zachowuje swój snapshot do następnego załadowania, bez odpytywania w tle, więc nie ma limitu propagacji dla stale otwartej karty. Pierwsza wizyta bez cache nadal czeka na serwer. dev_ omija cache. Bez zmiany kodu instalacji.

Błędy i weryfikacja

Używaj stabilnego code, nie tekstu Error.message. whenReady po błędzie startu odrzuca z BiscottiInitializationError. getLastError zachowuje ostatni błąd także po poprawnym wyborze. phase to initialization lub runtime, niezależnie od stanu inicjalizacji. Awaria wyłącza opcjonalne kategorie. Błąd pobrania pliku SDK obsłuż na elemencie script.

W DevTools sprawdź skrypt, config/host/klucz/CORS, CSP, storage i opublikowane kategorie. Odbierz pierwszą wizytę, odmowę, zgodę częściową i pełną, powrót, drugą kartę, cofnięcie, niedostępne API i storage. Sprawdź brak tagów przed zgodą i po cofnięciu. Tagi GTM i wtyczki WordPress wymagają odbioru w rzeczywistej instalacji.

Wersje i historia zmian

Kontrakt dotyczy API v1 w wydaniu b0449f1, wdrożonym 17.10.2026. apiVersion identyfikuje API, publicationVersion konfigurację witryny, a consentEpoch odnowienie preferencji. Żadne z nich nie jest niezmiennym URL skryptu. Zmiany addytywne zachowują v1; usunięcie metody lub zmiana jej znaczenia wymaga nowej wersji kontraktu.

2026-10-17 — API v1: gotowość, status, ostatni błąd, trzy zdarzenia DOM i zamrożone snapshoty. Zachowano dotychczasowe metody. Sprawdzono odzyskiwanie SPA, jawną fazę błędu i nazwę BiscottiInitializationError.

W16 — Tryb deweloperski. Osobny klucz do testów localhost i stagingu. Dane testowe nie trafiają do raportów produkcyjnych ani rozliczeń.

Automatyczne aktualizacje (zalecane): Wklejasz kod raz. Poprawki skryptu otrzymujesz automatycznie, bez ręcznej wymiany kodu. Dotychczasowe instalacje i WordPress działają tak samo. Przypięta wersja z SRI (zaawansowane): Wybierasz konkretną wersję skryptu. Nie otrzymasz automatycznych poprawek, także bezpieczeństwa. Aby ją zaktualizować, musisz ręcznie wymienić kod. W obu wariantach opublikowane ustawienia banera pobierają się automatycznie.

W20 — Wydania SDK i SRI. /sdk/manifest.json wskazuje bieżące wydanie oraz zachowane wersje. Pole src zawiera niezmienny adres, integrity jego hash SHA-384, a bytes rozmiar pliku. Każde wydanie ma też własny manifest obok skryptu. Adres wydania zawiera SHA-256 treści i jest buforowany przez rok jako immutable. Zmiana konfiguracji witryny nie zmienia tego adresu.

Dla przypiętej wersji z SRI: aby zaktualizować SDK, zapisz poprzedni kod, pobierz nowy kod z panelu lub manifestu i wymień razem src oraz integrity. Zachowaj klucz witryny i crossorigin="anonymous". Sprawdź aktualizację na localhost lub stagingu, w tym gotowość, odmowę, zgodę i cofnięcie. Aby wrócić, przywróć poprzednią parę src/integrity. Starsze wydania nie są nadpisywane ani usuwane przy buildzie. Przypięte wydanie wymaga ręcznej aktualizacji, także poprawek bezpieczeństwa; błędu SRI nie obchodź przez usunięcie integrity.

Hash pliku nie jest apiVersion, publicationVersion ani consentEpoch. Powrót do starszego skryptu nie cofa publikacji ani danych witryny. Archiwum starszego skryptu nie gwarantuje bezterminowej zgodności przyszłego API; przed powrotem sprawdź kontrakt i zachowanie.

W17 — biscotti:beforereload poprzedza wymagany reload/replace po wycofaniu. BeforeReloadDetail = SdkSnapshot + reason + navigation. Kod synchroniczny listenera na window wykonuje się przed nawigacją. SDK nie czeka na operacje asynchroniczne; szczegóły i przykład znajdziesz w sekcji o wycofaniu zgody.

{
  "apiVersion": 1,
  "version": "9c2bc03275827be7431adcc709a295afb1f7778553dbaf3c3c4f8a2df233f702",
  "src": "/sdk/9c2bc03275827be7431adcc709a295afb1f7778553dbaf3c3c4f8a2df233f702/consent.js",
  "integrity": "sha384-VtJRmbHcw1tU2ZG0b1SkNpDBvF0Wk2fuFyZG/CNH7stj+z9FgY8pbYK6eyk5KqmD",
  "bytes": 83837
}