Dokumentace pro integrátory

Instalace HTML

Přidej přesný host, vlož kód, ověř instalaci a publikuj konfiguraci. Kód zkopíruj z Instalace. Nahraď YOUR_SITE_KEY veřejným klíčem a použij adresu platformy: produkce https://biscotti.dev, oddělený dev https://dev.biscotti.dev. Veřejný klíč nedává administrátorský přístup. Jeden SDK vlož do head před integrace; použij jednu metodu na dokument. Běžný aktivní skript může běžet před odloženým SDK, proto použij inertní skripty. V patičce zachovej nastavení cookies.

Automatické aktualizace (doporučeno)

Kód vložíš jednou. Opravy skriptu dostáváš automaticky, bez ruční výměny kódu. Stávající instalace a WordPress fungují stejně.

<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

Stáhni ZIP, nainstaluj a aktivuj plugin. V Biscotti → Instalace → WordPress zkopíruj URL platformy a veřejný klíč. Administrátor vytvoří dočasný jednorázový párovací kód. Kód ani přihlašovací údaje nevkládej do HTML. Připoj přesný host, publikuj a odstraň duplicitní instalaci. Párování ani import nepublikují koncept a neblokují automaticky všechny pluginy. Ověř skutečné skripty šablony a pluginů.

Google Tag Manager — Basic

Biscotti nainstaluj mimo kontejner. Odstraň původní GTM kód i iframe noscript. Pod SDK vlož loader a nahraď GTM-XXXXXXX. Čeká na analytický souhlas; smíšený kontejner potřebuje pravidla jednotlivých tagů. Stažený kód patří do Kódu nativní šablony, ne Custom HTML. Povol access_consent write pro sedm signálů, access_globals spuštění Biscotti.onConsentChange, Biscotti.canActivate a dataLayer.push a čtení/zápis dataLayer. Použij Consent Initialization – All Pages a dodatečné souhlasy tagů. Ověř Preview / Tag Assistant. biscotti_consent_update v dataLayer není DOM biscotti:consentchange. Pravidla tagů vyžadují kladnou bránu canActivate. Šablona není 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 připravenost

Přítomnost window.Biscotti ani load neznamená připravenost. Konfigurace se načítá již před DOMContentLoaded; UI čeká na DOM. Ready znamená ověřenou publikaci, vyřešené preference, UI, brány, Consent Mode a poslech druhé karty. Chybějící volba i uložené odmítnutí jsou platné. Nečeká se na audit, zobrazení, písma ani externí tagy. Obnovené adaptéry startují po úvodních událostech; Promise callback může následovat po synchronním adaptéru. ready/error jsou konečné stavy inicializace. Provozní chyba nemění ready. Po chybě startu další volby stále vysílají změny, ale whenReady zůstane odmítnuté.

Události DOM a data

Naslouchej na window před SDK. ready nastane jednou; consentchange přidá reason a error přidá code/phase ke snapshotu. Jde o CustomEvent bez bublání a zrušení. Pozdní posluchač použije whenReady/getConsent/getLastError. Start: stav/GCM/UI → callbacky → ready → úvodní consentchange → adaptéry. Změna: stav → callbacky → consentchange → aktivace nebo reload. Chyba: odmítnutí volitelných → consentchange při změně → error; při chybě startu bez ready. Snapshot i consents jsou zmrazené, bez ID rozhodnutí, cookies, URL návštěvníka a výjimek. hasDecision odlišuje odmítnutí od chybějící volby; metadata jsou null před ověřením. Výjimka posluchače nezastaví vynucování; potvrzení auditu neopakuje události.

W17 — biscotti:beforereload předchází potřebnému reload/replace po odvolání souhlasu. BeforeReloadDetail = SdkSnapshot + reason + navigation. Synchronní kód posluchače na window se provede před navigací. Událost navigaci nezruší; SDK nečeká na asynchronní operace. Pořadí a příklad najdeš v části o odvolání souhlasu.

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

Aplikace SPA

