Pular para conteúdo

Detecção de Cookies

Visão Geral

O sistema de Cookie Detection do Complyr permite detectar e categorizar automaticamente todos os cookies presentes no seu site, incluindo cookies first-party e third-party. Esse recurso é essencial para compliance LGPD (Art. 7º, VIII) e para gerar declarações de cookies precisas.

Características

  • ✅ Scan automático de cookies em tempo real
  • ✅ Categorização baseada em padrões conhecidos
  • ✅ Detecção de cookies third-party
  • ✅ Monitoramento contínuo de novos cookies
  • ✅ Geração de relatórios de uso
  • ✅ Integração com sistema de consentimento
  • ✅ Export para documentação LGPD

Casos de Uso

  1. Auditoria de Cookies - Descobrir todos os cookies usados no site
  2. Compliance LGPD - Gerar declaração de cookies obrigatória
  3. Monitoramento - Detectar cookies third-party não autorizados
  4. Documentação - Manter registro atualizado de cookies

Conceitos Fundamentais

Tipos de Cookies

First-Party Cookies: - Definidos pelo seu domínio - Geralmente essenciais ou funcionais - Exemplos: sessão, autenticação, preferências

Third-Party Cookies: - Definidos por domínios externos - Usados para rastreamento e ads - Exemplos: Google Analytics, Facebook Pixel, ad networks

Categorias LGPD

O Complyr categoriza cookies em 5 grupos alinhados com LGPD:

  1. Essential - Essenciais para funcionamento do site
  2. Analytics - Métricas e análise de uso
  3. Marketing - Publicidade e retargeting
  4. Personalization - Personalização de experiência
  5. Third Party - Serviços de terceiros

Instalação e Configuração

Instalação Básica

<!-- Já incluído no script principal do Complyr -->
<script
  src="https://app.complyr.com.br/tag/js"
  data-workspace-id="SEU_WORKSPACE_ID"
  data-complyr-script
  data-enable-cookie-detection="true"
  async
  defer>
</script>

Configuração Avançada

// Configurar detecção de cookies com opções customizadas
window.complyrConfig = {
  workspace: 'SEU_WORKSPACE_ID',
  cookieDetection: {
    enabled: true,
    scanInterval: 5000,              // Scan a cada 5 segundos
    autoReport: true,                // Enviar relatório automaticamente
    detectThirdParty: true,          // Detectar cookies third-party
    categorize: true,                // Categorizar automaticamente
    warnUnknown: true,               // Avisar sobre cookies desconhecidos
    excludeDomains: [                // Domínios para ignorar
      'localhost',
      '.test',
    ],
    customCategories: {              // Categorias customizadas
      '_ga': 'analytics',
      '_fbp': 'marketing',
      'session_id': 'essential',
    },
  },
};

API de Detecção

Métodos Disponíveis

window.complyr.cookies.scan()

Executa scan manual de cookies:

document.addEventListener('complyr:loaded', async () => {
  // Executar scan manual
  const cookies = await window.complyr.cookies.scan();

  console.log('Cookies detectados:', cookies);
  // Retorna array de objetos Cookie
});

window.complyr.cookies.getAll()

Retorna todos os cookies detectados:

const allCookies = window.complyr.cookies.getAll();

console.log('Total de cookies:', allCookies.length);
console.log('Cookies:', allCookies);

Retorno:

[
  {
    name: '_ga',
    value: 'GA1.1.123456789.1234567890',
    domain: '.seusite.com',
    path: '/',
    expires: '2026-01-01T00:00:00.000Z',
    secure: true,
    httpOnly: false,
    sameSite: 'Lax',
    category: 'analytics',
    isThirdParty: true,
    detectedAt: '2025-01-15T10:30:00.000Z',
  },
  // ... mais cookies
]

window.complyr.cookies.getByCategory(category)

Filtra cookies por categoria:

// Obter apenas cookies de analytics
const analyticsCookies = window.complyr.cookies.getByCategory('analytics');

// Obter cookies essenciais
const essentialCookies = window.complyr.cookies.getByCategory('essential');

// Obter cookies third-party
const thirdPartyCookies = window.complyr.cookies.getByCategory('third_party');

