SDK React

Le SDK React donne à vos composants un accès direct au consentement du visiteur. Les composants sont rendus à nouveau quand le choix change : vous n’avez jamais besoin de lire les cookies ni de recharger la page. Il fonctionne avec React 18 et versions ultérieures, y compris dans les applications Next.js, Remix et Vite.

Installation

npm install @cookiesh/react

Le SDK s’appuie sur la balise script Cookiesh. Chargez-la le plus tôt possible, comme indiqué dans le démarrage rapide, puis enveloppez votre application dans 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	Type	Description
siteId	string	Votre Site ID. Facultatif si la balise script définit déjà data-site-id.
userId	string | undefined	Associe le consentement à un utilisateur connecté pour qu’il le suive sur tous ses appareils. Transmettre undefined après la déconnexion appelle reset().
language	string	Impose la langue du bandeau.
onChange	(state: ConsentState) => void	Appelée après chaque nouveau choix.

useConsent

useConsent() renvoie l’état actuel et les actions permettant de le modifier :

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

function PrivacySettingsLink() {
  const { openPreferences } = useConsent();
  return <button onClick={openPreferences}>Paramètres de confidentialité</button>;
}

L’objet renvoyé contient :

Champ	Type	Description
ready	boolean	false tant que l’état du consentement n’est pas connu
necessary, preferences, analytics, marketing	boolean	La valeur actuelle de chaque catégorie
method	string	L’origine de l’état actuel (voir l’API JavaScript)
acceptAll, rejectAll	() => Promise<ConsentState>	Enregistrent un choix pour toutes les catégories
setConsent	(choices) => Promise<ConsentState>	Enregistre un choix pour certaines catégories
showBanner, openPreferences	() => void	Ouvrent l’interface Cookiesh

ConsentGate

ConsentGate n’affiche ses enfants que lorsque toutes les catégories indiquées sont autorisées, et un contenu de remplacement dans le cas contraire :

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

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

Transmettez un tableau, comme category={['analytics', 'marketing']}, pour exiger plusieurs catégories.

Rendu côté serveur

Le choix du visiteur est stocké dans son navigateur : il est donc inconnu pendant le rendu de la page sur le serveur. Pendant le rendu serveur et le premier rendu client, ready vaut false, comme toutes les catégories sauf necessary. Le contenu dépendant du consentement s’affiche donc après l’hydratation, et rien ne s’exécute avant le consentement.

Pour éviter tout décalage de mise en page, donnez à ConsentGate un contenu de remplacement de la même taille que celui qu’il remplace. Avec l’App Router de Next.js, les composants qui appellent useConsent() doivent être des composants client ('use client').

Tests

Dans les tests unitaires, enveloppez les composants dans CookieshTestProvider pour contrôler l’état sans charger le script :

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

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