Dokumentation für Integratoren

HTML-Installation

Füge den genauen Host hinzu, installiere den Code, bestätige die Installation und veröffentliche die Konfiguration. Kopiere den Code aus Installation. Ersetze YOUR_SITE_KEY durch den öffentlichen Schlüssel und verwende deinen Plattform-Origin: Produktion https://biscotti.dev, separates Dev https://dev.biscotti.dev. Der Schlüssel gewährt keinen Administrationszugriff. Ein SDK gehört in head vor die Integrationen; nutze eine Installationsmethode pro Dokument. Aktive Skripte können vor dem verzögerten SDK laufen: markiere sie als inaktiv. Behalte Cookie-Einstellungen dauerhaft im Footer.

Automatische Updates (empfohlen)

Füge den Code einmal ein. Skriptkorrekturen erhältst du automatisch, ohne den Code manuell zu ersetzen. Bestehende Installationen und WordPress funktionieren genauso.

<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

Lade das ZIP herunter, installiere und aktiviere das Plugin. Kopiere in Biscotti → Installation → WordPress die Plattform-URL und den öffentlichen Schlüssel ins Plugin. Ein Administrator erstellt einen zeitlich begrenzten Einmalcode zur Kopplung. Codes und Zugangsdaten gehören nicht ins HTML. Verbinde den genauen Host, veröffentliche und entferne doppelte SDK-Installationen. Kopplung und Import veröffentlichen keinen Entwurf und blockieren nicht automatisch alle Plugins. Prüfe die tatsächlichen Skripte von Theme und Plugins.

Google Tag Manager — Basic

Installiere Biscotti außerhalb des Containers. Entferne den normalen GTM-Code und das noscript-iframe. Füge den Loader unter dem SDK ein und ersetze GTM-XXXXXXX. Er wartet auf Analyse-Einwilligung; gemischte Container brauchen Regeln je Tag. Füge die heruntergeladene Vorlage im Code-Tab einer nativen GTM-Vorlage ein, nicht in Custom HTML. Erlaube access_consent write für die sieben Signale, access_globals-Ausführung von Biscotti.onConsentChange, Biscotti.canActivate und dataLayer.push sowie Lesen/Schreiben von dataLayer. Nutze Consent Initialization – All Pages und zusätzliche Einwilligungen je Tag. Prüfe Preview / Tag Assistant. biscotti_consent_update in dataLayer ist nicht das DOM-Ereignis biscotti:consentchange. Veröffentlichte Regeln benötigen ein positives canActivate-Gate. Die Vorlage steht nicht in der 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 und Bereitschaft

window.Biscotti oder load bedeuten noch keine Bereitschaft. Die Konfiguration wird vor DOMContentLoaded geladen; die UI wartet auf das DOM. Ready bedeutet validierte Veröffentlichung, geklärte Präferenzen, UI, Gates, Consent Mode und Tab-Synchronisierung. Keine Wahl und gespeicherte Ablehnung sind gültig. Audit, Seitenaufrufe, Schriften und externe Tags werden nicht abgewartet. Wiederhergestellte Adapter starten nach den Anfangsereignissen; Promise-Callbacks können nach synchronen Adaptern laufen. ready/error sind endgültige Initialisierungszustände. Laufzeitfehler ändern ready nicht. Nach einem Startfehler werden spätere Entscheidungen weiterhin gemeldet; whenReady bleibt abgelehnt.

DOM-Ereignisse und Daten

Lausche vor dem SDK auf window. ready erscheint einmal; consentchange ergänzt reason und error ergänzt code/phase zum Snapshot. CustomEvent ohne Bubbling oder Abbruch. Späte Listener verwenden whenReady/getConsent/getLastError. Start: Zustand/GCM/UI → Callbacks → ready → anfängliches consentchange → Adapter. Änderung: Zustand → Callbacks → consentchange → Aktivierung oder Neuladen. Fehler: optionale Ablehnung → consentchange bei Änderung → error; Startfehler ohne ready. Snapshot und consents sind eingefroren, ohne Entscheidungs-ID, Cookie-Wert, Besucher-URL oder rohe Ausnahme. hasDecision unterscheidet Ablehnung von fehlender Wahl; Metadaten sind vor Validierung null. Listener-Ausnahmen stoppen die Durchsetzung nicht; Audit-Bestätigungen wiederholen kein Änderungsereignis.

W17 — biscotti:beforereload kommt vor dem erforderlichen reload/replace nach einem Widerruf. BeforeReloadDetail = SdkSnapshot + reason + navigation. Synchroner Listener-Code auf window läuft vor der Navigation. Das Ereignis kann die Navigation nicht abbrechen; das SDK wartet nicht auf asynchrone Arbeit. Reihenfolge und Beispiel stehen im Abschnitt zum Widerruf.

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

