Dokumentácia pre integrátorov

Inštalácia HTML

Pridaj presný host, vlož kód, over inštaláciu a publikuj konfiguráciu. Kód skopíruj z Inštalácie. Nahraď YOUR_SITE_KEY verejným kľúčom a použi adresu platformy: produkcia https://biscotti.dev, samostatný dev https://dev.biscotti.dev. Verejný kľúč nie je administrátorské oprávnenie. Jeden SDK vlož do head pred integrácie; použi jeden spôsob na dokument. Bežný aktívny skript môže bežať pred odloženým SDK, preto použi inertné skripty. V päte zachovaj nastavenia cookies.

Automatické aktualizácie (odporúčané)

Kód vložíš raz. Opravy skriptu dostávaš automaticky, bez ručnej výmeny kódu. Existujúce inštalácie a WordPress fungujú rovnako.

<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

Stiahni ZIP, nainštaluj a aktivuj doplnok. V Biscotti → Inštalácia → WordPress skopíruj URL platformy a verejný kľúč. Administrátor vytvorí dočasný jednorazový párovací kód. Kód a prístupové údaje nedávaj do HTML. Pripoj presný host, publikuj a odstráň duplicitnú inštaláciu. Párovanie ani import nepublikujú návrh a neblokujú automaticky všetky doplnky. Over skutočné skripty témy a doplnkov.

Google Tag Manager — Basic

Biscotti nainštaluj mimo kontajnera. Odstráň pôvodný kód GTM aj iframe noscript. Pod SDK vlož loader a nahraď GTM-XXXXXXX. Čaká na analytický súhlas; zmiešaný kontajner potrebuje pravidlá každej značky. Stiahnutý kód patrí do Kódu natívnej šablóny, nie Custom HTML. Povoľ access_consent write pre sedem signálov, access_globals vykonanie Biscotti.onConsentChange, Biscotti.canActivate a dataLayer.push a čítanie/zápis dataLayer. Použi Consent Initialization – All Pages a dodatočné súhlasy značiek. Over Preview / Tag Assistant. biscotti_consent_update v dataLayer nie je DOM biscotti:consentchange. Pravidlá značiek vyžadujú kladnú bránku canActivate. Šablóna nie je v 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 a pripravenosť

Prítomnosť window.Biscotti ani load neznamená pripravenosť. Konfigurácia sa načítava už pred DOMContentLoaded; UI čaká na DOM. Ready znamená overenú publikáciu, vyriešené preferencie, UI, bránky, Consent Mode a počúvanie druhej karty. Žiadna voľba aj uložené odmietnutie sú platné stavy. Nečaká sa na audit, zobrazenia, písma ani externé značky. Obnovené adaptéry štartujú po úvodných udalostiach; Promise callback môže nasledovať po synchrónnom adaptéri. ready/error sú konečné stavy inicializácie. Prevádzková chyba nemení ready. Po chybe štartu ďalšie voľby stále vysielajú zmeny, ale whenReady zostáva odmietnuté.

Udalosti DOM a údaje

Počúvaj na window pred SDK. ready nastane raz; consentchange pridá reason a error pridá code/phase k snapshotu. Sú to CustomEvent bez bublania a zrušenia. Neskorý poslucháč použije whenReady/getConsent/getLastError. Štart: stav/GCM/UI → callbacky → ready → úvodné consentchange → adaptéry. Zmena: stav → callbacky → consentchange → aktivácia alebo reload. Chyba: odmietnutie voliteľných → consentchange pri zmene → error; pri chybe štartu bez ready. Snapshot aj consents sú zmrazené, bez ID rozhodnutia, cookies, URL návštevníka a výnimiek. hasDecision rozlišuje odmietnutie od chýbajúcej voľby; pred overením sú metadáta null. Výnimka poslucháča nezastaví vynucovanie; potvrdenie auditu neopakuje udalosti.

W17 — biscotti:beforereload predchádza potrebnému reload/replace po odvolaní súhlasu. BeforeReloadDetail = SdkSnapshot + reason + navigation. Synchrónny kód poslucháča na window sa vykoná pred navigáciou. Udalosť navigáciu nezruší; SDK nečaká na asynchrónne operácie. Poradie a príklad sú v časti o odvolaní súhlasu.

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';
};

Aplikácie SPA

