React SDK

React SDK дает компонентам прямой доступ к согласию посетителя. Компоненты перерисовываются, когда выбор меняется, поэтому вам не нужно читать файлы cookie или перезагружать страницу. SDK работает с React 18 и новее, в том числе в приложениях на Next.js, Remix и Vite.

Установка

npm install @cookiesh/react

Внутри SDK использует тег script Cookiesh. Загрузите его как можно раньше, как показано в разделе Быстрый старт, а затем оберните приложение в 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>
  );
}

Свойство	Тип	Описание
siteId	string	ID вашего сайта. Необязателен, если тег script уже задает data-site-id.
userId	string | undefined	Связывает согласие с вошедшим пользователем, чтобы оно следовало за ним на всех устройствах. Передача undefined после выхода вызывает reset().
language	string	Принудительно задает язык баннера.
onChange	(state: ConsentState) => void	Вызывается после каждого нового выбора.

useConsent

useConsent() возвращает текущее состояние и действия для его изменения:

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

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

Возвращаемый объект содержит:

Поле	Тип	Описание
ready	boolean	false, пока состояние согласия неизвестно
necessary, preferences, analytics, marketing	boolean	Текущее значение каждой категории
method	string	Как возникло текущее состояние (см. JavaScript API)
acceptAll, rejectAll	() => Promise<ConsentState>	Сохраняют выбор для всех категорий
setConsent	(choices) => Promise<ConsentState>	Сохраняет выбор для части категорий
showBanner, openPreferences	() => void	Открывают интерфейс Cookiesh

ConsentGate

ConsentGate отображает дочерние элементы, только когда разрешены все перечисленные категории, а иначе — запасной вариант (fallback):

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

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

Чтобы потребовать несколько категорий, передайте массив, например category={['analytics', 'marketing']}.

Серверный рендеринг

Выбор посетителя хранится в его браузере, поэтому при рендеринге страницы на сервере он неизвестен. Во время серверного рендеринга и первого рендеринга на клиенте ready равно false, как и все категории, кроме necessary. Поэтому контент, зависящий от согласия, отображается после гидратации, и ничего не запускается до согласия.

Чтобы избежать смещения макета, задайте для ConsentGate запасной вариант того же размера, что и заменяемый контент. В Next.js App Router компоненты, которые вызывают useConsent(), должны быть клиентскими ('use client').

Тестирование

В модульных тестах оборачивайте компоненты в CookieshTestProvider, чтобы управлять состоянием без загрузки скрипта:

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

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