Příklad spusť, když už element script SDK existuje v DOM, před dokončením načtení souboru nebo po něm. SDK vlož jednou do kostry dokumentu. Odebírej změny nezávisle na úspěchu whenReady. Příklad aktualizuje DOM atribut; při odpojení zavolej disconnectBiscotti. whenReady vždy vrací počáteční snapshot; aktuální volbu získáš getConsent nebo odběrem. SPA navigace neinicializuje SDK ani nenačítá novou publikaci. Nové inertní prvky lze aktivovat jednou na prvek. Nenahrazuj window.Biscotti atrapou nebo frontou 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();
}

Adaptéry inertních skriptů

Použij type="text/plain", data-consent-category a pro externí skript data-consent-src místo src. Nahraď vzorovou URL. Volitelné kategorie začínají odmítnuté; prvek běží jednou za dokument po souhlasu. Podporovány jsou klasické inline a HTTP(S) skripty s kopírováním nonce, integrity a crossorigin. Moduly, nomodule, iframe noscript, libovolné pixely a serverové cookies jsou mimo kontrakt. Adaptér kategorie je nezávislý na pauze pravidel; canActivate kontroluje publikované pravidlo, nespouští tag. Smíšené tagy ověř samostatně.

<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 a Google Consent Mode

Volitelné signály začínají denied, security_storage granted; aktualizují se podle tabulky. Režim je Basic, bez automatické instalace GA/GTM či Advanced. performance a unclassified nemají vlastní Google signál: vynucuj kategorii nebo kladnou bránu publikovaného pravidla. Chybějící signál není povolení. Vypnuté kategorie nelze udělit. GTM potřebuje dodatečné souhlasy i příslušné brány.

performance zahrnuje technické měření: rychlost načítání a stabilitu webu. Návštěvnost, chování návštěvníků, GA4 a Clarity zařaď do analytics; měření kampaní a remarketing do advertising, i když nástroj měří také rychlost. Rozhoduje skutečný účel; nástroj s více účely rozděl nebo vyžaduj všechny příslušné souhlasy. performance a unclassified nemají nativní signál Google. Samotné performance neuděluje analytics_storage ani reklamní souhlasy. Skripty podmiň touto kategorií nebo kladnou bránou publikovaného pravidla; chybějící signál není povolení. V GTM vyžaduj biscottiPerformance rovná se true a u pravidla také jeho kladnou bránu. Nevytvářej performance_storage. Význam uložených souhlasů se nemění; tato oprava nevyžaduje nové rozhodnutí. Při změně účelu nebo rozsahu publikuj s obnovením souhlasů.

Google Consent Mode · Tag Assistant

Domény a testování

Publikace platí pro přesný hostname: example.com, www.example.com a shop.example.com jsou různé. SDK a CORS porovnávají host; klíč kontrolu neobejde. Preference jsou host-only, bez automatického sdílení subdomén. Dev a produkce mají oddělená data. Výjimka localhost ani propojený staging v jedné licenci zatím nejsou. Playground nemá zvláštní oprávnění; localhost na hostované platformě nemusí projít ověřením. Použij dostupný testovací host s ověřenou publikací. Nová publikace se načte v novém dokumentu.

Samostatný klíč pro localhost a staging. Testovací data nepatří do produkčních přehledů ani fakturace. Nejprve ulož koncept a schval informace o cookies. Kopie používá tato data a poslední publikovaná pravidla (před publikací žádná). Každé uložení obnovuje testovací souhlas. Localhost, 127.0.0.1 a [::1] vyžadují přesný port. Staging vyžaduje HTTPS na portu 443 a ověření instalace s testovacím klíčem. Produkční host je vyloučen.

V panelu vyber Instalace → Vývojářský režim → Uložit testovací konfiguraci, přidej http://localhost:5173 a zkopíruj kód dev_. Příklad spusť na tomto originu s hostovanou platformou Biscotti, bez místní instalace platformy. Produkční data a klíč site_ zůstávají oddělené. Pro staging přidej přesný HTTPS origin, vlož testovací kód na hlavní stránku a ověř instalaci. Ověření nepřistupuje k soukromým adresám.

