Solução de Problemas - Facebook Pixel¶

Guia completo de troubleshooting para resolver problemas comuns na integração Complyr + Facebook Pixel e garantir rastreamento correto de conversões.

🔍 Ferramentas de Diagnóstico¶

Antes de começar, certifique-se de ter as seguintes ferramentas instaladas:

1. Facebook Pixel Helper¶

Extensão oficial do Facebook para Chrome: - Download: Chrome Web Store - Função: Detecta Pixels, mostra eventos disparados, valida parâmetros - Uso: Clique no ícone da extensão ao visitar seu site

2. Facebook Events Manager¶

Painel oficial de monitoramento: - URL: business.facebook.com/events_manager - Função: Eventos em tempo real, histórico, qualidade de dados - Uso: Selecione seu Pixel → Testar Eventos

3. Console do Navegador¶

DevTools integrado: - Atalho: F12 (Windows/Linux) ou Cmd+Option+I (Mac) - Aba Console: Ver logs do Complyr e erros JavaScript - Aba Network: Inspecionar requisições do Pixel

❌ Problemas Comuns¶

Problema 1: Pixel Não Detectado¶

Sintoma: - Facebook Pixel Helper mostra "No pixels found" - Events Manager não registra eventos - Nenhum log no console

Diagnóstico:

// Abra o console (F12) e execute:
console.log('fbq exists:', typeof fbq);
console.log('Complyr loaded:', typeof window.complyr);
console.log('Consent:', localStorage.getItem('complyr_consent'));

Possíveis Causas e Soluções:

Causa 1.1: Script Complyr Não Carregado¶

Verificar:

<!-- Deve existir no <head> do HTML -->
<script
  src="https://app.complyr.com.br/tag/js"
  data-workspace-id="SEU_WORKSPACE_ID"
  data-complyr-script
  async
  defer>
</script>

Solução: - Verifique se o Workspace ID está correto - Certifique-se de que o script está no <head>, não no <body> - Remova async e defer temporariamente para forçar carregamento síncrono

Causa 1.2: Consentimento Não Concedido¶

Verificar:

const consent = JSON.parse(localStorage.getItem('complyr_consent'));
console.log('Marketing consent:', consent?.purposes?.marketing);

Solução: 1. Limpe o localStorage: localStorage.clear() 2. Recarregue a página 3. Aceite o banner de consentimento clicando em "Aceitar Todos" 4. Verifique se Pixel Helper agora detecta o Pixel

Ordem Esperada

Sem consentimento → Pixel bloqueado → Pixel Helper não detecta

Com consentimento → Pixel carrega → Pixel Helper detecta

Causa 1.3: Ordem de Carregamento Incorreta¶

Problema: Script do Pixel carrega antes do script Complyr.

Verificar:

<!-- ❌ ERRADO -->
<script>
  fbq('init', '123456789012345');  <!-- Pixel PRIMEIRO -->
</script>
<script data-complyr-script></script>  <!-- Complyr DEPOIS -->

<!-- ✅ CORRETO -->
<script data-complyr-script></script>  <!-- Complyr PRIMEIRO -->
<script>
  fbq('init', '123456789012345');  <!-- Pixel DEPOIS -->
</script>

Solução: Mova o script Complyr para ANTES do código do Facebook Pixel.

Causa 1.4: AdBlocker Ativo¶

Verificar: - Desabilite extensões de bloqueio de anúncios (uBlock, AdBlock Plus, etc.) - Teste em janela anônima sem extensões

Solução: - Durante testes, desabilite AdBlockers - Em produção, usuários com AdBlockers não serão rastreados (comportamento esperado)

Problema 2: Eventos Não Disparam¶

Sintoma: - Pixel Helper detecta Pixel - Mas eventos como AddToCart, Purchase não aparecem - Events Manager não registra eventos customizados

Diagnóstico:

// Teste manual no console
fbq('track', 'ViewContent', {
  content_ids: ['test-123'],
  content_type: 'product',
  value: 99.90,
  currency: 'BRL'
});

// Verifique Pixel Helper imediatamente após

Possíveis Causas e Soluções:

Causa 2.1: Sintaxe Incorreta¶

Problemas comuns:

// ❌ ERRADO: Nome de evento incorreto
fbq('track', 'AddCart');  // Correto: AddToCart

// ❌ ERRADO: Parâmetros inválidos
fbq('track', 'Purchase', {
  price: 99.90  // Correto: value
});

// ❌ ERRADO: String ao invés de número
fbq('track', 'Purchase', {
  value: "99.90",  // Deve ser número: 99.90
  currency: 'BRL'
});

// ✅ CORRETO
fbq('track', 'Purchase', {
  content_ids: ['produto-123'],
  value: 99.90,
  currency: 'BRL'
});

Solução: Consulte a documentação de eventos customizados para sintaxe correta.

Causa 2.2: Evento Disparado Antes do Init¶

Problema: Código dispara evento antes do fbq('init') completar.

// ❌ ERRADO
fbq('init', '123456789012345');
fbq('track', 'Purchase', { ... });  // Pode executar antes do init completar

// ✅ CORRETO
fbq('init', '123456789012345');
fbq('track', 'PageView');

// Aguarde init completar antes de eventos customizados
setTimeout(() => {
  fbq('track', 'Purchase', { ... });
}, 100);

// Ou use callback
document.addEventListener('DOMContentLoaded', function() {
  // Pixel já carregado
  fbq('track', 'Purchase', { ... });
});

Causa 2.3: Evento Customizado Não Criado no Pixel¶

Problema: Eventos customizados (trackCustom) precisam ser criados no Events Manager primeiro.

Solução:

Acesse Events Manager
Selecione seu Pixel
Vá em Eventos Customizados
Clique em Criar Evento Customizado
Digite o nome (ex: DownloadPDF)
Configure regras ou use evento de código
Salve

Agora o evento customizado será rastreado:

fbq('trackCustom', 'DownloadPDF', {
  filename: 'catalogo.pdf'
});

Problema 3: Match Rate Baixo¶

Sintoma: - Events Manager mostra "Match Quality Score" < 3.0 - Audiências customizadas têm poucos matches - Relatórios de ROAS imprecisos

Diagnóstico:

Acesse Events Manager
Selecione seu Pixel
Vá em Qualidade de Dados (Data Quality)
Verifique Match Quality Score

Scores: - < 3.0: Ruim ❌ - 3.0 - 5.0: Médio ⚠️ - 5.0 - 7.0: Bom ✅ - > 7.0: Excelente ✅✅

Possíveis Causas e Soluções:

Causa 3.1: Advanced Matching Não Configurado¶

Verificar:

// No console, após usuário fazer login
console.log('User identified:', localStorage.getItem('complyr_user_identification'));

Se retornar null, Advanced Matching não está sendo usado.

Solução:

Identifique o usuário após login:

// Em sua página de login bem-sucedido
window.complyr.identify('email', 'usuario@example.com');

// Verifique no Pixel Helper se "Advanced Matching" aparece

Causa 3.2: Dados Identificáveis Incorretos¶

Problemas comuns:

// ❌ ERRADO: Email com espaços ou maiúsculas
window.complyr.identify('email', ' Usuario@Example.COM ');

// ❌ ERRADO: Telefone sem código do país
window.complyr.identify('phone', '11987654321');

// ✅ CORRETO: Email normalizado
window.complyr.identify('email', 'usuario@example.com');

// ✅ CORRETO: Telefone com código internacional
window.complyr.identify('phone', '+5511987654321');

Solução:

// Normalize dados antes de enviar
function normalizeEmail(email) {
  return email.toLowerCase().trim();
}

function normalizePhone(phone) {
  // Remove tudo exceto dígitos e +
  return phone.replace(/[^\d+]/g, '');
}