Príklad spusti, keď už element script SDK existuje v DOM, pred dokončením načítania súboru alebo po ňom. SDK vlož raz do kostry dokumentu. Zmeny odoberaj nezávisle od úspechu whenReady. Príklad aktualizuje DOM atribút; pri odpojení zavolaj disconnectBiscotti. whenReady vždy vracia úvodný snapshot; aktuálnu voľbu získaj cez getConsent alebo odber. SPA navigácia neinicializuje SDK ani nenačíta novú publikáciu. Nové inertné prvky sa môžu aktivovať raz na prvok. Nenahrádzaj window.Biscotti atrapou alebo frontom metód.

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();
}

Adaptéry inertných skriptov

Použi type="text/plain", data-consent-category a pri externom skripte data-consent-src namiesto src. Nahraď vzorovú URL. Voliteľné kategórie začínajú odmietnuté; prvok beží raz na dokument po súhlase. Podporované sú klasické inline a HTTP(S) skripty, s kopírovaním nonce, integrity a crossorigin. Moduly, nomodule, iframe noscript, ľubovoľné pixely a serverové cookies sú mimo kontraktu. Adaptér kategórie je nezávislý od pauzy pravidiel; canActivate kontroluje publikované pravidlo a nespúšťa značku. Zmiešané značky over osobitne.

<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>

Kategórie a Google Consent Mode

Voliteľné signály začínajú denied, security_storage granted. Aktualizujú sa podľa tabuľky. Režim je Basic, bez automatickej inštalácie GA/GTM či Advanced. performance a unclassified nemajú vlastný Google signál: vynucuj kategóriu alebo kladnú bránku publikovaného pravidla. Chýbajúci signál nedáva povolenie. Vypnuté kategórie nemožno udeliť. GTM potrebuje dodatočné súhlasy aj príslušné bránky.

performance zahŕňa technické meranie: rýchlosť načítania a stabilitu webu. Návštevnosť, správanie návštevníkov, GA4 a Clarity zaraď do analytics; meranie kampaní a remarketing do advertising, aj keď nástroj meria aj rýchlosť. Rozhoduje skutočný účel; nástroj s viacerými účelmi rozdeľ alebo vyžaduj všetky príslušné súhlasy. performance a unclassified nemajú natívny signál Google. Samotné performance neudeľuje analytics_storage ani reklamné súhlasy. Skripty podmieň touto kategóriou alebo kladnou bránkou publikovaného pravidla; chýbajúci signál nie je povolenie. V GTM vyžaduj biscottiPerformance rovná sa true a pri pravidle aj jeho kladnú bránku. Nevytváraj performance_storage. Význam uložených súhlasov sa nemení; táto oprava nevyžaduje nové rozhodnutie. Pri zmene účelu alebo rozsahu publikuj s obnovením súhlasov.

Google Consent Mode · Tag Assistant

Domény a testovanie

Publikácia platí pre presný hostname. example.com, www.example.com a shop.example.com sú odlišné. SDK a CORS porovnávajú host; kľúč kontrolu neobíde. Preferencie sú host-only, bez automatického zdieľania subdomén. Dev a produkcia majú oddelené dáta. Výnimka localhost ani prepojený staging v jednej licencii zatiaľ nie sú. Playground nemá osobitné oprávnenia; localhost na hostovanej platforme nemusí prejsť overením. Použi dostupný testovací host s overenou publikáciou. Nová publikácia sa načíta v novom dokumente.

Samostatný kľúč pre localhost a staging. Testovacie údaje nepatria do produkčných prehľadov ani fakturácie. Najprv ulož koncept a schváľ informácie o cookies. Kópia používa tieto údaje a posledné publikované pravidlá (pred publikáciou žiadne). Každé uloženie obnovuje testovací súhlas. Localhost, 127.0.0.1 a [::1] vyžadujú presný port. Staging vyžaduje HTTPS na porte 443 a overenie inštalácie s testovacím kľúčom. Produkčný host je vylúčený.

V paneli vyber Inštalácia → Vývojársky režim → Uložiť testovaciu konfiguráciu, pridaj http://localhost:5173 a skopíruj kód dev_. Príklad spusti na tomto origine s hostovanou platformou Biscotti, bez lokálnej inštalácie platformy. Produkčné údaje a kľúč site_ zostávajú oddelené. Pre staging pridaj presný HTTPS origin, vlož testovací kód na hlavnú stránku a over inštaláciu. Overenie nepristupuje k súkromným adresám.