SPA-Anwendungen

Führe das Beispiel aus, sobald das SDK-script-Element im DOM steht, vor oder nach Abschluss des Datei-Ladens. Installiere das SDK einmal in der Dokumenthülle. Abonniere unabhängig vom Erfolg von whenReady. Das Beispiel aktualisiert ein DOM-Attribut; rufe beim Unmount disconnectBiscotti auf. whenReady liefert immer den anfänglichen Snapshot; aktuelle Präferenzen liest du über getConsent oder das Abonnement. SPA-Navigation initialisiert nicht neu und lädt keine neue Veröffentlichung. Neue inaktive Elemente können einmal je Element starten. Ersetze window.Biscotti nicht durch einen Platzhalter oder eine Methodenwarteschlange.

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

Adapter für inaktive Skripte

Nutze type="text/plain", data-consent-category und für externe Skripte data-consent-src statt src. Ersetze die Beispiel-URL. Optionale Kategorien beginnen abgelehnt; ein Element startet einmal pro Dokument nach Einwilligung. Unterstützt sind klassische Inline- und HTTP(S)-Skripte; nonce, integrity und crossorigin werden kopiert. Module, nomodule, noscript-iframes, beliebige Pixel und Server-Cookies liegen außerhalb des Vertrags. Kategorieadapter sind unabhängig von Regelpausen; canActivate prüft die veröffentlichte Regel und startet keinen Tag. Gemischte Tags brauchen eine eigene Prüfung.

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

Kategorien und Google Consent Mode

Optionale Signale beginnen denied, security_storage granted; die Tabelle zeigt die Zuordnung. Der Modus ist Basic, ohne automatische GA/GTM-Installation oder Advanced. performance und unclassified haben kein natives Google-Signal: erzwinge die Kategorie oder ein positives veröffentlichtes Regel-Gate. Ein fehlendes Signal ist keine Erlaubnis. Deaktivierte Kategorien können nicht erteilt werden. GTM braucht zusätzliche Einwilligungen und passende Gates.

performance umfasst technische Messungen: Ladegeschwindigkeit und Stabilität der Website. Ordne Besucherzahlen, Besucherverhalten, GA4 und Clarity analytics zu; Kampagnenmessung und Remarketing advertising, auch wenn das Tool die Geschwindigkeit misst. Entscheidend ist der tatsächliche Zweck; trenne Tools mit mehreren Zwecken oder verlange alle passenden Einwilligungen. performance und unclassified haben kein natives Google-Signal. performance allein erteilt weder analytics_storage noch Werbeeinwilligungen. Verlange für Skripte diese Kategorie oder ein positives Gate der veröffentlichten Regel; ein fehlendes Signal ist keine Erlaubnis. Verlange in GTM biscottiPerformance gleich true und bei Regeln zusätzlich deren positives Gate. Erfinde kein performance_storage. Gespeicherte Einwilligungen behalten ihre Bedeutung; diese Korrektur erfordert keine neue Entscheidung. Veröffentliche Änderungen an Zweck oder Umfang mit erneuter Einwilligung.

Google Consent Mode · Tag Assistant

Domains und Tests

Eine Veröffentlichung gilt für einen genauen Hostnamen: example.com, www.example.com und shop.example.com sind verschieden. SDK und CORS prüfen den Host; der Schlüssel umgeht dies nicht. Präferenzen sind host-only, ohne automatische Subdomain-Freigabe. Dev und Produktion haben getrennte Daten. Localhost-Ausnahme und verknüpftes Staging in einer Lizenz fehlen noch. Playground hat keine Sonderrechte; localhost kann auf der gehosteten Plattform die Verifikation nicht bestehen. Teste einen erreichbaren Host mit verifizierter Veröffentlichung. Eine neue Veröffentlichung wird in einem neuen Dokument geladen.

Separater Schlüssel für localhost und Staging. Testdaten fließen nicht in Produktionsberichte oder Abrechnung ein. Speichere zuerst den Entwurf und bestätige die Cookie-Informationen. Die Kopie nutzt diese Daten und zuletzt veröffentlichte Regeln (vor Veröffentlichung keine). Jedes Speichern erneuert die Testeinwilligung. Localhost, 127.0.0.1 und [::1] benötigen den exakten Port. Staging benötigt HTTPS auf Port 443 und eine Installationsprüfung mit dem Testschlüssel. Der Produktionshost ist ausgeschlossen.

Wähle Installation → Entwicklermodus → Testkonfiguration speichern, füge http://localhost:5173 hinzu und kopiere den dev_-Code. Führe das Beispiel auf diesem Origin mit der gehosteten Biscotti-Plattform aus; eine lokale Plattform ist nicht nötig. Produktionsdaten und site_-Schlüssel bleiben getrennt. Für Staging füge den exakten HTTPS-Origin hinzu, installiere den Testcode auf der Startseite und prüfe die Installation. Die Prüfung greift nicht auf private Adressen zu.

