SDK React

L’SDK React dà ai componenti accesso diretto al consenso del visitatore. I componenti si aggiornano quando la scelta cambia, così non devi mai leggere i cookie né ricaricare la pagina. Funziona con React 18 e versioni successive, comprese le app Next.js, Remix e Vite.

Installazione

npm install @cookiesh/react

Dietro le quinte, l’SDK usa il tag script di Cookiesh. Caricalo il prima possibile, come mostrato nella guida rapida, poi racchiudi l’app in 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	Tipo	Descrizione
siteId	string	Il tuo Site ID. Facoltativo se il tag script imposta già data-site-id.
userId	string | undefined	Collega il consenso a un utente con login, così lo segue su tutti i dispositivi. Passare undefined dopo la disconnessione chiama reset().
language	string	Impone la lingua del banner.
onChange	(state: ConsentState) => void	Viene chiamata dopo ogni nuova scelta.

useConsent

useConsent() restituisce lo stato attuale e le azioni per modificarlo:

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

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

L’oggetto restituito contiene:

Campo	Tipo	Descrizione
ready	boolean	false finché lo stato del consenso non è noto
necessary, preferences, analytics, marketing	boolean	Il valore attuale di ogni categoria
method	string	Come si è arrivati allo stato attuale (vedi l’API JavaScript)
acceptAll, rejectAll	() => Promise<ConsentState>	Salvano una scelta per tutte le categorie
setConsent	(choices) => Promise<ConsentState>	Salva una scelta per alcune categorie
showBanner, openPreferences	() => void	Aprono l’interfaccia di Cookiesh

ConsentGate

ConsentGate esegue il rendering dei propri figli solo quando tutte le categorie indicate sono autorizzate, altrimenti mostra un fallback:

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

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

Passa un array, ad esempio category={['analytics', 'marketing']}, per richiedere più categorie.

Rendering lato server

La scelta del visitatore si trova nel suo browser, quindi non è nota mentre una pagina viene generata sul server. Durante il rendering lato server e il primo rendering sul client, ready è false e tutte le categorie tranne necessary sono false. Per questo i contenuti che dipendono dal consenso vengono visualizzati dopo l’idratazione e nulla viene eseguito prima del consenso.

Per evitare spostamenti del layout, assegna a ConsentGate un fallback delle stesse dimensioni del contenuto che sostituisce. Nell’App Router di Next.js, i componenti che chiamano useConsent() devono essere client component ('use client').

Test

Nei test unitari, racchiudi i componenti in CookieshTestProvider per controllare lo stato senza caricare lo script:

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

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