React-SDK

Das React-SDK gibt Komponenten direkten Zugriff auf die Einwilligung des Besuchers. Komponenten rendern neu, sobald sich die Entscheidung ändert. Sie müssen also nie Cookies auslesen oder die Seite neu laden. Es funktioniert mit React 18 und neuer, auch in Next.js-, Remix- und Vite-Apps.

Installation

npm install @cookiesh/react

Das SDK nutzt im Hintergrund das Cookiesh-Script-Tag. Laden Sie es so früh wie möglich, wie im Schnellstart gezeigt, und umschließen Sie Ihre App dann mit CookieshProvider.

CookieshProvider

import { CookieshProvider } from '@cookiesh/react';

export function App({ children }: { children: React.ReactNode }) {
  return (
    <CookieshProvider siteId="ck_live_8f2a91" userId={session?.user.id}>
      {children}
    </CookieshProvider>
  );
}

Prop	Typ	Beschreibung
siteId	string	Ihre Site ID. Optional, wenn das Script-Tag bereits data-site-id setzt.
userId	string | undefined	Verknüpft die Einwilligung mit einem angemeldeten Nutzer, damit sie ihm geräteübergreifend folgt. Wird nach der Abmeldung undefined übergeben, ruft das reset() auf.
language	string	Erzwingt die Bannersprache.
onChange	(state: ConsentState) => void	Wird nach jeder neuen Entscheidung aufgerufen.

useConsent

useConsent() gibt den aktuellen Status und die Aktionen zurück, mit denen er sich ändern lässt:

import { useConsent } from '@cookiesh/react';

function PrivacySettingsLink() {
  const { openPreferences } = useConsent();
  return <button onClick={openPreferences}>Privacy settings</button>;
}

Das zurückgegebene Objekt enthält:

Feld	Typ	Beschreibung
ready	boolean	false, bis der Einwilligungsstatus bekannt ist
necessary, preferences, analytics, marketing	boolean	Der aktuelle Wert jeder Kategorie
method	string	Wie der aktuelle Status zustande kam (siehe JavaScript-API)
acceptAll, rejectAll	() => Promise<ConsentState>	Speichert eine Entscheidung für alle Kategorien
setConsent	(choices) => Promise<ConsentState>	Speichert eine Entscheidung für einzelne Kategorien
showBanner, openPreferences	() => void	Öffnet die Cookiesh-Oberfläche

ConsentGate

ConsentGate rendert seine Kinder nur, wenn jede angegebene Kategorie erlaubt ist, und andernfalls einen Fallback:

import { ConsentGate } from '@cookiesh/react';

<ConsentGate category="marketing" fallback={<VideoPlaceholder />}>
  <YouTubeEmbed id="dQw4w9WgXcQ" />
</ConsentGate>

Übergeben Sie ein Array, etwa category={['analytics', 'marketing']}, um mehrere Kategorien vorauszusetzen.

Server-Rendering

Die Entscheidung des Besuchers liegt in seinem Browser und ist daher unbekannt, solange eine Seite auf dem Server gerendert wird. Beim Server-Rendering und beim ersten Rendern im Client ist ready false, und jede Kategorie außer necessary ist false. Einwilligungsabhängige Inhalte werden deshalb erst nach der Hydration gerendert, und vor der Einwilligung läuft nichts.

Um Layout-Shifts zu vermeiden, geben Sie ConsentGate einen Fallback in derselben Größe wie der ersetzte Inhalt. Im Next.js App Router müssen Komponenten, die useConsent() aufrufen, Client-Komponenten sein ('use client').

Testen

Umschließen Sie Komponenten in Unit-Tests mit CookieshTestProvider, um den Status zu steuern, ohne das Skript zu laden:

import { render, screen } from '@testing-library/react';
import { CookieshTestProvider } from '@cookiesh/react/testing';

render(
  <CookieshTestProvider consent={{ analytics: true, marketing: false }}>
    <Dashboard />
  </CookieshTestProvider>,
);