Präferenzen und Warteschlange sind nach Schlüssel und Origin samt Port getrennt. Snapshots und Ereignisse ergänzen environment: development; der Banner zeigt einen Testhinweis. Deaktivieren, Entfernen des Origins oder Erneuern des Schlüssels sperrt weitere Anfragen; lade offene Dokumente neu. Der Schlüssel ist öffentlich: Origin beschränkt Browser, authentifiziert keine Server. Adapter führen nach Einwilligung echte Integrationen aus: nutze Testkonten. Es entsteht keine zusätzliche lizenzierte oder verknüpfte Staging-Website. Erneuern löscht nur Testdaten und erfordert eine neue Staging-Prüfung.

Grenzen: 10 Origins, 20 Konfigurationen, 1000 Entscheidungen und 1000 Seitenaufrufe. Zum Zurücksetzen Schlüssel erneuern.

Öffentliches Staging muss eine echte Subdomain der Produktionsdomain sein, z. B. staging.example.com für example.com oder www.example.com (nur ein führendes www. wird entfernt); füge für Tests auf einer anderen Domain eine separate Website hinzu.

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

Einwilligung ändern und widerrufen

Behalte dieses Element im Seitenfuß. openPreferences öffnet Einstellungen ohne Einwilligung. Sobald SDK-Adapter ausgeführt wurden, erfordert auch ein teilweiser Widerruf das Neuladen des Dokuments, um ihren laufenden Code zu entfernen.

Lausche auf window auf biscotti:beforereload. Das eingefrorene BeforeReloadDetail enthält den aktuellen SdkSnapshot, reason (choice, storage, expiry oder error) und navigation (reload oder replace). Bei einer ausdrücklichen Auswahl erfolgen Speicherung, Consent-Mode-Aktualisierung, Schließen der Freigaben und consentchange vor diesem Ereignis. Eine Notfallverweigerung verweigert zuerst lokal, versucht Consent Mode zu aktualisieren und Einstellungen zu löschen (der Tab-Abgleich löscht keine Auswahl eines anderen Tabs), sendet consentchange bei Änderungen und gegebenenfalls error, dann beforereload und replace mit erzwungener Verweigerung. Bei einem Consent-Mode-Fehler bleiben die Freigaben geschlossen; error meldet den Fehler.

Speichere den Anwendungszustand synchron, etwa eine Ansichtskennung in sessionStorage. Das Ereignis ist nicht abbrechbar; preventDefault, Listener-Ausnahmen und zurückgegebene Promises brechen die Navigation nicht ab. Das SDK wartet nicht auf asynchrone Arbeit. Synchroner Listener-Code läuft vor der Navigation. Das Signal gilt für lokale Änderungen, andere Tabs, Ablauf und Notfallverweigerung; ohne erforderliches Neuladen wird es nicht gesendet. Serverseitige Cookies und Verarbeitung brauchen eigene Prüfungen. Ein unsigniertes Cookie ist keine Authentifizierung.

Wenn du im beforeunload-Dialog des Browsers auf der Seite bleibst, sendet ein späterer Widerruf das Signal erneut und versucht die Navigation nochmals.

<button type="button" data-biscotti-preferences>Cookie-Einstellungen</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 und Integrität

Erlaube den Plattform-Origin in script-src/connect-src, /brand/fonts in font-src und deine Integrationen. Inline-Adapter benötigen CSP-Nonce/Hash; das Skript-Nonce wird kopiert. Der SDK-Stil im Shadow DOM erhält kein Style-Nonce: strikte Richtlinien müssen das berücksichtigen, ein Skript-Nonce genügt nicht. Es gibt keinen universellen CSP-Header. CORS erlaubt den veröffentlichten Host; das SDK lässt credentials weg, CORS authentifiziert keine Server. Füge den Code einmal ein. Skriptkorrekturen erhältst du automatisch, ohne den Code manuell zu ersetzen. Bestehende Installationen und WordPress funktionieren genauso. Automatische Updates (empfohlen): /consent.js. Feste Version mit SRI (erweitert): /sdk/<SHA-256>/consent.js, integrity SHA-384, crossorigin="anonymous". Öffentliche SDK-Dateien und Manifeste erlauben CORS *, die API prüft weiterhin den Website-Host. SRI prüft JavaScript, nicht API-Konfiguration, Schriften oder externe Tags. /consent.js bleibt eine veränderliche Adresse für bestehende Installationen und WordPress; binde dafür keinen SRI-Hash ein.

