Exemplos Práticos¶

Visão Geral¶

Bem-vindo à seção de Exemplos Práticos do Complyr! Aqui você encontrará implementações completas e funcionais para diferentes tipos de projetos e tecnologias.

Cada exemplo é detalhado com: - 📝 Código completo e funcional - 🎯 Caso de uso específico - ⚙️ Configuração passo a passo - 🧪 Como testar a implementação - ⚠️ Problemas comuns e soluções - 🎨 Customizações recomendadas

Exemplos Disponíveis¶

1. Site Básico (HTML Puro)¶

Implementação mais simples do Complyr em um site HTML estático.

Ideal para: - Sites institucionais - Landing pages - Blogs estáticos - Portfólios

Tecnologias: - HTML5 - CSS3 - JavaScript puro

Tempo estimado: 10 minutos

Nível: Iniciante 🟢

2. E-commerce Completo¶

Integração completa com Google Tag Manager e Facebook Pixel para loja virtual.

Ideal para: - Lojas virtuais - Marketplaces - Vendas online

Tecnologias: - HTML/JavaScript - Google Tag Manager - Facebook Pixel - Google Analytics 4 - Enhanced E-commerce

Tempo estimado: 45 minutos

Nível: Intermediário 🟡

Recursos incluídos: - Rastreamento de visualizações de produto - Rastreamento de adicionar ao carrinho - Rastreamento de checkout - Rastreamento de compras - Advanced Matching do Facebook Pixel - Consent Mode v2 configurado

3. Aplicação SaaS (React)¶

Implementação em aplicação SaaS moderna com React, incluindo autenticação e área do usuário.

Ideal para: - Dashboards - Aplicações web SaaS - Áreas de membros - Plataformas online

Tecnologias: - React 18+ - React Router - localStorage - API REST

Tempo estimado: 30 minutos

Nível: Intermediário 🟡

Recursos incluídos: - Identificação de usuários após login - Sincronização cross-device - Gestão de preferências na conta do usuário - Preferências persistidas no backend - Banner condicional (não exibir para usuários autenticados com preferências)

4. WordPress (Plugin ou Código)¶

Guia completo para integração em sites WordPress.

Ideal para: - Blogs WordPress - Sites corporativos WordPress - WooCommerce

Tecnologias: - WordPress 5.0+ - PHP - JavaScript - WooCommerce (opcional)

Tempo estimado: 20 minutos

Nível: Iniciante 🟢

Métodos incluídos: - Via plugin Code Snippets - Via functions.php - Via GTM (Google Tag Manager) - Via plugin customizado

5. Single Page Application (React)¶

Implementação otimizada para React SPAs com roteamento e navegação.

Ideal para: - SPAs React - Next.js - Create React App - Vite + React

Tecnologias: - React 18+ - React Router v6 - TypeScript - Hooks customizados

Tempo estimado: 25 minutos

Nível: Intermediário 🟡

Recursos incluídos: - Hook customizado useComplyr() - Context Provider para estado global - Integração com React Router - TypeScript types incluídos - Testes unitários com Jest

Pré-requisitos¶

Antes de implementar qualquer exemplo, certifique-se de ter:

1. Conta no Complyr¶

✅ Cadastro gratuito em app.complyr.com.br

2. Workspace Configurado¶

✅ Workspace criado com: - Nome da empresa - Domínio configurado (ex: meusite.com.br) - Workspace ID gerado

3. Template de Consentimento Ativo¶

✅ Pelo menos um template de consentimento publicado e ativo

4. Políticas Criadas¶

✅ Políticas recomendadas: - Política de Privacidade - Política de Cookies - Termos de Uso

5. Ferramentas de Teste¶

✅ Para validar a implementação: - Navegador com DevTools (Chrome, Firefox, Edge) - Modo anônimo/privado para testes - GTM Preview (se usar GTM) - Facebook Pixel Helper (se usar FB Pixel)

Como Usar os Exemplos¶

Passo 1: Escolha o Exemplo¶

Selecione o exemplo que melhor se adequa ao seu projeto:

Passo 2: Obtenha Suas Credenciais¶

No dashboard do Complyr:

1. Acesse Configurações → Integrações
2. Copie seu Workspace ID
3. (Opcional) Configure Google Tag Manager ou Facebook Pixel conforme necessário

Passo 3: Siga o Guia Passo a Passo¶

Cada exemplo inclui:

1. Instalação - Como adicionar o script
2. Configuração - Opções e customizações
3. Testes - Como validar que está funcionando
4. Troubleshooting - Problemas comuns e soluções