window.complyr.cookies.getThirdParty()

Retorna apenas cookies third-party:

const thirdParty = window.complyr.cookies.getThirdParty();

console.log('Cookies third-party detectados:', thirdParty.length);
thirdParty.forEach(cookie => {
  console.log(`- ${cookie.name} (${cookie.domain})`);
});

window.complyr.cookies.categorize(cookieName, category)

Categoriza um cookie manualmente:

// Categorizar cookie customizado
window.complyr.cookies.categorize('my_custom_cookie', 'personalization');

// Categorizar múltiplos cookies
const customCategories = {
  'user_preferences': 'personalization',
  'shopping_cart': 'essential',
  'ab_test_variant': 'analytics',
};

Object.entries(customCategories).forEach(([name, category]) => {
  window.complyr.cookies.categorize(name, category);
});

window.complyr.cookies.generateReport()

Gera relatório completo de cookies:

const report = window.complyr.cookies.generateReport();

console.log('Relatório de Cookies:');
console.log('Total:', report.total);
console.log('Por categoria:', report.byCategory);
console.log('Third-party:', report.thirdPartyCount);
console.log('Não categorizados:', report.uncategorized);

Formato do Relatório:

{
  total: 15,
  byCategory: {
    essential: 3,
    analytics: 5,
    marketing: 4,
    personalization: 2,
    third_party: 1,
  },
  thirdPartyCount: 8,
  uncategorized: 0,
  cookies: [ /* array completo de cookies */ ],
  generatedAt: '2025-01-15T10:35:00.000Z',
}

window.complyr.cookies.exportDeclaration()

Exporta declaração de cookies para documentação LGPD:

const declaration = window.complyr.cookies.exportDeclaration();

// Gerar tabela HTML
const html = declaration.toHTML();
document.getElementById('cookie-table').innerHTML = html;

// Gerar JSON
const json = declaration.toJSON();
console.log('Declaração JSON:', json);

// Gerar Markdown
const markdown = declaration.toMarkdown();
console.log('Declaração Markdown:', markdown);

Eventos de Detecção

complyr:cookie-detected

Dispara quando um novo cookie é detectado:

document.addEventListener('complyr:cookie-detected', (event) => {
  const cookie = event.detail;

  console.log('Novo cookie detectado:', cookie.name);
  console.log('Categoria:', cookie.category);
  console.log('Third-party:', cookie.isThirdParty);

  // Ação customizada
  if (cookie.category === 'uncategorized') {
    console.warn('Cookie não categorizado encontrado:', cookie.name);
    // Enviar para revisão manual
  }
});

complyr:cookie-scan-complete

Dispara quando scan completo termina:

document.addEventListener('complyr:cookie-scan-complete', (event) => {
  const { total, byCategory, duration } = event.detail;

  console.log(`Scan completo: ${total} cookies encontrados em ${duration}ms`);
  console.log('Por categoria:', byCategory);
});

complyr:third-party-detected

Dispara quando cookie third-party é detectado:

document.addEventListener('complyr:third-party-detected', (event) => {
  const cookie = event.detail;

  console.warn('Cookie third-party detectado:', {
    name: cookie.name,
    domain: cookie.domain,
    category: cookie.category,
  });

  // Verificar se tem consentimento
  const hasConsent = window.complyr.hasConsent(cookie.category);

  if (!hasConsent) {
    console.error('Cookie third-party sem consentimento!', cookie.name);
    // Bloquear cookie ou alertar usuário
  }
});

Categorização Automática

Padrões Conhecidos

O Complyr usa uma biblioteca de padrões para categorizar automaticamente cookies comuns:

// Padrões built-in (exemplos)
const knownPatterns = {
  // Google Analytics
  '_ga': 'analytics',
  '_gid': 'analytics',
  '_gat': 'analytics',
  '_gac_': 'analytics',

  // Facebook
  '_fbp': 'marketing',
  '_fbc': 'marketing',
  'fr': 'marketing',

  // Marketing/Ads
  'IDE': 'marketing',
  'NID': 'marketing',
  '__Secure-1PSID': 'marketing',

  // Essenciais
  'PHPSESSID': 'essential',
  'session_id': 'essential',
  'csrf_token': 'essential',

  // Personalização
  'lang': 'personalization',
  'theme': 'personalization',
  'preferences': 'personalization',
};