Das Banner kann geprüfte Konfiguration für 15 Minuten in localStorage nutzen, getrennt nach Plattform, Schlüssel und Origin. Jedes Dokument bestätigt aktuelle Veröffentlichung und Host beim Server; ETag/304 vermeidet die erneute Übertragung unveränderter Konfiguration. Annahme und optionale Skripte bleiben bis zur Bestätigung gesperrt, Ablehnen funktioniert sofort. Ablehnen bei einem Ausfall löscht die lokale Zustimmung; der Audit-Eintrag benötigt aktuelle Konfiguration. Veröffentlichung oder consentEpoch-Änderung liefert neue Konfiguration; Rücknahme, entfernter Host und Fehler löschen den Cache und verweigern Berechtigungen. Der Cache verzögert keine Berechtigungsprüfung in neuen Dokumenten; nach 8 Sekunden ohne Antwort bleibt die Ablehnung. Ein offenes Dokument behält seinen Stand bis zur Navigation ohne regelmäßige Abfragen; für dauerhaft offene Tabs gibt es keine Propagationsfrist. Der erste Besuch ohne Cache wartet auf den Server. dev_ umgeht den Cache. Du musst den Installationscode nicht ändern.

Fehler und Prüfung

Nutze stabile codes statt Error.message. whenReady lehnt beim Startfehler mit BiscottiInitializationError ab; getLastError behält den letzten Fehler auch nach erfolgreicher Wahl. phase ist initialization/runtime unabhängig vom Endzustand. Fehler lehnen optionale Kategorien ab. SDK-Downloadfehler behandelst du am script-Element. Prüfe Network/Console, Host, Schlüssel, CORS, CSP, Speicher und Veröffentlichung. Teste Erstbesuch, Ablehnung, Teil-/Vollzustimmung, Rückkehr, zweiten Tab, Widerruf und API-/Speicherausfall. Echte GTM-Tags und WordPress-Plugins separat prüfen.

Versionen und Verlauf

API v1 aus Release b0449f1, bereitgestellt am 2026-10-17. apiVersion bezeichnet den Vertrag, publicationVersion die Konfiguration und consentEpoch die Erneuerung. Keine davon ist eine unveränderliche Skript-URL. Ergänzungen erhalten v1; Entfernen oder Bedeutungsänderung einer Methode verlangt einen neuen Vertrag.

2026-10-17 — Bereitschaft, Status, letzter Fehler, drei DOM-Ereignisse und eingefrorene Snapshots; bisherige Methoden erhalten. SPA-Wiederherstellung, explizite Phase und Name BiscottiInitializationError geprüft.

W16 — Entwicklermodus. Separater Schlüssel für localhost und Staging. Testdaten fließen nicht in Produktionsberichte oder Abrechnung ein.

Automatische Updates (empfohlen): Füge den Code einmal ein. Skriptkorrekturen erhältst du automatisch, ohne den Code manuell zu ersetzen. Bestehende Installationen und WordPress funktionieren genauso. Feste Version mit SRI (erweitert): Du wählst eine bestimmte Skriptversion. Du erhältst keine automatischen Korrekturen, auch keine Sicherheitskorrekturen. Für ein Update musst du den Code manuell ersetzen. Veröffentlichte Banner-Einstellungen werden in beiden Modi automatisch geladen.

W20 — SDK-Versionen und SRI. /sdk/manifest.json nennt die aktuelle und die erhaltenen Versionen. src ist die unveränderliche URL, integrity ihr SHA-384-Hash und bytes die Dateigröße. Jede Version hat ein Manifest neben dem Skript. Die URL enthält den SHA-256-Inhaltshash und wird ein Jahr als immutable zwischengespeichert; Konfigurationsänderungen ändern sie nicht.

Für eine feste SRI-Version: Speichere vor einem Update den alten Code und ersetze src und integrity gemeinsam aus Panel oder Manifest. Behalte Website-Schlüssel und crossorigin="anonymous". Teste Bereitschaft, Ablehnung, Einwilligung und Widerruf auf localhost oder Staging. Stelle für ein Rollback das vorherige src/integrity-Paar wieder her. Builds überschreiben oder löschen erhaltene Versionen nicht. Gebundene Versionen brauchen manuelle Updates, auch Sicherheitskorrekturen; entferne integrity nicht, um SRI-Fehler zu umgehen. Der Hash ist keine apiVersion, publicationVersion oder consentEpoch. Ein Skript-Rollback setzt Veröffentlichungen und Daten nicht zurück; prüfe vorher die API-Kompatibilität.

W17 — biscotti:beforereload kommt vor dem erforderlichen reload/replace nach einem Widerruf. BeforeReloadDetail = SdkSnapshot + reason + navigation. Synchroner Listener-Code auf window läuft vor der Navigation. Das Ereignis kann die Navigation nicht abbrechen; das SDK wartet nicht auf asynchrone Arbeit. Reihenfolge und Beispiel stehen im Abschnitt zum Widerruf.

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