KATLA PARA REACT
Consentimento de cookies para React que vive na sua árvore de componentes.
Um provider, meia dúzia de hooks tipados e dois componentes sem estilos. A decisão é estado que os seus componentes leem e com o qual voltam a renderizar, o bloqueador de cookies é injetado automaticamente, e o banner é seu para estilizar ou substituir por completo.
@katla.app/sdk/reactReact 18 e 19Vite, CRA, qualquer bundler
src/App.tsxVite + React
import { useEffect } from 'react'
import {
KatlaProvider,
CookieBanner,
useKatlaConsent,
} from '@katla.app/sdk/react'
function Analytics() {
const { consent } = useKatlaConsent()
useEffect(() => {
if (consent?.analytics) loadAnalytics()
}, [consent])
return null
}
export default function App() {
return (
<KatlaProvider siteId="your-site-id" googleConsentMode>
<Analytics />
<CookieBanner />
</KatlaProvider>
)
}O provider injeta ele próprio o bloqueador de cookies e a ponte de consentimentoGuia completo →
PORQUE É QUE OS SITES REACT TROPEÇAM NO CONSENTIMENTO
O estado do consentimento e o estado do React são o mesmo problema, resolvido duas vezes.
O PROBLEMAO banner é um script de terceiros que altera o DOM por fora do React, e uma nova renderização ou uma mudança de rota repõe-no como estava.
COM O KATLAEm vez disso, um provider e hooks tipados. O consentimento vive no contexto, e os componentes que o leem voltam a renderizar como tudo o resto na sua árvore.
O PROBLEMAAs tags são carregadas a partir do index.html antes de o React montar, por isso a decisão chega muito depois dos cookies.
COM O KATLAO KatlaProvider injeta o bloqueador de cookies ao montar. Um cookie cuja categoria não foi autorizada é recusado em document.cookie, seja qual for a tag que o tentou definir.
O PROBLEMAUm banner alojado ignora o seu design system, e mudar-lhe o estilo é uma luta com a folha de estilos de outra pessoa.
COM O KATLAO CookieBanner não inclui CSS: markup semântico com nomes de classe katla-* estáveis, uma render prop que o substitui por completo, e useConsentManager() se não quiser markup nenhum.
CONFIGURAÇÃO
Quatro passos, um provider.
- Instalarnpm install @katla.app/sdk. Cerca de 4 KB transferidos em modo headless.
- Envolver a appColoque o KatlaProvider à volta da sua árvore com o seu Site ID, e adicione googleConsentMode se usa GA4 ou Google Ads.
- Condicionar as tagsLeia useKatlaConsent() e carregue os scripts de analítica ou de marketing só quando a respetiva categoria for autorizada.
- Pôr o banner no arUse o CookieBanner e estilize-o com o seu próprio CSS, ou construa o seu próprio com useConsentManager().
FEITO PARA REACT
Hooks e componentes, e nada que não tenha pedido.
useKatlaConsentA decisão atual por categoria, atualizada em tempo real a partir de window.KatlaConsent, com uma subscrição onChange que devolve a sua própria função para a cancelar.
useKatlaCookiesO seu inventário analisado, com estados de carregamento e de erro. Os pedidos em curso não se duplicam, por isso dez componentes a montar ao mesmo tempo continuam a fazer um só pedido.
useConsentManagerO banner inteiro como estado (ready, hasDecision, availableCategories, toggleCategory, acceptAll, rejectAll, saveSelection) sem um único elemento renderizado.
Componentes sem estilosCookieBanner e CookieCatalog renderizam HTML semântico com nomes de classe katla-*, uma render prop e substituições por categoria e por cookie.
Consent Mode v2Uma única prop googleConsentMode controla ad_storage, analytics_storage, ad_user_data e ad_personalization. Negados por predefinição, atualizados com a decisão.
Nada pedido ao montarkatla pull escreve o inventário e o bloqueador em .katla/. Passe-os como initialCookies e guardScript e o navegador não pede absolutamente nada.
CORE WEB VITALS
Os cookies esfarelam-se. O seu SEO não devia.
O script de consentimento é o primeiro recurso de terceiros na página, e é por isso que aparece no relatório de Core Web Vitals. O ponto de entrada React transfere 4 KB, não renderiza interface nenhuma que não tenha pedido e não reserva espaço no fluxo da página; com initialCookies vindos do build, não faz pedido nenhum.
Como funciona o modo headless →4 kBTransferidoBloqueador de cookies e API de consentimento, brotli
0 msLCP acrescentadoFace à mesma página sem ele
0Deslocamento de layoutO banner não reserva espaço no fluxo
2PedidoUm script, em cache na edge
Medições nossas, feitas a : como foram feitas.
Perguntas que as equipas React fazem
- Devo usar isto em Next.js?
- Use antes @katla.app/sdk/next. O KatlaNextProvider assume a fronteira de cliente para que o resto da sua árvore continue a ser Server Components, e getCachedCookies() faz o prefetch do inventário no servidor. Os hooks e os componentes são os mesmos.
- Tenho de usar o CookieBanner?
- Não. Aceita uma render prop que substitui todo o seu markup, e useConsentManager() dá-lhe o mesmo estado sem markup nenhum. O provider, por si só, não renderiza banner nenhum.
- Que versões do React?
- 18 e 19, como peer dependency. Hooks e componentes de função em todo o lado, por isso funciona com Vite, Create React App ou qualquer outra configuração de React do lado do cliente.
- Posso evitar o pedido ao carregar a página?
- Sim. katla pull escreve os dados dos cookies, as políticas e o guard.js em .katla/ durante o build. Passe-os ao provider como initialCookies e guardScript e nada é pedido ao carregar a página.
Envolva a sua app uma vez, e os cookies esperam pela vez deles.
O plano gratuito analisa o seu site React e gera uma política de cookies, sem cartão.