A biblioteca oferece integrações nativas para as ferramentas mais comuns, eliminando a necessidade de código manual para o carregamento condicional de scripts de terceiros. As categorias usadas pelas integrações são sempre lidas da prop categories do ConsentProvider (fonte única de verdade).
O componente ConsentScriptLoader gerencia o carregamento desses scripts automaticamente, disparando-os apenas quando o usuário concede consentimento para a categoria correspondente.
category no config.measurementId, containerId, pixelId), a integração não executa. Em dev é logado erro; em prod não há log.globalThis.window.dataLayer não existir, a biblioteca cria []; se existir e tiver push, usa como está; se existir sem push, não sobrescreve e avisa em dev.🎯 Google Consent Mode v2 Automático: GA4 e GTM agora implementam Consent Mode v2 automaticamente:
bootstrap: Seta consent('default', 'denied') antes de qualquer carregamentoonConsentUpdate: Envia consent('update', 'granted') quando usuário consente🔄 Sistema de Fila com Prioridade: Scripts são executados ordenadamente:
necessary sempre primeiropriority primeiro📝 API registerScript(): Registre scripts programaticamente fora do JSX:
import { registerScript } from 'react-lgpd-consent'
const cleanup = registerScript({
id: 'my-script',
category: 'analytics',
priority: 5,
execute: async () => {
/* carrega script */
},
onConsentUpdate: ({ preferences }) => {
/* reage a mudanças */
},
})
💡 Procurando exemplos práticos? Veja RECIPES.md para receitas passo a passo de Google Consent Mode v2, Next.js App Router e CSP/nonce.
As integrações nativas foram revisadas contra a documentação oficial dos provedores:
dataLayerName customizado: a URL agora inclui &l=<dataLayerName>, como no snippet oficial do Google Tag Manager.clarity('consentv2', ...) automaticamente em onConsentUpdate, upload continua aceito no tipo, mas não envia mais uma tag arbitrária nem controla upload; gera aviso de depreciação.api_base, settings, Intercom('update') quando o consentimento segue válido e Intercom('shutdown') quando a categoria é revogada.zE('messenger:set', 'cookies', range) para sincronizar all, functional ou none.api_host para projetos com residência regional de dados.analyticscreateGoogleAnalyticsIntegration(config)measurementId e configurações adicionais para o gtag.import { createGoogleAnalyticsIntegration, ConsentScriptLoader } from 'react-lgpd-consent'
const integrations = [
createGoogleAnalyticsIntegration({
measurementId: 'G-XXXXXXXXXX',
config: { send_page_view: false },
})
]
<ConsentScriptLoader integrations={integrations} />
// ✅ Consent Mode v2 implementado automaticamente:
// - bootstrap: consent('default', 'denied') antes do script
// - onConsentUpdate: consent('update', 'granted') após consentimento
analyticscreateGoogleTagManagerIntegration(config)containerId e dataLayerName.import { createGoogleTagManagerIntegration } from 'react-lgpd-consent'
const integrations = [
createGoogleTagManagerIntegration({
containerId: 'GTM-XXXXXXX',
dataLayerName: 'customLayer', // opcional; gera &l=customLayer na URL do gtm.js
}),
]
// ✅ Consent Mode v2 no dataLayer customizado automaticamente
marketingcreateFacebookPixelIntegration(config)pixelId e autoTrack para PageView.import { createFacebookPixelIntegration } from 'react-lgpd-consent'
const integrations = [createFacebookPixelIntegration({ pixelId: 'YOUR_PIXEL_ID', autoTrack: true })]
analyticscreateHotjarIntegration(config)siteId, version e modo debug.import { createHotjarIntegration } from 'react-lgpd-consent'
const integrations = [createHotjarIntegration({ siteId: '123456', version: 6 })]
analyticscreateMixpanelIntegration(config)token, configurações customizadas e api_host para residência regional de dados.import { createMixpanelIntegration } from 'react-lgpd-consent'
const integrations = [
createMixpanelIntegration({
token: 'YOUR_TOKEN',
api_host: 'https://api-eu.mixpanel.com', // use quando seu projeto exigir endpoint regional
}),
]
analyticscreateClarityIntegration(config)projectId e sincroniza a Consent API v2 (consentv2) quando as preferências mudam.import { createClarityIntegration } from 'react-lgpd-consent'
const integrations = [
createClarityIntegration({
projectId: 'abcdef',
analyticsStorageCategory: 'analytics', // padrão
adStorageCategory: 'marketing', // padrão
}),
]
A partir de 31/10/2025, a Microsoft exige sinal de consentimento válido para funcionalidade completa do Clarity em visitas originadas de EEA/UK/CH. A integração envia
ad_Storageeanalytics_Storageconforme as categorias configuradas.
functionalcreateIntercomIntegration(config)app_id, api_base, settings, atualização em SPA e encerramento de sessão na revogação de consentimento.import { createIntercomIntegration } from 'react-lgpd-consent'
const integrations = [
createIntercomIntegration({
app_id: 'your_app_id',
api_base: 'https://api-iam.eu.intercom.io', // opcional: US/EU/Australia
settings: { custom_launcher_selector: '#help' },
}),
]
functionalcreateZendeskMessagingIntegration(config)key e sincronização de cookies via messenger:set.import { createZendeskMessagingIntegration } from 'react-lgpd-consent'
const integrations = [
createZendeskMessagingIntegration({
key: 'your_zendesk_key',
cookieRange: 'functional', // opcional: all | functional | none
}),
]
functionalcreateUserWayIntegration(config)accountId.import { createUserWayIntegration } from 'react-lgpd-consent'
const integrations = [createUserWayIntegration({ accountId: 'USERWAY_ACCOUNT_ID' })]
Para simplificar a configuração de múltiplas integrações, a biblioteca oferece templates e funções de ajuda.
suggestCategoryForScript(name: string): Sugere a categoria LGPD apropriada para um nome de script conhecido.createSuggestedIntegration(config): Cria integração customizada com categoria sugerida automaticamente (pode sobrescrever com category).createECommerceIntegrations, createSaaSIntegrations, createCorporateIntegrations: Templates de negócio que agrupam as integrações mais comuns para cada setor.INTEGRATION_TEMPLATES: Constante com presets de IDs e categorias para cada template.import {
ConsentProvider,
ConsentScriptLoader,
createECommerceIntegrations,
} from 'react-lgpd-consent'
function App() {
const integrations = createECommerceIntegrations({
googleAnalytics: { measurementId: 'G-XXXX' },
facebookPixel: { pixelId: '1234567890' },
hotjar: { siteId: '999999' },
})
return (
<ConsentProvider categories={{ enabledCategories: ['analytics', 'marketing', 'functional'] }}>
<ConsentScriptLoader integrations={integrations} />
{/* Seu app */}
</ConsentProvider>
)
}
import { createSuggestedIntegration } from 'react-lgpd-consent'
const integrations = [
createSuggestedIntegration({
id: 'custom-chat',
src: 'https://example.com/chat.js',
}),
]
A biblioteca inclui funcionalidades experimentais para facilitar a auditoria e o mapeamento de cookies.
categorizeDiscoveredCookies usa heurísticas para sugerir a categoria de um cookie.import { discoverRuntimeCookies, categorizeDiscoveredCookies } from 'react-lgpd-consent'
// 1. Descobre cookies em tempo de execução
const discovered = discoverRuntimeCookies()
// 2. Categoriza e registra no catálogo de cookies do modal
categorizeDiscoveredCookies(discovered, true)
Para evitar hydration mismatch e vazamento de scripts:
ConsentProvider dentro de um Client Component e carregue-o com dynamic(..., { ssr: false }) a partir do RootLayout (Server Component).ConsentScriptLoader para carregar GTM/GA4 somente após consentimento e inicialize o Consent Mode v2 com gtag('consent','default', denied) antes de qualquer script.QUICKSTART.md para ordem dos provedores/estilos (MUI/Emotion) e checklist SSR.Se precisar de uma integração que não é oferecida nativamente, você pode criar a sua implementando a interface ScriptIntegration.
interface ScriptIntegration {
id: string // ID único para o script
category: string // Categoria de consentimento que habilita o script
src: string // URL do script
init?: () => void // Função opcional para executar após o carregamento
attrs?: Record<string, string> // Atributos HTML para a tag <script>
}
A partir da versão 0.4.5, a biblioteca dispara automaticamente eventos padronizados no dataLayer para facilitar rastreamento, auditoria LGPD e integrações com o Google Tag Manager.
dataLayerglobalThis.window.dataLayer não existir, a biblioteca cria [].push, o array/objeto é usado como está.push, a biblioteca não sobrescreve e avisa em dev.consent_initializedDisparado quando o sistema de consentimento é inicializado (após hidratação).
Payload:
{
event: 'consent_initialized',
consent_version: '0.4.5',
timestamp: '2025-10-25T13:52:33.729Z',
categories: {
necessary: true,
analytics: false,
marketing: false
}
}
Exemplo de uso no GTM:
consent_initialized{{categories.analytics}}, {{categories.marketing}}, etc.consent_updatedDisparado sempre que o usuário atualiza suas preferências de consentimento.
Payload:
{
event: 'consent_updated',
consent_version: '0.4.5',
timestamp: '2025-10-25T13:52:33.729Z',
origin: 'modal', // 'banner' | 'modal' | 'reset' | 'programmatic'
categories: {
necessary: true,
analytics: true,
marketing: false
},
changed_categories: ['analytics']
}
Exemplo de uso no GTM:
consent_updated{{changed_categories}} contém analyticsNo GTM, crie as seguintes variáveis de camada de dados:
DLV - Consent Categories
categoriesDLV - Consent Origin
originDLV - Changed Categories
changed_categoriesAcionador: Consent Initialized
consent_initializedAcionador: Consent Updated - Analytics Accepted
consent_updated{{DLV - Consent Categories}}.analytics igual a trueG-XXXXXXXXXXConsent Updated - Analytics AcceptedCrie uma tag para registrar mudanças de consentimento em um sistema de auditoria:
// Tag HTML customizada no GTM
<script>
(function() {
var auditData = {
timestamp: {{DLV - timestamp}},
origin: {{DLV - Consent Origin}},
categories: {{DLV - Consent Categories}},
changed: {{DLV - Changed Categories}}
};
// Enviar para seu sistema de auditoria
fetch('/api/consent-audit', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(auditData)
});
})();
</script>
Para casos avançados, você pode disparar eventos manualmente:
import { pushConsentUpdatedEvent } from 'react-lgpd-consent'
// Disparar evento após mudança programática
const handleCustomUpdate = () => {
const newPreferences = {
necessary: true,
analytics: true,
marketing: false,
}
pushConsentUpdatedEvent(newPreferences, 'programmatic')
}
import type {
ConsentEvent,
ConsentEventOrigin,
ConsentInitializedEvent,
ConsentUpdatedEvent,
} from 'react-lgpd-consent'
// Origem da ação
type ConsentEventOrigin = 'banner' | 'modal' | 'reset' | 'programmatic'
// Evento de inicialização
interface ConsentInitializedEvent {
event: 'consent_initialized'
consent_version: string
timestamp: string
categories: Record<string, boolean>
}
// Evento de atualização
interface ConsentUpdatedEvent {
event: 'consent_updated'
consent_version: string
timestamp: string
origin: ConsentEventOrigin
categories: Record<string, boolean>
changed_categories: string[]
}
| Ferramenta | Categoria Recomendada | Justificativa |
|---|---|---|
| Google Analytics | analytics |
Coleta estatísticas de uso |
| Google Tag Manager | analytics |
Container de tags analíticas |
| Facebook Pixel | marketing |
Publicidade direcionada |
| Hotjar/FullStory | analytics |
Análise comportamental |
| UserWay/AccessiBe | functional |
Funcionalidade de acessibilidade |
| Live Chat | functional |
Funcionalidade de suporte |
| YouTube/Vimeo | social |
Conteúdo de redes sociais |
gtag.js): https://developers.google.com/tag-platform/gtagjsIntegre sistemas de auditoria monitorando eventos de consentimento:
import { ConsentProvider, ConsentScriptLoader } from 'react-lgpd-consent'
import { googleAnalytics4Integration } from './integrations'
;<ConsentProvider
categories={{ enabledCategories: ['analytics', 'marketing'] }}
onConsentInit={(state) => {
// Disparado na inicialização (útil para analytics)
console.log('Consentimento inicial:', state)
}}
onConsentChange={(current, previous) => {
// Disparado em toda mudança de preferências
console.log('Mudança:', { current, previous })
// Exemplo: disparar evento no dataLayer
globalThis.window?.dataLayer?.push({
event: 'consent_preferences_updated',
consent_analytics: current.preferences.analytics,
consent_marketing: current.preferences.marketing,
})
}}
onAuditLog={(entry) => {
// Enviar para backend de compliance
fetch('/api/consent-audit', {
method: 'POST',
body: JSON.stringify(entry),
})
}}
>
<ConsentScriptLoader integrations={[googleAnalytics4Integration]} />
<YourApp />
</ConsentProvider>
Use configurações pré-validadas pela ANPD:
import { ConsentProvider, createAnpdCategoriesConfig } from 'react-lgpd-consent'
// Preset BÁSICO (necessary + analytics)
const basicConfig = createAnpdCategoriesConfig({ include: ['analytics'] })
// Preset COMPLETO (todas as 6 categorias)
const fullConfig = createAnpdCategoriesConfig({
include: ['analytics', 'marketing', 'functional', 'social', 'personalization']
})
// Com customizações
const customConfig = createAnpdCategoriesConfig({
include: ['analytics', 'marketing'],
names: { analytics: 'Análises' },
descriptions: { marketing: 'Anúncios personalizados' }
})
<ConsentProvider categories={fullConfig}>
<ConsentScriptLoader integrations={myIntegrations} />
</ConsentProvider>
Vantagens dos presets:
Problemas de integração? Consulte TROUBLESHOOTING.md - Seção de Integrations.
ConsentScriptLoader e useConsentScriptLoader compartilham o mesmo ciclo:
bootstrap: preparação local idempotente, sem requisições externas, inclusive antes do aceite.beforeLoad(consent): configuração/fila do SDK, somente com categoria autorizada.init: inicialização após download, somente se o consentimento continuar válido.onConsentUpdate: sincronização na conclusão e nas mudanças posteriores, inclusive revogação.Downloads simultâneos são compartilhados. Remontar o componente não repete init por padrão.
reloadOnChange permite repetir a preparação e inicialização ao reautorizar a categoria;
a tag externa já carregada não é baixada novamente. Use IDs distintos para configurações distintas.
O hook deve permanecer montado enquanto a integração estiver ativa para observar revogações.
Falhas de rede não são consideradas sucesso e permitem nova tentativa.
analyticsStorageCategory mapeia analytics_storage e usa category como padrão.
adStorageCategory mapeia ad_storage, ad_user_data e ad_personalization, com padrão marketing.
Uma decisão ainda não confirmada (consented: false) nunca concede esses sinais.
Layers customizados não reutilizam o gtag de outro layer. O evento gtm.js é preparado antes do container.
createGoogleAnalyticsIntegration({
measurementId: 'G-XXXX',
category: 'estatisticas',
analyticsStorageCategory: 'estatisticas',
adStorageCategory: 'publicidade',
})
O loader bloqueia o download até o aceite (Consent Mode básico). Não carrega tags antes do aceite
para enviar pings sem cookies. Se o banner for integrado dentro de um template GTM, utilize
setDefaultConsentState e updateConsentState no template, com o gatilho Consent Initialization,
conforme a documentação do Google.
Não copie chamadas gtag('consent', ...) para uma tag Custom HTML como substituição dessas APIs.
Configure checks de consentimento para cada tag de terceiros no container.
O inventário padrão de GA4 contém _ga e _ga_*. _gid permanece apenas como padrão legado de
classificação; não é anunciado como cookie GA4. O GTM não recebe cookies próprios no catálogo:
registre os cookies das tags realmente configuradas, inclusive Google Ads, via overrides.
O Pixel prepara a fila antes do download e comunica consent grant/revoke. Novo aceite não repete
PageView. O Mixpanel prepara os marcadores exigidos pelo bundle CDN e recebe api_host dentro do
segundo argumento de init; o terceiro argumento é nome de instância, não endereço da API.
Revogar chama opt_out_tracking; reautorizar chama opt_in_tracking sem gerar evento de opt-in.
Consulte a documentação do Mixpanel.
_hjSettings e hj são preparados antes do script externo, incluindo hjdebug.
Não usamos comandos de parada não documentados. Depois de iniciado, revogar a categoria recarrega
a página para encerrar o SDK. O consentimento deve ser persistido antes dessa recarga (o provider faz isso).
Para aplicações com persistência externa, onRevoke substitui essa ação; o callback deve encerrar
o documento após persistir a decisão. Remover apenas a tag <script> não interrompe o SDK em memória.
Clarity prepara sua fila e envia consentv2 antes do script e após mudanças. upload é obsoleto e
não deve ser usado como controle de coleta. consentMode: false desativa a sincronização automática;
nesse caso o consumidor assume esse controle. Consentimento de armazenamento não equivale a desligar
inteiramente o SDK: veja a Consent API v2.
Intercom prepara settings e fila antes do download, preservando o host regional. A revogação chama
shutdown; um novo aceite chama boot novamente quando o boot automático está habilitado.
Prefira createZendeskMessagingIntegration ou COMMON_INTEGRATIONS.zendeskMessaging.
createZendeskChatIntegration continua disponível com seu ID legado, mas também integra Messaging,
não Chat Classic. Use somente uma das duas fábricas por página. Cookies do Chat Classic não são
anunciados para Messaging; a API do widget controla também armazenamento local. Declare o inventário
efetivo da sua configuração com setCookieCatalogOverrides.
UserWay mantém a URL oficial e o atributo data-account; nenhuma migração de endpoint é necessária.