Passo 4: Teste em Ambiente de Desenvolvimento¶

Antes de publicar em produção:

✅ Teste em localhost ou ambiente de staging ✅ Verifique o banner aparece corretamente ✅ Teste aceitar/rejeitar/customizar consentimentos ✅ Valide que cookies são bloqueados quando necessário ✅ Verifique Google Tag Manager e Facebook Pixel (se aplicável)

Passo 5: Publique em Produção¶

Após validar em desenvolvimento:

✅ Deploy do código em produção ✅ Teste novamente em modo anônimo ✅ Monitore erros no Console ✅ Valide consentimentos sendo salvos no dashboard Complyr

Estrutura dos Exemplos¶

Todos os exemplos seguem uma estrutura padronizada:

# Nome do Exemplo

## Visão Geral
- Descrição do caso de uso
- Tecnologias utilizadas
- Tempo estimado de implementação

## Pré-requisitos
- Lista de requisitos específicos

## Passo 1: Instalação
- Código de instalação do script Complyr

## Passo 2: Configuração
- Configurações adicionais necessárias

## Passo 3: Implementação
- Código completo com comentários
- Exemplos práticos

## Passo 4: Testes
- Como validar a implementação
- Checklist de testes

## Customizações
- Opções de customização
- Exemplos avançados

## Problemas Comuns
- Troubleshooting
- Soluções para erros frequentes

## Próximos Passos
- Links para documentação relacionada

Comparação de Exemplos¶

Fluxo Geral de Implementação¶

flowchart TD
    A[Criar Workspace no Complyr] --> B[Configurar Template de Consentimento]
    B --> C[Criar Políticas]
    C --> D[Copiar Workspace ID]
    D --> E{Escolher Tecnologia}

    E -->|HTML Puro| F[Site Básico]
    E -->|Loja Virtual| G[E-commerce]
    E -->|SaaS/Dashboard| H[Aplicação SaaS]
    E -->|WordPress| I[WordPress]
    E -->|React| J[React SPA]

    F --> K[Adicionar Script Tag]
    G --> K
    H --> K
    I --> K
    J --> K

    K --> L{Integrar com GTM?}
    L -->|Sim| M[Configurar GTM]
    L -->|Não| N[Testar Banner]

    M --> O{Integrar com FB Pixel?}
    O -->|Sim| P[Configurar Facebook Pixel]
    O -->|Não| N

    P --> N
    N --> Q[Validar Consentimentos]
    Q --> R[Testar Bloqueio de Cookies]
    R --> S[Deploy em Produção]
    S --> T[Monitorar no Dashboard]

Recursos Adicionais¶

Documentação de Referência¶

• Gerenciamento de Consentimento
• Controle por Finalidade
• Google Tag Manager
• Facebook Pixel
• API JavaScript

Ferramentas Úteis¶

1. Testes de Consentimento:
2. Chrome DevTools → Application → Cookies
3. Chrome DevTools → Console (eventos)

4. GTM Preview Mode

5. Validação de Pixels:

6. Facebook Pixel Helper

7. Google Tag Assistant

8. Testes de Acessibilidade:

9. WAVE

10. axe DevTools

11. Simulação de Dispositivos:

12. Chrome DevTools → Device Toolbar (Ctrl+Shift+M)
13. BrowserStack (testes cross-browser)

Exemplos por Caso de Uso¶

Caso 1: Site Simples sem Marketing¶

Objetivo: Site institucional que NÃO usa Google Analytics, Facebook Pixel ou outras ferramentas de rastreamento.

Solução: Site Básico

Motivo: Implementação mínima, apenas solicita consentimento para cookies essenciais.

Caso 2: Loja Virtual com Rastreamento de Conversões¶

Objetivo: E-commerce que precisa rastrear vendas, adicionar ao carrinho, checkout.

Solução: E-commerce Completo

Motivo: Integração completa com GTM, GA4, Facebook Pixel, Enhanced E-commerce.

Caso 3: Plataforma SaaS com Usuários Logados¶

Objetivo: Aplicação web com autenticação, área do usuário, preferências persistidas.

Solução: Aplicação SaaS

Motivo: Identificação de usuários, sincronização cross-device, preferências no backend.

Caso 4: Blog WordPress sem Conhecimento Técnico¶

Objetivo: Blog WordPress, proprietário sem conhecimento de código.

Solução: WordPress

Motivo: Múltiplas opções (plugin, GTM, código), sem necessidade de editar código.