Preferencie a front sú oddelené kľúčom a originom vrátane portu. Snapshoty a udalosti pridávajú environment: development; banner označuje test. Vypnutie, odstránenie originu alebo obnova kľúča blokuje ďalšie požiadavky; otvorené dokumenty obnov. Kľúč je verejný: Origin obmedzuje prehliadače, neoveruje servery. Adaptéry po súhlase spúšťajú skutočné integrácie: použi testovacie účty. Nevzniká ďalšia licencovaná stránka ani prepojený staging. Obnova vymaže len testovacie údaje a vyžaduje nové overenie stagingu.

Limity: 10 originov, 20 konfigurácií, 1000 rozhodnutí a 1000 zobrazení. Obnov kľúč pre nový test.

Verejný staging musí byť vlastnou subdoménou produkčnej domény, napr. staging.example.com pre example.com alebo www.example.com (vynecháva sa iba jedno úvodné www.); pre testy na inej doméne pridaj samostatnú stránku.

<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>

Zmena a odvolanie súhlasu

Ponechaj tento ovládací prvok v päte webu. openPreferences otvorí nastavenia bez udelenia súhlasu. Ak SDK spustil adaptéry, aj čiastočné odvolanie vyžaduje opätovné načítanie dokumentu na odstránenie ich bežiaceho kódu.

Na window počúvaj biscotti:beforereload. Zmrazený BeforeReloadDetail obsahuje aktuálny SdkSnapshot, reason (choice, storage, expiry alebo error) a navigation (reload alebo replace). Pri výslovnej voľbe uloženiu preferencií, aktualizácii Consent Mode, zatvoreniu brán a consentchange nasleduje táto udalosť. Núdzové odmietnutie najprv odmietne lokálne, pokúsi sa aktualizovať Consent Mode a vymazať preferencie (synchronizácia kariet nemaže voľbu inej karty), odošle consentchange pri zmene a prípadný error, potom beforereload a replace s vynúteným odmietnutím. Ak Consent Mode zlyhá, brány zostanú zatvorené a error oznámi chybu.

Ulož stav aplikácie synchrónne, napríklad identifikátor zobrazenia do sessionStorage. Udalosť sa nedá zrušiť; preventDefault, výnimka poslucháča ani vrátený Promise nezrušia navigáciu. SDK nečaká na asynchrónne operácie. Synchrónny kód poslucháča sa vykoná pred navigáciou. Signál pokrýva lokálnu zmenu, inú kartu, vypršanie a núdzové odmietnutie; bez potrebného načítania nevzniká. Serverové cookies a spracovanie potrebujú vlastné kontroly. Nepodpísané cookie nie je autentifikácia.

Ak v dialógu beforeunload prehliadača zvolíš zostať, ďalšie odvolanie zopakuje signál a pokus o načítanie.

<button type="button" data-biscotti-preferences>Nastavenia 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 a integrita

Povoľ origin platformy v script-src/connect-src, /brand/fonts vo font-src a potrebné integrácie. Inline adaptéry potrebujú CSP nonce/hash; nonce skriptu sa kopíruje. SDK vkladá štýl do Shadow DOM bez nonce štýlu: prísna politika s tým musí počítať, nonce skriptu nestačí. Univerzálna CSP hlavička nie je. CORS prijíma host publikácie; SDK vynecháva credentials a CORS neautentifikuje servery. Kód vložíš raz. Opravy skriptu dostávaš automaticky, bez ručnej výmeny kódu. Existujúce inštalácie a WordPress fungujú rovnako. Automatické aktualizácie (odporúčané): /consent.js. Pripnutá verzia so SRI (pokročilé): /sdk/<SHA-256>/consent.js, integrity SHA-384, crossorigin="anonymous". Verejný SDK a manifesty povoľujú CORS *, API naďalej overuje host webu. SRI overuje JavaScript, nie konfiguráciu API, fonty ani externé tagy. /consent.js zostáva premenlivou adresou pre existujúce inštalácie a WordPress; nepripínaj k nej SRI.