const userEmail = normalizeEmail(rawEmail);
const userPhone = normalizePhone(rawPhone);

window.complyr.identify('email', userEmail);
window.complyr.identify('phone', userPhone);

Causa 3.3: Identificação Apenas em Páginas Específicas¶

Problema: Usuário identificado apenas na página de login, mas não persiste em outras páginas.

Solução:

Identifique uma vez após login e mantenha em toda sessão:

// auth-service.js (exemplo SPA)
class AuthService {
  async login(email, password) {
    const user = await api.login({ email, password });

    // Salvar sessão
    this.currentUser = user;
    localStorage.setItem('user', JSON.stringify(user));

    // Identificar no Complyr
    if (window.complyr) {
      window.complyr.identify('email', user.email);
    }

    return user;
  }

  // Em cada carregamento de página
  restoreSession() {
    const user = JSON.parse(localStorage.getItem('user'));
    if (user && window.complyr) {
      window.complyr.identify('email', user.email);
    }
  }
}

// Chame em cada carregamento
document.addEventListener('DOMContentLoaded', function() {
  authService.restoreSession();
});

Problema 4: Pixel Dispara Sem Consentimento¶

Sintoma: - Usuário não aceitou consentimento de marketing - Mas Pixel Helper detecta eventos sendo enviados - Viola LGPD

Diagnóstico:

// Verifique consentimento
const consent = JSON.parse(localStorage.getItem('complyr_consent'));
console.log('Marketing granted:', consent?.purposes?.marketing);

// Verifique se Pixel está ativo
console.log('fbq exists:', typeof fbq);
console.log('fbq called without consent:', true);  // ❌ PROBLEMA!

Possível Causa: Ordem de Carregamento Incorreta

Verificar:

<!-- ❌ ERRADO: Pixel carrega ANTES do Complyr -->
<script>
  !function(f,b,e,v,n,t,s){ /* Código do Pixel */ }
  fbq('init', '123456789012345');
  fbq('track', 'PageView');
</script>
<script data-complyr-script></script>

Solução:

<!-- ✅ CORRETO: Complyr carrega ANTES do Pixel -->
<script
  src="https://app.complyr.com.br/tag/js"
  data-workspace-id="SEU_WORKSPACE_ID"
  data-complyr-script>
</script>

<script>
  !function(f,b,e,v,n,t,s){ /* Código do Pixel */ }
  fbq('init', '123456789012345');
  fbq('track', 'PageView');
</script>

Crítico

Se o script Complyr carregar DEPOIS do Pixel, o consentimento não será verificado e o Pixel disparará sem permissão do usuário.

Problema 5: Erros no Console¶

Erro 5.1: `fbq is not defined`¶

Mensagem:

Uncaught ReferenceError: fbq is not defined

Causa: Código tenta chamar fbq() antes do Pixel carregar.

Solução:

// ❌ ERRADO: Chama imediatamente
fbq('track', 'Purchase', { ... });

// ✅ CORRETO: Aguarda DOM carregar
document.addEventListener('DOMContentLoaded', function() {
  if (typeof fbq !== 'undefined') {
    fbq('track', 'Purchase', { ... });
  }
});

// ✅ ALTERNATIVA: Usa setTimeout
setTimeout(() => {
  if (typeof fbq !== 'undefined') {
    fbq('track', 'Purchase', { ... });
  }
}, 500);

Erro 5.2: `Cannot read property 'apply' of undefined`¶

Mensagem:

Uncaught TypeError: Cannot read property 'apply' of undefined

Causa: Script Complyr criou Proxy para fbq, mas Pixel não carregou.

Solução:

Verifique se usuário aceitou consentimento de marketing:

const consent = JSON.parse(localStorage.getItem('complyr_consent'));
if (consent?.purposes?.marketing) {
  console.log('Marketing consent granted - Pixel should load');
} else {
  console.log('Marketing consent denied - Pixel blocked');
}