Caso 5: Aplicação React Moderna com TypeScript¶

Objetivo: SPA React com roteamento, TypeScript, testes automatizados.

Solução: React SPA

Motivo: Implementação otimizada para React, hooks customizados, types TypeScript.

Padrões de Código¶

Todos os exemplos seguem estes padrões:

1. Script Tag Padrão¶

<!-- Complyr Script - Adicionar antes do </body> -->
<script
  src="https://app.complyr.com.br/tag/js"
  data-workspace-id="SEU_WORKSPACE_ID"
  data-complyr-script
  async
  defer>
</script>

2. Esperar Carregamento do Script¶

// ✅ CORRETO: Aguardar evento complyr:loaded
document.addEventListener('complyr:loaded', function() {
  if (window.complyr) {
    // Script carregado, pode usar window.complyr
    console.log('Complyr carregado!');
  }
});

// ❌ ERRADO: Usar imediatamente
window.complyr.identify('email', 'user@example.com'); // Pode falhar

3. Verificar Existência do Objeto¶

// ✅ CORRETO: Verificar se existe
if (window.complyr && typeof window.complyr.identify === 'function') {
  window.complyr.identify('email', 'user@example.com');
}

// ❌ ERRADO: Assumir que existe
window.complyr.identify('email', 'user@example.com'); // Erro se não carregou

4. Tratamento de Erros¶

// ✅ CORRETO: Try-catch para operações críticas
try {
  window.complyr.revokeConsent('User requested data deletion');
  console.log('Consentimento revogado com sucesso');
} catch (error) {
  console.error('Erro ao revogar consentimento:', error);
  // Fallback ou mensagem ao usuário
}

5. Listeners de Eventos¶

// ✅ CORRETO: Remover listeners quando não precisar mais
const consentHandler = function(event) {
  console.log('Consentimento atualizado:', event.detail);
};

document.addEventListener('consent-updated', consentHandler);

// Cleanup (ex: ao desmontar componente React)
document.removeEventListener('consent-updated', consentHandler);

Boas Práticas¶

1. Performance¶

✅ Carregue o script de forma assíncrona

<script src="..." async defer></script>

✅ Não bloqueie a renderização da página

<!-- ✅ Antes do </body> -->
<body>
  <!-- Conteúdo -->
  <script src="complyr-script"></script>
</body>

<!-- ❌ No <head> sem async -->
<head>
  <script src="complyr-script"></script> <!-- Bloqueia renderização -->
</head>

2. Segurança¶

✅ Use HTTPS em produção

if (location.protocol !== 'https:' && process.env.NODE_ENV === 'production') {
  console.warn('Complyr requer HTTPS em produção');
}

✅ Não exponha dados sensíveis

// ❌ ERRADO: Enviar dados sensíveis sem hash
window.complyr.identify('cpf', '12345678900'); // CPF em texto puro

// ✅ CORRETO: Enviar apenas hash
const cpfHash = sha256('12345678900');
window.complyr.identify('cpf', cpfHash);

3. Acessibilidade¶

✅ Banner navegável por teclado - Botões acessíveis via Tab - Enter/Space para ativar botões - Escape para fechar modal

✅ ARIA labels adequadas

<button
  class="complyr-btn"
  aria-label="Aceitar todos os cookies"
  onclick="window.complyr.acceptAll()">
  Aceitar Todos
</button>

4. UX¶

✅ Mensagens claras e objetivas

<!-- ✅ BOM -->
<p>Usamos cookies para melhorar sua experiência.</p>

<!-- ❌ RUIM -->
<p>Este site utiliza tecnologias de rastreamento baseadas em cookies...</p>

✅ Botões visualmente distintos - "Aceitar Todos" → Verde / Destaque - "Rejeitar Todos" → Vermelho / Secundário - "Gerenciar Preferências" → Neutro / Terciário

Testes Recomendados¶

Para cada exemplo, execute estes testes:

Checklist de Validação¶

• Banner aparece na primeira visita
• Teste em modo anônimo/privado

• Limpe cookies e localStorage antes de testar

• Banner não aparece em visitas subsequentes

• Após aceitar/rejeitar, atualizar página

• Banner não deve aparecer novamente

• Aceitar Todos funciona

• Clique em "Aceitar Todos"
• Verifique localStorage contém consentimento GRANTED

• Verifique eventos disparados no Console

• Rejeitar Todos funciona

• Clique em "Rejeitar Todos"
• Verifique localStorage contém consentimento DENIED

• Verifique cookies não essenciais bloqueados

