SDK de React

El SDK de React da a los componentes acceso directo al consentimiento del visitante. Los componentes se vuelven a renderizar cuando cambia la elección, así que nunca tienes que leer cookies ni recargar la página. Funciona con React 18 y posteriores, incluidas las apps de Next.js, Remix y Vite.

Instalación

npm install @cookiesh/react

El SDK usa internamente la etiqueta script de Cookiesh. Cárgala lo antes posible, como se explica en el inicio rápido, y después envuelve tu app en 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	Descripción
siteId	string	Tu Site ID. Opcional si la etiqueta script ya define data-site-id.
userId	string | undefined	Vincula el consentimiento a un usuario con sesión iniciada para que lo acompañe en todos sus dispositivos. Pasar undefined tras cerrar sesión llama a reset().
language	string	Fuerza el idioma del banner.
onChange	(state: ConsentState) => void	Se llama tras cada nueva elección.

useConsent

useConsent() devuelve el estado actual y las acciones para cambiarlo:

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

function PrivacySettingsLink() {
  const { openPreferences } = useConsent();
  return <button onClick={openPreferences}>Configuración de privacidad</button>;
}

El objeto devuelto contiene:

Campo	Tipo	Descripción
ready	boolean	false hasta que se conoce el estado del consentimiento
necessary, preferences, analytics, marketing	boolean	El valor actual de cada categoría
method	string	Cómo se ha llegado al estado actual (consulta la API de JavaScript)
acceptAll, rejectAll	() => Promise<ConsentState>	Guardan una elección para todas las categorías
setConsent	(choices) => Promise<ConsentState>	Guarda una elección para algunas categorías
showBanner, openPreferences	() => void	Abren la interfaz de Cookiesh

ConsentGate

ConsentGate solo renderiza su contenido cuando todas las categorías indicadas están permitidas; si no, muestra un contenido alternativo:

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

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

Pasa un array, como category={['analytics', 'marketing']}, para exigir varias categorías.

Renderizado en servidor

La elección del visitante vive en su navegador, así que se desconoce mientras la página se renderiza en el servidor. Durante el renderizado en servidor y el primer renderizado en el cliente, ready es false y todas las categorías salvo necessary son false. Por eso, el contenido que depende del consentimiento se renderiza tras la hidratación y nada se ejecuta antes del consentimiento.

Para evitar cambios de diseño, da a ConsentGate un fallback del mismo tamaño que el contenido al que sustituye. En el App Router de Next.js, los componentes que llaman a useConsent() deben ser componentes de cliente ('use client').

Pruebas

En las pruebas unitarias, envuelve los componentes en CookieshTestProvider para controlar el estado sin cargar el script:

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

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