Categorização por Domínio

// Categorizar por domínio automaticamente
window.complyrConfig = {
  cookieDetection: {
    domainCategories: {
      'google-analytics.com': 'analytics',
      'facebook.com': 'marketing',
      'doubleclick.net': 'marketing',
      'googletagmanager.com': 'analytics',
      'hotjar.com': 'analytics',
    },
  },
};

Categorização por Regex

// Categorizar usando regex
window.complyrConfig = {
  cookieDetection: {
    regexCategories: [
      { pattern: /^_ga/, category: 'analytics' },
      { pattern: /^_fb/, category: 'marketing' },
      { pattern: /session|sess/, category: 'essential' },
      { pattern: /test|experiment/, category: 'analytics' },
    ],
  },
};

Monitoramento Contínuo

Auto-Scan

Configure scan automático em intervalos:

// Configurar scan a cada 10 segundos
window.complyrConfig = {
  cookieDetection: {
    enabled: true,
    scanInterval: 10000,  // 10 segundos
    autoReport: true,
  },
};

Manual Scan Trigger

// Scan manual após ações específicas
document.getElementById('load-widgets').addEventListener('click', async () => {
  // Carregar widgets third-party
  await loadExternalWidgets();

  // Scan cookies após carregamento
  setTimeout(async () => {
    const cookies = await window.complyr.cookies.scan();
    console.log('Novos cookies após widgets:', cookies);
  }, 2000);
});

Watch Mode

Monitore criação de cookies em tempo real:

// Habilitar modo watch
window.complyr.cookies.watch({
  onDetect: (cookie) => {
    console.log('Cookie criado:', cookie.name);

    // Alertar se third-party sem consentimento
    if (cookie.isThirdParty) {
      const hasConsent = window.complyr.hasConsent(cookie.category);
      if (!hasConsent) {
        alert(`Cookie third-party detectado sem consentimento: ${cookie.name}`);
      }
    }
  },
  interval: 1000,  // Verificar a cada 1 segundo
});

// Desabilitar watch
window.complyr.cookies.unwatch();

Integração com Consentimento

Bloquear Cookies sem Consentimento

document.addEventListener('complyr:loaded', () => {
  // Monitorar cookies e bloquear se necessário
  window.complyr.cookies.watch({
    onDetect: async (cookie) => {
      const hasConsent = await window.complyr.hasConsent(cookie.category);

      if (!hasConsent && cookie.category !== 'essential') {
        // Deletar cookie sem consentimento
        document.cookie = `${cookie.name}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=${cookie.path}; domain=${cookie.domain}`;

        console.warn('Cookie bloqueado (sem consentimento):', cookie.name);
      }
    },
  });
});

Limpar Cookies ao Revogar Consentimento

document.addEventListener('complyr:consent-updated', (event) => {
  const { purposes } = event.detail;

  // Se revogou analytics, deletar cookies de analytics
  if (!purposes.analytics.granted) {
    const analyticsCookies = window.complyr.cookies.getByCategory('analytics');

    analyticsCookies.forEach(cookie => {
      document.cookie = `${cookie.name}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=${cookie.path}; domain=${cookie.domain}`;
      console.log('Cookie de analytics removido:', cookie.name);
    });
  }

  // Se revogou marketing, deletar cookies de marketing
  if (!purposes.marketing.granted) {
    const marketingCookies = window.complyr.cookies.getByCategory('marketing');

    marketingCookies.forEach(cookie => {
      document.cookie = `${cookie.name}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=${cookie.path}; domain=${cookie.domain}`;
      console.log('Cookie de marketing removido:', cookie.name);
    });
  }
});

Geração de Declaração de Cookies

Template HTML