• Gerenciar Preferências funciona

• Clique em "Gerenciar Preferências"
• Modal abre com toggles para cada finalidade

• Salvar preferências funciona

• Cookies bloqueados quando negados

• Rejeite "Analytics"
• Google Analytics NÃO deve disparar

• Verifique no GTM Preview ou DevTools

• Cookies desbloqueados quando aceitos

• Aceite "Marketing"
• Facebook Pixel DEVE disparar

• Verifique no Facebook Pixel Helper

• Consentimento salvo no backend

• Acesse Dashboard Complyr

• Verifique consentimento registrado em Consentimentos

• Responsividade

• Teste em desktop (1920x1080)
• Teste em tablet (768x1024)

• Teste em mobile (375x667)

• Acessibilidade

• Navegue com Tab (sem mouse)
• Use leitor de tela (NVDA, JAWS, VoiceOver)
• Verifique contraste WCAG AA (4.5:1)

Troubleshooting Geral¶

Problema 1: Banner não aparece¶

Sintomas: - Página carrega mas banner não exibe

Causas possíveis: 1. Workspace ID incorreto 2. Script não carregou (bloqueado por ad blocker) 3. Erro de JavaScript anterior bloqueou execução 4. Template não está ativo

Soluções:

// 1. Verificar se script carregou
console.log('Complyr disponível:', window.complyr);

// 2. Verificar erros no Console
// DevTools → Console → Verificar erros em vermelho

// 3. Verificar localStorage
console.log(localStorage.getItem('complyr_consent'));

// 4. Forçar reset
localStorage.removeItem('complyr_consent');
location.reload();

Problema 2: Consentimento não salva¶

Sintomas: - Clicar em "Aceitar" mas banner reaparece

Causas possíveis: 1. localStorage bloqueado (modo privado) 2. Domínio não corresponde ao workspace 3. Erro de rede (API offline)

Soluções:

// 1. Testar localStorage
try {
  localStorage.setItem('test', 'test');
  console.log('localStorage disponível');
} catch (e) {
  console.error('localStorage bloqueado:', e);
}

// 2. Verificar Network tab
// DevTools → Network → Filtrar por "complyr" → Verificar status 200

// 3. Verificar domínio workspace
console.log('Domínio atual:', location.hostname);
console.log('Workspace domain:', 'SEU_DOMINIO_WORKSPACE');

Problema 3: Google Tag Manager não dispara¶

Sintomas: - GTM configurado mas tags não executam

Causas possíveis: 1. Consent Mode v2 bloqueando tags 2. Triggers mal configurados 3. Consentimento não foi dado

Soluções:

// 1. Verificar dataLayer
console.log('dataLayer:', window.dataLayer);

// 2. Verificar consent state
console.log('Consent Analytics:', window.dataLayer.find(
  item => item.consent_analytics
));

// 3. Usar GTM Preview Mode
// Tag Manager → Preview → Verificar tags disparadas

Problema 4: Facebook Pixel não rastreia¶

Sintomas: - FB Pixel configurado mas eventos não aparecem

Causas possíveis: 1. Consent não foi concedido para Marketing 2. Pixel ID incorreto 3. fbq() chamado antes do consentimento

Soluções:

// 1. Verificar se fbq existe
console.log('Facebook Pixel:', window.fbq);

// 2. Verificar eventos
fbq('track', 'PageView'); // Testar manualmente

// 3. Verificar Facebook Pixel Helper (extensão Chrome)
// Deve mostrar eventos capturados em verde

Próximos Passos¶

Após escolher e implementar um exemplo:

1. Customização de Banner - Personalize cores e textos
2. Configuração de Templates - Ajuste finalidades
3. Tópicos Avançados - Funcionalidades avançadas
4. Referência Técnica - Documentação completa da API

Suporte¶

Precisa de ajuda com algum exemplo?

• Email: contato@complyr.com.br
• GitHub Issues: https://github.com/complyr/complyr/issues
• Documentação: https://docs.complyr.com.br

Contribuindo com Exemplos¶

Quer adicionar um novo exemplo? Contribuições são bem-vindas!

1. Fork do repositório complyr/public-docs
2. Crie um arquivo Markdown seguindo a estrutura padrão
3. Adicione código funcional e testado
4. Inclua screenshots se necessário
5. Abra um Pull Request

Exemplos que gostaríamos de ver: - Vue.js + Nuxt.js - Angular - Svelte/SvelteKit - Astro - Gatsby - Hugo (Static Site Generator)