Preference a fronta jsou odděleny klíčem a originem včetně portu. Snapshoty a události přidávají environment: development; banner označuje test. Vypnutí, odebrání originu či obnova klíče blokuje další požadavky; otevřené dokumenty obnov. Klíč je veřejný: Origin omezuje prohlížeče, neověřuje servery. Adaptéry po souhlasu spouštějí skutečné integrace: použij testovací účty. Nevzniká další licencovaná stránka ani propojený staging. Obnova smaže jen testovací data a vyžaduje nové ověření stagingu.

Limity: 10 originů, 20 konfigurací, 1000 rozhodnutí a 1000 zobrazení. Obnov klíč pro nový test.

Veřejný staging musí být vlastní subdoménou produkční domény, např. staging.example.com pro example.com nebo www.example.com (vynechává se pouze jedno úvodní www.); pro testy na jiné doméně přidej samostatnou 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>

Změna a odvolání souhlasu

Ponech tento ovládací prvek v zápatí webu. openPreferences otevře nastavení bez udělení souhlasu. Pokud SDK spustilo adaptéry, i částečné odvolání vyžaduje nové načtení dokumentu pro odstranění jejich běžícího kódu.

Na window poslouchej biscotti:beforereload. Zmrazený BeforeReloadDetail obsahuje aktuální SdkSnapshot, reason (choice, storage, expiry nebo error) a navigation (reload nebo replace). Při výslovné volbě události předchází uložení preferencí, aktualizace Consent Mode, uzavření bran a consentchange. Nouzové odmítnutí nejprve odmítne lokálně, pokusí se aktualizovat Consent Mode a smazat preference (synchronizace karet nemaže volbu jiné karty), odešle consentchange při změně a případný error, pak beforereload a replace s vynuceným odmítnutím. Pokud Consent Mode selže, brány zůstanou zavřené a error ohlásí chybu.

Ulož stav aplikace synchronně, například identifikátor zobrazení do sessionStorage. Událost nelze zrušit; preventDefault, výjimka posluchače ani vrácený Promise nezruší navigaci. SDK nečeká na asynchronní operace. Synchronní kód posluchače se provede před navigací. Signál pokrývá místní změnu, jinou kartu, vypršení a nouzové odmítnutí; bez potřebného načtení nevzniká. Serverové cookies a zpracování potřebují vlastní kontroly. Nepodepsané cookie není autentizace.

Pokud v dialogu beforeunload prohlížeče zvolíš zůstat, další odvolání zopakuje signál a pokus o načtení.

<button type="button" data-biscotti-preferences>Nastavení 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

Povol origin platformy v script-src/connect-src, /brand/fonts ve font-src a potřebné integrace. Inline adaptéry potřebují CSP nonce/hash; nonce skriptu se kopíruje. SDK vkládá styl do Shadow DOM bez nonce stylu: přísná politika to musí zohlednit, nonce skriptu nestačí. Univerzální CSP hlavička neexistuje. CORS přijímá host publikace; SDK vynechává credentials a CORS neověřuje servery. Kód vložíš jednou. Opravy skriptu dostáváš automaticky, bez ruční výměny kódu. Stávající instalace a WordPress fungují stejně. Automatické aktualizace (doporučeno): /consent.js. Připnutá verze se SRI (pokročilé): /sdk/<SHA-256>/consent.js, integrity SHA-384, crossorigin="anonymous". Veřejný SDK a manifesty povolují CORS *, API nadále ověřuje host webu. SRI ověřuje JavaScript, ne konfiguraci API, fonty ani externí tagy. /consent.js zůstává proměnlivou adresou pro stávající instalace a WordPress; nepřipínej k ní SRI.