async function generateCookieDeclaration() {
  const declaration = window.complyr.cookies.exportDeclaration();

  const html = `
    <div class="cookie-declaration">
      <h2>Declaração de Cookies</h2>
      <p>Este site utiliza ${declaration.total} cookies para melhorar sua experiência.</p>

      <h3>Cookies Essenciais (${declaration.byCategory.essential})</h3>
      <table>
        <thead>
          <tr>
            <th>Nome</th>
            <th>Finalidade</th>
            <th>Duração</th>
          </tr>
        </thead>
        <tbody>
          ${declaration.cookies
            .filter(c => c.category === 'essential')
            .map(c => `
              <tr>
                <td>${c.name}</td>
                <td>${c.purpose || 'Funcionamento essencial do site'}</td>
                <td>${formatDuration(c.expires)}</td>
              </tr>
            `).join('')}
        </tbody>
      </table>

      <h3>Cookies de Analytics (${declaration.byCategory.analytics})</h3>
      <table>
        <thead>
          <tr>
            <th>Nome</th>
            <th>Finalidade</th>
            <th>Duração</th>
          </tr>
        </thead>
        <tbody>
          ${declaration.cookies
            .filter(c => c.category === 'analytics')
            .map(c => `
              <tr>
                <td>${c.name}</td>
                <td>${c.purpose || 'Análise de uso e métricas'}</td>
                <td>${formatDuration(c.expires)}</td>
              </tr>
            `).join('')}
        </tbody>
      </table>

      <!-- Repetir para outras categorias -->
    </div>
  `;

  document.getElementById('cookie-declaration-container').innerHTML = html;
}

function formatDuration(expiresStr) {
  if (!expiresStr) return 'Sessão';

  const expires = new Date(expiresStr);
  const now = new Date();
  const days = Math.floor((expires - now) / (1000 * 60 * 60 * 24));

  if (days < 1) return 'Sessão';
  if (days === 1) return '1 dia';
  if (days < 30) return `${days} dias`;
  if (days < 365) return `${Math.floor(days / 30)} meses`;
  return `${Math.floor(days / 365)} anos`;
}

Export para Markdown

function exportToMarkdown() {
  const declaration = window.complyr.cookies.exportDeclaration();
  const markdown = declaration.toMarkdown();

  // Copiar para clipboard
  navigator.clipboard.writeText(markdown);
  alert('Declaração de cookies copiada para clipboard!');
}

Output Markdown:

# Declaração de Cookies

Este site utiliza 15 cookies para melhorar sua experiência.

## Cookies Essenciais (3)

| Nome | Finalidade | Duração |
|------|-----------|---------|
| session_id | Gerenciar sessão do usuário | Sessão |
| csrf_token | Proteção contra CSRF | 1 dia |
| language | Preferência de idioma | 1 ano |

## Cookies de Analytics (5)

| Nome | Finalidade | Duração |
|------|-----------|---------|
| _ga | Google Analytics - identificação | 2 anos |
| _gid | Google Analytics - identificação de sessão | 1 dia |
| _gat | Google Analytics - throttle | 1 minuto |

...

Relatórios e Analytics

Dashboard de Cookies

async function renderCookieDashboard() {
  const report = window.complyr.cookies.generateReport();

  const dashboard = `
    <div class="cookie-dashboard">
      <div class="stat-card">
        <h3>${report.total}</h3>
        <p>Total de Cookies</p>
      </div>

      <div class="stat-card">
        <h3>${report.thirdPartyCount}</h3>
        <p>Third-Party</p>
      </div>

      <div class="stat-card">
        <h3>${report.uncategorized}</h3>
        <p>Não Categorizados</p>
      </div>

      <div class="chart-container">
        <canvas id="cookie-chart"></canvas>
      </div>

      <div class="cookie-list">
        ${report.cookies.map(c => `
          <div class="cookie-item ${c.isThirdParty ? 'third-party' : 'first-party'}">
            <strong>${c.name}</strong>
            <span class="category-badge ${c.category}">${c.category}</span>
            <span class="domain">${c.domain}</span>
          </div>
        `).join('')}
      </div>
    </div>
  `;

  document.getElementById('dashboard').innerHTML = dashboard;

  // Renderizar chart com Chart.js
  renderChart(report.byCategory);
}

