KATLA PARA TYPESCRIPT
Consentimento de cookies em TypeScript: uma API, não uma tag script.
Um cliente tipado para o inventário de cookies, as políticas geradas e a decisão do visitante. Sem framework, sem interface e sem nenhum global não documentado para adivinhar: as categorias, o estado do consentimento e os locales das políticas são tipos que o seu editor já conhece.
@katla.app/sdk4 KB headlessQualquer bundler ou framework
src/consent.tsSem framework
import { createKatlaClient, type ConsentState } from '@katla.app/sdk'
const katla = createKatlaClient({ siteId: 'your-site-id' })
// Refuse non-consented cookies before anything can set one
await katla.injectGuard()
// The scanned inventory, grouped and typed by category
const { cookies } = await katla.getCookies()
cookies.marketing.forEach((c) => console.log(c.name, c.platform))
// Every decision, for as long as you listen
const off = katla.onConsentChange((consent: ConsentState) => {
if (consent.analytics) loadAnalytics()
})onConsentChange devolve a sua própria função para cancelar a subscriçãoGuia completo →
PORQUE É QUE OS SITES TYPESCRIPT TROPEÇAM NO CONSENTIMENTO
Um banner é um problema de interface. O consentimento é um problema de dados.
O PROBLEMAA plataforma entrega um widget, e tudo o que está por trás (que cookies existem, o que fazem, o que o visitante escolheu) fica fechado dentro do iframe de outra pessoa.
COM O KATLAO SDK são esses dados. getCookies() devolve o inventário, getPolicy() devolve o documento gerado em markdown, onConsentChange() devolve a decisão. A interface é a parte opcional.
O PROBLEMAO global de consentimento não está documentado e é diferente em cada plataforma, por isso cada integração é um palpite que falha em silêncio em produção.
COM O KATLAwindow.KatlaConsent tem o tipo KatlaConsentAPI, e ConsentState, CookieCategory, CookieData e os treze locales das políticas são exportados com ele. Um nome de categoria errado é um erro de compilação, não um pedido de suporte.
O PROBLEMABloquear rastreadores obriga a auditar cada script à mão, e a auditoria fica desatualizada no deploy seguinte.
COM O KATLAinjectGuard() redefine document.cookie e retém tudo aquilo cuja categoria não foi autorizada. A análise mantém o inventário atualizado, por isso a lista não é algo que tenha de manter.
CONFIGURAÇÃO
Instale, crie um cliente, condicione as tags.
- Instalarnpm install @katla.app/sdk. Cerca de 4 KB transferidos, tipos incluídos.
- Criar um clientecreateKatlaClient({ siteId }) é toda a configuração. Passe também baseUrl apenas se servir a CDN a partir do seu próprio domínio.
- Injetar o bloqueadorawait client.injectGuard(). A partir daí, um cookie cuja categoria não foi autorizada nunca é escrito.
- Condicionar as tagsSubscreva com onConsentChange() e carregue os scripts de analítica ou de publicidade quando a respetiva categoria passar a true.
FEITO PARA TYPESCRIPT
O que recebe por uma única dependência.
O inventário, tipadogetCookies() devolve cada cookie e píxel analisado, agrupados por categoria, com o fornecedor, o responsável pelo tratamento e a descrição, em qualquer um de treze idiomas.
O bloqueador de cookiesinjectGuard() redefine document.cookie, por isso um cookie sem consentimento é recusado no momento em que é escrito, em vez de ser apagado algum tempo depois de ter sido definido.
Políticas como dadosgetPolicy({ format }) devolve a política de cookies, a política de privacidade ou a tabela de cookies em markdown, com a data em que foi gerada. Renderize-a como a sua stack renderiza markdown.
Consent Mode v2 e GPCsetupGoogleConsentMode() envia os quatro sinais da Google, negados por predefinição e atualizados com a decisão. isGPCEnabled() lê o Global Privacy Control do navegador.
Build sem pedidos em runtimekatla pull escreve o inventário, as políticas e o bloqueador em .katla/, para que um build os possa incluir como recursos estáticos e não peça nada a cada visualização de página.
Sem frameworkO cliente é um objeto simples sobre fetch e eventos de window. Os pontos de entrada React e Next.js assentam nele; Vue, Svelte e JavaScript puro chamam-no diretamente.
CORE WEB VITALS
Os cookies esfarelam-se. O seu SEO não devia.
Headless quer dizer exatamente isso: sem interface, sem folha de estilos, sem webfont e sem um segundo pedido para ir buscar nada disso. 4 KB transferidos para o bloqueador e a API de consentimento e, trazido para o build com katla pull, nem sequer é um pedido.
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 TypeScript fazem
- Tenho de construir o meu próprio banner?
- Só se quiser. O ponto de entrada React inclui CookieBanner e CookieCatalog sem estilos, e o widget alojado do Katla é uma única tag script. O SDK em si, deliberadamente, não renderiza nada.
- Funciona fora do navegador?
- getCookies() e getPolicy() são simples pedidos fetch e correm em qualquer sítio onde o fetch corra, incluindo Node e runtimes de edge. injectGuard() e onConsentChange() precisam de um DOM, porque a decisão em si é tomada no navegador.
- E Vue, Svelte, ou nenhum framework?
- O cliente não depende de nenhum framework, por isso funciona em todos. Só os pontos de entrada React e Next.js importam o React, e nada o obriga a importá-los.
- De onde vêm os dados dos cookies?
- Da análise do seu próprio site, servida a partir da CDN e em cache na edge: as mesmas respostas que o widget lê. A cache é limpa quando uma análise ou uma reclassificação altera alguma coisa, por isso nunca é uma cópia que tenha de manter sincronizada.
Uma dependência, e o consentimento fica tipado.
O plano gratuito analisa o seu site TypeScript e gera uma política de cookies, sem cartão.