Banner môže 15 minút používať overenú konfiguráciu v localStorage, oddelene pre platformu, kľúč a origin. Každý dokument overí aktuálnu publikáciu a host na serveri; ETag/304 zabráni opakovanému prenosu rovnakej konfigurácie. Prijatie a voliteľné skripty zostávajú do overenia vypnuté, odmietnutie funguje hneď. Odmietnutie pri výpadku zruší miestny súhlas; audit potrebuje aktuálnu konfiguráciu. Publikácia alebo zmena consentEpoch vráti novú konfiguráciu; stiahnutie publikácie, odstránený host a chyby vymažú cache a zamietnu povolenia. Cache nepridáva oneskorenie oprávnení v novom dokumente; po 8 sekundách bez odpovede zostáva odmietnutie. Otvorený dokument ponechá snapshot do ďalšieho načítania, bez pravidelných dopytov; pre stále otvorenú kartu neexistuje lehota propagácie. Prvá návšteva bez cache čaká na server. dev_ cache obchádza. Inštalačný kód nemusíš meniť.

Chyby a overenie

Používaj stabilný code, nie Error.message. whenReady pri chybe štartu odmietne s BiscottiInitializationError; getLastError uchová poslednú chybu aj po úspešnej voľbe. phase je initialization/runtime nezávisle od konečného stavu. Chyba odmietne voliteľné kategórie. Chybu stiahnutia SDK obslúž na script. V DevTools over Network/Console, host, kľúč, CORS, CSP, úložisko a publikáciu. Testuj prvú návštevu, odmietnutie, čiastočný/plný súhlas, návrat, druhú kartu, odvolanie a výpadok API/storage. Skutočné GTM značky a WordPress doplnky over osobitne.

Verzie a história

API v1 z vydania b0449f1, nasadeného 2026-10-17. apiVersion je kontrakt, publicationVersion konfigurácia a consentEpoch obnovenie preferencií. Nie sú to nemenné URL skriptu. Aditívne zmeny zachovávajú v1; odstránenie metódy alebo zmena významu potrebuje nový kontrakt.

2026-10-17 — Pripravenosť, stav, posledná chyba, tri DOM udalosti a zmrazené snapshoty; staršie metódy zachované. Overená obnova SPA, explicitná fáza a názov BiscottiInitializationError.

W16 — Vývojársky režim. Samostatný kľúč pre localhost a staging. Testovacie údaje nepatria do produkčných prehľadov ani fakturácie.

Automatické aktualizácie (odporúčané): Kód vložíš raz. Opravy skriptu dostávaš automaticky, bez ručnej výmeny kódu. Existujúce inštalácie a WordPress fungujú rovnako. Pripnutá verzia so SRI (pokročilé): Vyberáš konkrétnu verziu skriptu. Nedostaneš automatické opravy vrátane bezpečnostných. Pri aktualizácii musíš kód ručne vymeniť. Publikované nastavenia bannera sa v oboch režimoch načítajú automaticky.

W20 — Vydania SDK a SRI. /sdk/manifest.json uvádza aktuálne aj zachované vydania. src je nemenná adresa, integrity jej SHA-384 hash a bytes veľkosť súboru. Každé vydanie má manifest aj vedľa skriptu. Adresa obsahuje SHA-256 obsahu a ročnú cache immutable; zmena konfigurácie ju nemení.

Pri pripnutej verzii so SRI si pri aktualizácii ulož starý kód a vymeň spolu src aj integrity podľa panela alebo manifestu. Zachovaj kľúč a crossorigin="anonymous". Na localhost alebo stagingu over pripravenosť, odmietnutie, súhlas aj odvolanie. Pri návrate obnov pôvodnú dvojicu src/integrity. Build staré vydania neprepisuje ani neodstraňuje. Pripnuté vydania vyžadujú ručné aktualizácie vrátane bezpečnostných; chybu SRI neobchádzaj odstránením integrity. Hash nie je apiVersion, publicationVersion ani consentEpoch. Návrat skriptu nevracia publikácie ani dáta; najprv over kompatibilitu API.

W17 — biscotti:beforereload predchádza potrebnému reload/replace po odvolaní súhlasu. BeforeReloadDetail = SdkSnapshot + reason + navigation. Synchrónny kód poslucháča na window sa vykoná pred navigáciou. Udalosť navigáciu nezruší; SDK nečaká na asynchrónne operácie. Poradie a príklad sú v časti o odvolaní súhlasu.

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