function renderChart(byCategory) {
  const ctx = document.getElementById('cookie-chart').getContext('2d');

  new Chart(ctx, {
    type: 'doughnut',
    data: {
      labels: Object.keys(byCategory),
      datasets: [{
        data: Object.values(byCategory),
        backgroundColor: [
          '#4CAF50',  // essential
          '#2196F3',  // analytics
          '#FF9800',  // marketing
          '#9C27B0',  // personalization
          '#F44336',  // third_party
        ],
      }],
    },
    options: {
      responsive: true,
      plugins: {
        legend: {
          position: 'bottom',
        },
        title: {
          display: true,
          text: 'Distribuição de Cookies por Categoria',
        },
      },
    },
  });
}

Export para CSV

function exportToCsv() {
  const cookies = window.complyr.cookies.getAll();

  const csv = [
    ['Nome', 'Categoria', 'Domínio', 'Third-Party', 'Duração', 'Detectado em'].join(','),
    ...cookies.map(c => [
      c.name,
      c.category,
      c.domain,
      c.isThirdParty ? 'Sim' : 'Não',
      formatDuration(c.expires),
      new Date(c.detectedAt).toLocaleString(),
    ].join(',')),
  ].join('\n');

  // Download CSV
  const blob = new Blob([csv], { type: 'text/csv' });
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = `cookies-${Date.now()}.csv`;
  a.click();
}

Troubleshooting

Problema 1: Cookies não detectados

Sintomas: - Scan retorna array vazio - Cookies conhecidos não aparecem

Soluções:

// 1. Verificar se detecção está habilitada
console.log('Cookie detection enabled:', window.complyrConfig?.cookieDetection?.enabled);

// 2. Executar scan manual
const cookies = await window.complyr.cookies.scan();
console.log('Manual scan result:', cookies);

// 3. Verificar cookies diretamente
console.log('document.cookie:', document.cookie);

// 4. Verificar permissões
console.log('Cookies enabled:', navigator.cookieEnabled);

Problema 2: Categorização incorreta

Sintomas: - Cookies aparecem em categoria errada - Cookies essenciais marcados como marketing

Soluções:

// Re-categorizar manualmente
window.complyr.cookies.categorize('my_cookie', 'essential');

// Adicionar padrão customizado
window.complyrConfig = {
  cookieDetection: {
    customCategories: {
      'my_cookie': 'essential',
      'session_*': 'essential',  // Suporta wildcards
    },
  },
};

// Recarregar configuração
await window.complyr.reload();

Problema 3: Third-party não detectados

Sintomas: - Cookies third-party não aparecem - isThirdParty sempre false

Soluções:

// 1. Habilitar detecção de third-party explicitamente
window.complyrConfig = {
  cookieDetection: {
    detectThirdParty: true,
  },
};

// 2. Verificar SameSite e Secure
cookies.forEach(c => {
  console.log(`${c.name}: sameSite=${c.sameSite}, secure=${c.secure}`);
});

// 3. Verificar se domínio é considerado third-party
const domain = window.location.hostname;
cookies.forEach(c => {
  const isThirdParty = !c.domain.includes(domain);
  console.log(`${c.name}: ${c.domain} - third-party: ${isThirdParty}`);
});

Segurança e Privacidade

Não Armazenar Valores Sensíveis

// Cookie detector NÃO armazena valores de cookies
// Apenas metadados (nome, domínio, categoria, etc.)

const cookies = window.complyr.cookies.getAll();
cookies.forEach(c => {
  console.log(c.name);   // ✅ OK
  console.log(c.value);  // ⚠️ Não persistido em backend
});

Hash de Valores (Opcional)

// Se precisar armazenar valores, use hash
import { sha256 } from 'crypto-js';

const cookies = window.complyr.cookies.getAll();
const hashedCookies = cookies.map(c => ({
  ...c,
  value: sha256(c.value).toString(),
}));

Próximos Passos

Após implementar Cookie Detection:

  1. Caching - Otimize performance com cache inteligente
  2. Form Scanning - Detecte campos de formulário sensíveis
  3. Request Interception - Controle requisições baseado em consentimento

Precisa de ajuda? Entre em contato com nosso suporte em suporte@complyr.com.br.