Se consentimento concedido mas erro persiste, verifique AdBlockers.

Erro 5.3: `[Complyr] Facebook Pixel bloqueado - sem consentimento de marketing`¶

Mensagem no console:

[Complyr] Facebook Pixel bloqueado - sem consentimento de marketing

Causa: Usuário não aceitou consentimento de marketing. Comportamento esperado.

Solução: Não é um erro! É o Complyr funcionando corretamente e respeitando LGPD.

Para testar com consentimento: 1. localStorage.clear() 2. Recarregue página 3. Clique em "Aceitar Todos" no banner 4. Pixel agora será carregado

Problema 6: Eventos Duplicados¶

Sintoma: - Events Manager mostra 2x ou 3x o mesmo evento - Pixel Helper mostra múltiplos PageView para mesma página

Possíveis Causas e Soluções:

Causa 6.1: Múltiplas Chamadas `fbq('init')`¶

Verificar:

// Busque no código-fonte por:
fbq('init', '123456789012345');

// Deve aparecer apenas UMA vez

Solução: Remova chamadas duplicadas de fbq('init').

Causa 6.2: SPA com Múltiplos PageView¶

Problema: Aplicações Single Page Apps (React, Vue) disparam PageView em cada mudança de rota.

Solução:

// ❌ ERRADO: PageView automático em cada route change
fbq('track', 'PageView');  // Executado em cada useEffect

// ✅ CORRETO: PageView apenas na primeira carga
useEffect(() => {
  if (!window.fbqPageViewFired) {
    fbq('track', 'PageView');
    window.fbqPageViewFired = true;
  }
}, []);

// ✅ ALTERNATIVA: Use ViewContent para navegação
function onRouteChange(pageName) {
  fbq('track', 'ViewContent', {
    content_name: pageName
  });
}

Causa 6.3: GTM + Código Direto¶

Problema: Pixel instalado via GTM E diretamente no HTML.

Solução: Escolha apenas uma forma de instalação: - Via código direto no HTML (recomendado com Complyr), ou - Via GTM (não recomendado com Complyr)

Se usar GTM, configure consentimento manual (não use Complyr para controlar o Pixel).

🧪 Testes de Validação¶

Checklist de Testes Completo¶

Use esta checklist para validar a integração:

✅ Teste 1: Instalação Básica¶

Script Complyr presente no <head>
Script Complyr carrega ANTES do código do Pixel
Workspace ID correto
Pixel ID correto (15 dígitos)

✅ Teste 2: Consentimento Negado¶

Abra site em janela anônima
Banner aparece
Clique em "Apenas Essenciais" (nega marketing)
Pixel Helper NÃO deve detectar Pixel
Console mostra [Complyr] Facebook Pixel bloqueado

✅ Teste 3: Consentimento Concedido¶

Limpe localStorage: localStorage.clear()
Recarregue página
Banner aparece
Clique em "Aceitar Todos"
Pixel Helper detecta Pixel ✅
Events Manager registra PageView

✅ Teste 4: Eventos Customizados¶

Dispare evento manualmente no console:

fbq('track', 'AddToCart', {
  content_ids: ['test-123'],
  value: 99.90,
  currency: 'BRL'
});

Pixel Helper mostra evento AddToCart ✅
Events Manager registra evento em tempo real

✅ Teste 5: Advanced Matching¶

Execute no console:

window.complyr.identify('email', 'teste@example.com');

Dispare evento:

fbq('track', 'ViewContent', {
  content_ids: ['produto-123']
});

Pixel Helper mostra "Advanced Matching" ✅
Hash de email aparece (em: 5e8848...)

✅ Teste 6: Persistência de Consentimento¶

Aceite consentimento
Navegue para outra página do site
Pixel Helper continua detectando Pixel ✅
Banner NÃO aparece novamente

✅ Teste 7: Revogação de Consentimento¶

Com consentimento ativo, execute:

window.complyr.revokeConsent('Teste de revogação');