Banner může 15 minut používat ověřenou konfiguraci v localStorage, odděleně pro platformu, klíč a origin. Každý dokument ověří aktuální publikaci a host na serveru; ETag/304 zabrání opakovanému přenosu stejné konfigurace. Přijetí a volitelné skripty zůstávají do ověření vypnuté, odmítnutí funguje ihned. Odmítnutí při výpadku zruší místní souhlas; audit potřebuje aktuální konfiguraci. Publikace či změna consentEpoch vrátí novou konfiguraci; stažení publikace, odstraněný host a chyby vymažou cache a zamítnou oprávnění. Cache nepřidává zpoždění oprávnění v novém dokumentu; po 8 sekundách bez odpovědi zůstává odmítnutí. Otevřený dokument ponechá snapshot do dalšího načtení, bez pravidelných dotazů; pro stále otevřenou kartu není lhůta propagace. První návštěva bez cache čeká na server. dev_ cache obchází. Instalační kód nemusíš měnit.

Chyby a ověření

Používej stabilní code, ne Error.message. whenReady při chybě startu odmítne s BiscottiInitializationError; getLastError zachovává poslední chybu i po úspěšné volbě. phase je initialization/runtime nezávisle na konečném stavu. Chyba odmítne volitelné kategorie. Chybu stažení SDK řeš na script. V DevTools ověř Network/Console, host, klíč, CORS, CSP, úložiště a publikaci. Testuj první návštěvu, odmítnutí, částečný/plný souhlas, návrat, druhou kartu, odvolání a výpadek API/storage. Skutečné GTM tagy a WordPress pluginy ověř zvlášť.

Verze a historie

API v1 z vydání b0449f1, nasazeného 2026-10-17. apiVersion je kontrakt, publicationVersion konfigurace a consentEpoch obnova preferencí. Nejde o neměnné URL skriptu. Aditivní změny zachovávají v1; odstranění metody nebo změna významu vyžaduje nový kontrakt.

2026-10-17 — Připravenost, stav, poslední chyba, tři DOM události a zmrazené snapshoty; dosavadní metody zachovány. Ověřena obnova SPA, explicitní fáze a název BiscottiInitializationError.

W16 — Vývojářský režim. Samostatný klíč pro localhost a staging. Testovací data nepatří do produkčních přehledů ani fakturace.

Automatické aktualizace (doporučeno): Kód vložíš jednou. Opravy skriptu dostáváš automaticky, bez ruční výměny kódu. Stávající instalace a WordPress fungují stejně. Připnutá verze se SRI (pokročilé): Volíš konkrétní verzi skriptu. Nedostaneš automatické opravy včetně bezpečnostních. Při aktualizaci musíš kód ručně vyměnit. Publikovaná nastavení banneru se v obou režimech načítají automaticky.

W20 — Vydání SDK a SRI. /sdk/manifest.json uvádí aktuální i zachovaná vydání. src je neměnná adresa, integrity její SHA-384 hash a bytes velikost souboru. Každé vydání má manifest také vedle skriptu. Adresa obsahuje SHA-256 obsahu a roční cache immutable; změna konfigurace ji nemění.

U připnuté verze se SRI si při aktualizaci ulož starý kód a vyměň společně src i integrity podle panelu nebo manifestu. Zachovej klíč a crossorigin="anonymous". Na localhost nebo stagingu ověř připravenost, odmítnutí, souhlas i odvolání. Při návratu obnov původní dvojici src/integrity. Build stará vydání nepřepisuje ani neodstraňuje. Připnutá vydání vyžadují ruční aktualizace včetně bezpečnostních; chybu SRI neobcházej odstraněním integrity. Hash není apiVersion, publicationVersion ani consentEpoch. Návrat skriptu nevrací publikace ani data; nejdřív ověř kompatibilitu API.

W17 — biscotti:beforereload předchází potřebnému reload/replace po odvolání souhlasu. BeforeReloadDetail = SdkSnapshot + reason + navigation. Synchronní kód posluchače na window se provede před navigací. Událost navigaci nezruší; SDK nečeká na asynchronní operace. Pořadí a příklad najdeš v části o odvolání souhlasu.

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