JavaScript-API

Mit der JavaScript-API kann Ihr eigener Code die Einwilligung lesen und ändern. Dieselbe API steht auf zwei Wegen zur Verfügung:

• Das globale Objekt Cookiesh, das vom Script-Tag erzeugt wird. Nutzen Sie es in reinen HTML-Seiten und in der Browserkonsole.
• Das Paket @cookiesh/js, ein typisierter Wrapper um das globale Objekt für gebündelte Apps. Es funktioniert genauso und enthält TypeScript-Definitionen.

npm install @cookiesh/js

import { cookiesh } from '@cookiesh/js';

Das Paket lädt keine zweite Kopie von Cookiesh. Es wartet auf das Script-Tag und ruft das globale Objekt auf. Alle folgenden Beispiele verwenden das Paket, Cookiesh.ready() und cookiesh.ready() verhalten sich aber identisch.

Einwilligungsstatus

Die meisten Methoden geben ein ConsentState-Objekt zurück oder erwarten eines:

interface ConsentState {
  necessary: true;
  preferences: boolean;
  analytics: boolean;
  marketing: boolean;
  /** Wie der aktuelle Status zustande kam. */
  method: 'default' | 'banner' | 'preferences' | 'api' | 'gpc';
  /** Zufällige ID des gespeicherten Einwilligungsnachweises, oder null vor der ersten Entscheidung. */
  consentId: string | null;
  /** Zeitpunkt der Entscheidung nach ISO 8601, oder null vor der ersten Entscheidung. */
  timestamp: string | null;
  bannerVersion: string;
  /** Region, auf die die Regel zutraf, etwa "FR" oder "US-CA". */
  region: string;
}

Bevor der Besucher eine Entscheidung trifft, ist method gleich default, und die Kategorien entsprechen dem Standardstatus der Region. In Opt-in-Regionen ist damit alles außer necessary false.

Einwilligung lesen

ready()

ready(): Promise<ConsentState>

Wird aufgelöst, sobald Cookiesh den Einwilligungsstatus kennt: bei wiederkehrenden Besuchern sofort, bei neuen nach der Regionserkennung. Es wartet nicht darauf, dass der Besucher im Banner klickt. Starten Sie damit Code, der von der Einwilligung abhängt:

const consent = await cookiesh.ready();
if (consent.analytics) initAnalytics();

getConsent()

getConsent(): ConsentState | null

Gibt den aktuellen Status synchron zurück, oder null, wenn Cookiesh noch nicht fertig geladen ist. Verwenden Sie lieber ready(), es sei denn, Sie sind sicher, dass das Skript geladen ist.

hasConsent(category)

hasConsent(category: 'necessary' | 'preferences' | 'analytics' | 'marketing'): boolean

Eine Abkürzung, um eine einzelne Kategorie zu prüfen. Gibt false zurück, bis Cookiesh geladen ist.

Einwilligung ändern

Diese Methoden speichern einen neuen Einwilligungsnachweis, genau so, als hätte der Besucher das Banner benutzt. Rufen Sie sie nur als Reaktion auf eine eindeutige Handlung des Besuchers auf, etwa einen Klick auf Ihrer eigenen Einstellungsseite.

acceptAll(): Promise<ConsentState>
rejectAll(): Promise<ConsentState>
setConsent(choices: Partial<Record<'preferences' | 'analytics' | 'marketing', boolean>>): Promise<ConsentState>

// Ein eigener Schalter auf Ihrer Seite mit den Kontoeinstellungen
await cookiesh.setConsent({ analytics: event.target.checked });

Kategorien, die Sie weglassen, behalten ihren aktuellen Wert. necessary lässt sich nicht ändern.

Die Oberfläche anzeigen

showBanner(): void
openPreferences(): void
close(): void

showBanner() zeigt das Banner der ersten Ebene erneut an, auch wenn der Besucher bereits entschieden hat. openPreferences() öffnet das Präferenz-Center mit Schaltern pro Kategorie und der Cookie-Übersicht. close() schließt beides, ohne zu speichern.

Angemeldete Nutzer

Standardmäßig wird die Einwilligung pro Browser gespeichert. In Produkten mit Login verknüpfen Sie sie mit Ihrer Nutzer-ID, damit die Entscheidung dem Nutzer geräteübergreifend folgt:

identify(userId: string): Promise<ConsentState>
reset(): void

// Nach der Anmeldung
await cookiesh.identify(session.user.id);

// Nach der Abmeldung
cookiesh.reset();

identify() sucht die letzte Entscheidung des Nutzers. Gibt es eine, wendet Cookiesh sie auf diesem Gerät an und überspringt das Banner. Hat der Besucher vor der Anmeldung entschieden, wird diese Entscheidung für den Nutzer gespeichert. Cookiesh speichert nur einen gesalzenen Hash der übergebenen ID, nie die ID selbst. Verwenden Sie eine nicht sprechende interne ID, keine E-Mail-Adresse.

reset() entfernt die Verknüpfung mit dem Nutzer, behält aber die aktuelle Entscheidung auf diesem Gerät bei.

Attribute des Script-Tags

Sie konfigurieren das Script-Tag mit data--Attributen:

Attribut	Standard	Beschreibung
data-site-id	Pflichtangabe	Ihre Site ID, etwa ck_live_8f2a91
data-language	Automatisch	Erzwingt die Bannersprache (siehe Banner anpassen)
data-auto-block	true	Auf false setzen, um nur die Skripte zu blockieren, die Sie selbst kennzeichnen
data-nonce	Keiner	CSP-Nonce für die Skripte, die Cookiesh freigibt
data-consent-mode	true	Auf false setzen, um keine Google-Consent-Mode-Signale mehr zu senden

Debugging

Cookiesh.debug(): void

Führen Sie es in der Browserkonsole aus, um die erkannte Region, die zutreffende Regel, die Banner-Version, jedes blockierte Skript und den aktuellen Status jeder Kategorie auszugeben. Es ist nur über das globale Objekt verfügbar.