Recarregue página
Pixel Helper NÃO detecta Pixel
Console mostra [Complyr] Facebook Pixel bloqueado

🔧 Ferramentas de Debug Avançado¶

Debug Mode do Facebook Pixel¶

Ative logs detalhados no console:

// Cole no console do navegador
fbq.set('autoConfig', false, '123456789012345');
fbq('init', '123456789012345', {}, { debug: true });

Isso mostrará logs detalhados de cada evento:

[Facebook Pixel] Track event: PageView
[Facebook Pixel] Track event: ViewContent
[Facebook Pixel] Params: {content_ids: ['123'], value: 99.90}

Network Tab Inspection¶

Abra DevTools (F12)
Vá na aba Network
Filtre por facebook.com ou tr?
Recarregue a página
Procure por requisições para https://www.facebook.com/tr

O que verificar: - Status: Deve ser 200 OK - Query Params: id (Pixel ID), ev (evento), em (email hasheado se Advanced Matching) - Headers: User-Agent, Referer

Se requisições não aparecem → Pixel bloqueado (sem consentimento ou AdBlocker)

Complyr Debug Logs¶

Ative logs detalhados do Complyr:

// Cole no console
localStorage.setItem('complyr_debug', 'true');

// Recarregue página

// Verá logs como:
// [Complyr] Consent loaded: {purposes: {...}}
// [Complyr] Marketing consent: true
// [Complyr] Facebook Pixel loaded
// [Complyr] User identified: email

Para desativar:

localStorage.removeItem('complyr_debug');

📊 Monitoramento Contínuo¶

Events Manager - Data Quality¶

Monitore regularmente a qualidade dos dados:

Acesse Events Manager
Selecione seu Pixel
Vá em Qualidade de Dados
Verifique:
Match Quality Score: Deve ser > 6.0
Event Match Quality: Percentual de eventos com match
Data Issues: Erros ou avisos

Alertas comuns: - "Low event match quality" → Configure Advanced Matching - "Missing parameters" → Adicione parâmetros obrigatórios (value, currency) - "Duplicate events" → Remova chamadas duplicadas de fbq()

Test Events Tool¶

Ferramenta para testar eventos antes de ativação:

Events Manager → Testar Eventos
Digite URL do seu site
Abra o site em nova aba
Interaja (clique em produtos, adicione ao carrinho, etc.)
Volte ao Events Manager
Veja eventos em tempo real

Benefícios: - Validação em tempo real - Não afeta dados de produção - Mostra parâmetros completos de cada evento

❓ FAQ - Troubleshooting¶

P: Pixel funciona em desenvolvimento mas não em produção¶

R: Verifique: - Workspace ID e Pixel ID corretos em produção - Domínio do workspace configurado corretamente - HTTPS habilitado (Pixel requer HTTPS em produção) - AdBlockers não estão bloqueando (usuários reais podem usar)

P: Match rate baixo mesmo com Advanced Matching¶

R: - Verifique se identificação acontece APÓS o login, não antes - Normalize emails (lowercase, trim) - Use múltiplos identificadores (email + telefone + nome) - Aguarde 24-48h para Facebook processar dados

P: Eventos aparecem no Pixel Helper mas não no Events Manager¶

R: - Aguarde até 20 minutos para propagação - Verifique se Pixel ID é o mesmo em ambos - Confirme que AdBlockers estão desabilitados - Teste em janela anônima

P: Pixel funciona mas Advanced Matching não¶

R: - Verifique se window.complyr.identify() foi chamado APÓS login - Confirme que Pixel Helper mostra "Advanced Matching" ✅ - Verifique se hash de email aparece no Pixel Helper (em: 5e8848...) - Aguarde 24-48h para Facebook processar

P: Consentimento concedido mas Pixel não carrega¶

R: - Limpe cache do navegador - Limpe localStorage: localStorage.clear() - Recarregue página e aceite novamente - Verifique ordem de scripts (Complyr → Pixel) - Teste em navegador diferente

🔗 Próximos Passos¶

Agora que você sabe resolver problemas comuns:

Voltar ao Setup - Revisar configuração inicial
Gerenciamento de Consentimento - Entender bloqueio automático
Eventos Customizados - Validar sintaxe de eventos
Advanced Matching - Melhorar match rate

📞 Suporte¶

Problemas não resolvidos por este guia?

FAQ - Perguntas frequentes gerais
Documentação Facebook - Suporte oficial
Pixel Helper Guide - Guia oficial do Pixel Helper
Email: contato@complyr.com.br

📝 Reportar Problemas¶

Encontrou um bug ou problema não documentado?

Acesse GitHub Issues
Clique em New Issue
Use o template "Bug Report - Facebook Pixel"
Inclua:
Descrição do problema
Console logs
Screenshot do Pixel Helper
Passos para reproduzir
Ambiente (browser, versão, sistema operacional)

Solução de Problemas - Facebook Pixel¶

🔍 Ferramentas de Diagnóstico¶

1. Facebook Pixel Helper¶

2. Facebook Events Manager¶

3. Console do Navegador¶

❌ Problemas Comuns¶

Problema 1: Pixel Não Detectado¶

Causa 1.1: Script Complyr Não Carregado¶

Causa 1.2: Consentimento Não Concedido¶

Causa 1.3: Ordem de Carregamento Incorreta¶

Causa 1.4: AdBlocker Ativo¶

Problema 2: Eventos Não Disparam¶

Causa 2.1: Sintaxe Incorreta¶

Causa 2.2: Evento Disparado Antes do Init¶

Causa 2.3: Evento Customizado Não Criado no Pixel¶

Problema 3: Match Rate Baixo¶

Causa 3.1: Advanced Matching Não Configurado¶

Causa 3.2: Dados Identificáveis Incorretos¶

Causa 3.3: Identificação Apenas em Páginas Específicas¶

Problema 4: Pixel Dispara Sem Consentimento¶

Problema 5: Erros no Console¶

Erro 5.1: fbq is not defined¶

Erro 5.2: Cannot read property 'apply' of undefined¶

Erro 5.3: [Complyr] Facebook Pixel bloqueado - sem consentimento de marketing¶

Problema 6: Eventos Duplicados¶

Causa 6.1: Múltiplas Chamadas fbq('init')¶

Causa 6.2: SPA com Múltiplos PageView¶

Causa 6.3: GTM + Código Direto¶

🧪 Testes de Validação¶

Checklist de Testes Completo¶

✅ Teste 1: Instalação Básica¶

✅ Teste 2: Consentimento Negado¶

✅ Teste 3: Consentimento Concedido¶

✅ Teste 4: Eventos Customizados¶

✅ Teste 5: Advanced Matching¶

✅ Teste 6: Persistência de Consentimento¶

✅ Teste 7: Revogação de Consentimento¶

🔧 Ferramentas de Debug Avançado¶

Debug Mode do Facebook Pixel¶

Network Tab Inspection¶

Complyr Debug Logs¶

📊 Monitoramento Contínuo¶

Events Manager - Data Quality¶

Test Events Tool¶

❓ FAQ - Troubleshooting¶

P: Pixel funciona em desenvolvimento mas não em produção¶

P: Match rate baixo mesmo com Advanced Matching¶

P: Eventos aparecem no Pixel Helper mas não no Events Manager¶

P: Pixel funciona mas Advanced Matching não¶

P: Consentimento concedido mas Pixel não carrega¶

🔗 Próximos Passos¶

📞 Suporte¶

📝 Reportar Problemas¶

Erro 5.1: `fbq is not defined`¶

Erro 5.2: `Cannot read property 'apply' of undefined`¶

Erro 5.3: `[Complyr] Facebook Pixel bloqueado - sem consentimento de marketing`¶

Causa 6.1: Múltiplas Chamadas `fbq('init')`¶