Guia Completo de Implementação de Tracking por Cliente

Visão Geral do Processo de Implementação

A implementação de tracking multi-nível para clientes de agências jurídicas segue uma arquitetura em camadas progressivas, desenhada para entregar valor incremental desde o primeiro dia enquanto constrói a fundação para atribuição completa e closed-loop.

Estrutura em Cinco Fases

O processo se organiza em cinco momentos distintos, cada um com entregáveis claros:

Fase	Timing	Objetivo	Bloqueadores Críticos
Pré-requisito	Uma vez (agência)	Infraestrutura compartilhada no ar	Deploy do Porteiro, migrations aplicadas
Fase 0: Kickoff	Dia 1 (paralelo)	Disparar aprovações externas	Business verification (Meta), API access (Google)
Nível 0: Browser-Side	Dia 1	Tracking básico funcionando	Acesso ao site, credenciais de anúncios
Níveis 1-2: Server + Closed Loop	Semana 1	Atribuição completa e conversões offline	Tokens de API, credenciais do tenant
Validação & Go-Live	Fim da Semana 1	Sistema validado em produção	Testes end-to-end passando

Camadas de Tracking: Do Básico ao Avançado

Cada nível de tracking adiciona uma camada de inteligência sobre a anterior:

Nível 0 — Browser-Side (Fundação)
Pixel do Meta + Enhanced Conversions do Google Ads capturam eventos no navegador do usuário. Campos ocultos (gclid, _fbc, _fbp) preservam contexto de origem. Este nível já entrega:

• Rastreamento de cliques e pageviews
• Conversões de lead nas plataformas
• Atribuição last-click básica

Nível 1 — Server-Side (Deduplicação)
Eventos duplicados enviados via Conversions API (Meta) e Enhanced Conversions API (Google) usando event_id compartilhado. O servidor enriquece dados com hash de PII. Ganhos:

• Contagem precisa (sem duplos)
• Resistência a bloqueadores de anúncios
• Event Match Quality (EMQ) elevado

Nível 2 — Closed Loop (Receita Real)
Conversões offline disparam quando o lead vira cliente no CRM. O sistema envia de volta às plataformas o valor real do contrato. Resultado:

• Otimização de lances por ROI verdadeiro
• Atribuição fim-a-fim (clique → cliente)
• Visibilidade do funil completo

Lógica de Execução: Paralelo + Incremental

A implementação não é sequencial pura. Três princípios aceleram a entrega:

1. Kickoff em Paralelo
   A Fase 0 (aprovações externas) começa no Dia 1, enquanto você instrumenta o site. Quando o browser-side estiver validado, as credenciais de API já estarão prontas.

2. Valor Incremental
   O cliente vê tracking funcionando no fim do Dia 1, mesmo sem server-side. Cada nível adiciona capacidade sem quebrar o anterior.

3. Config-as-Code
   O trabalho pesado por cliente é configuração (uma linha em client_config, secrets no Vault), não desenvolvimento. Tags no site são padronizadas.

Marcos de Validação

Antes do go-live, quatro validações obrigatórias:

• ✅ Meta Test Events: evento aparece deduplicated (browser + servidor com mesmo event_id)
• ✅ Google Ads Diagnostic: Enhanced Conversions registrando, uploads offline confirmados
• ✅ End-to-End Real: formulário → CRM → mudança de status → conversão offline nas plataformas
• ✅ Métricas de Qualidade: EMQ ≥ 8.0, match rate offline ≥ 50%

Gargalo Determinante: Aprovações Externas

O passo mais lento não depende da sua execução técnica. Meta e Google exigem:

• Meta: Business verification completa para gerar System User token (pode levar 3-5 dias úteis)
• Google: Developer token ativo e acesso de API na conta do cliente (aprovação manual do Google)

Por isso a Fase 0 dispara imediatamente, antes mesmo de tocar no código do site.

Tempo-Alvo de Implementação

Ritmo ideal por cliente:

• Dia 1: Nível 0 no ar (tracking básico funcionando)
• Semana 1: Níveis 1-2 validados (server-side + closed loop)
• Dia 8-10: Go-live em produção com monitoramento ativo

O trabalho real por cliente é 4-6 horas de config + validação. O restante é tempo de espera em aprovações externas e testes de estabilidade.

Pré-requisitos de Infraestrutura da Agência

(seção não gerada — tente novamente)

Fase 0: Kickoff e Coleta de Credenciais

A Fase 0 é o gargalo silencioso de qualquer implementação de tracking: ela depende de aprovações externas (Google, Meta) que podem levar de 24 horas a 7 dias. Por isso, inicie esta fase no Dia 1, em paralelo com a instrumentação do site. Quando o browser-side estiver validado, o server-side já estará destravado.

Por que começar imediatamente?

Dois processos críticos travam o server-side tracking e o closed loop:

1. Meta Business Verification — necessária para gerar um System User token com permissões de API no dataset (Pixel). Sem ela, você não consegue enviar eventos server-side.
2. Google Ads API Access — o developer token da agência precisa de aprovação do Google (nível Standard ou superior) para fazer upload de conversões offline. O processo pode exigir documentação da agência e revisão manual.

Se você esperar o Nível 0 estar 100% pronto para depois pedir esses acessos, adiciona uma semana de atraso evitável.

---

Checklist de acessos e credenciais

Para cada novo cliente, colete os seguintes acessos antes de iniciar a instrumentação:

Acessos às plataformas

Plataforma	Nível de acesso necessário	Quem fornece
Meta Business Manager	Admin ou System User	Cliente ou agência (se gestão total)
Google Ads	Admin	Cliente ou agência
Google Analytics 4	Editor ou Admin	Cliente
Site/Landing Page	Acesso ao código-fonte (FTP, CMS, repo Git)	Cliente ou dev do cliente
CRM	Admin ou acesso ao banco de dados	Cliente ou agência (se infra própria)

Verificações e aprovações externas

Meta:

• Business verification iniciada — acesse Meta Business Settings → Security Center e complete o processo de verificação. Você precisará enviar documentos da empresa (CNPJ, contrato social, comprovante de endereço).
• Domínio verificado — no Business Manager, vá em Brand Safety → Domains e adicione o domínio da landing page. Use DNS (TXT record) ou upload de arquivo HTML.
• System User criado — em Users → System Users, crie um usuário de sistema com permissão de "Manage Ads" e "Manage Business Extensions" no dataset (Pixel) do cliente.

Google:

• Developer token solicitado — se a agência ainda não tem, solicite em Google Ads API Center. O token é da agência, não do cliente, e serve para todos os clientes.
• Nível de acesso confirmado — verifique se o token está em Standard ou Basic. O nível Basic limita uploads a 15 mil conversões/dia (suficiente para 99% dos casos).
• OAuth 2.0 configurado — crie um projeto no Google Cloud Console, ative a Google Ads API e gere credenciais OAuth (client ID + client secret). Você usará isso para gerar o refresh_token de cada cliente.

---

IDs e tokens a coletar (por cliente)

Após os acessos estarem liberados, extraia os seguintes identificadores:

Meta

• dataset_id (também chamado de Pixel ID) — encontre em Events Manager → Data Sources → [Nome do Pixel] → Settings. Formato: 1234567890123456.
• pixel_id — mesmo valor do dataset_id (Meta usa os dois termos de forma intercambiável).
• System User token — após criar o System User, gere um token de longa duração (60 dias ou permanente) com escopo ads_management e business_management. Guarde esse token no Vault (nunca em código).

Google Ads

• customer_id — ID da conta do cliente, sem traços. Encontre no canto superior direito do Google Ads (ex: 1234567890).
• login-customer-id — ID da conta MCC (gerente) da agência. Também sem traços.
• conversion_action_id — ID da ação de conversão de Lead. Acesse Tools → Conversions → [Nome da conversão] → Tag setup. O ID aparece na URL ou no código do snippet (ex: 987654321).
• refresh_token — token OAuth gerado após o cliente autorizar a agência a acessar a conta dele. Use a Google OAuth Playground ou um script próprio para obter o token.

---

Roteiro de kickoff (Dia 1)

1. Reunião de alinhamento (30 min)

   • Apresente o escopo do tracking (níveis 0, 1 e 2).
   • Explique os prazos: Nível 0 no ar em 24h, server-side em 7 dias (dependendo das aprovações).
   • Colete os acessos listados acima.

2. Dispare as verificações externas (15 min)

   • Meta: inicie a Business verification.
   • Google: confirme que o developer token da agência está ativo.
   • Domínio: adicione o TXT record de verificação no DNS do cliente.

3. Organize as credenciais (15 min)

   • Crie uma pasta segura (1Password, Bitwarden, ou Vault do Supabase) para guardar tokens e IDs.
   • Preencha a Ficha do Cliente (seção final do checklist) com os valores coletados.

4. Inicie a instrumentação em paralelo

   • Enquanto aguarda as aprovações, implemente o Nível 0 (browser-side). Ele não depende de API e já entrega valor rápido.

---

Tempo estimado

• Coleta de acessos: 1–2 horas (se o cliente responder rápido).
• Verificações externas: 1–7 dias (fora do seu controle).
• Extração de IDs: 30 minutos (após os acessos estarem liberados).

Dica: Use um template de e-mail para solicitar acessos. Exemplo:

Assunto: [Cliente] — Acessos para Implementação de Tracking

Olá [Nome],

Para implementar o tracking multi-nível no site de [Cliente], precisamos dos seguintes acessos:

• Meta Business Manager (nível Admin)
• Google Ads (nível Admin)
• Google Analytics 4 (nível Editor)
• Acesso ao código do site (FTP, CMS ou repositório Git)
• Acesso ao CRM (se aplicável)

Também iniciaremos a verificação de negócio no Meta e a configuração da API do Google Ads. Qualquer atraso nesses processos pode adiar o go-live do server-side tracking.

Podemos agendar 30 minutos amanhã para alinhar?

---

Próximo passo

Com os acessos em mãos e as verificações iniciadas, você está pronto para o Dia 1: Implementação do Nível 0 (Browser-Side). Não espere as aprovações externas ficarem prontas — o Pixel e o Enhanced Conversions já funcionam sem API.

Por que iniciar as aprovações externas imediatamente?

O gargalo crítico de qualquer implementação de tracking avançado não está na sua equipe — está nas plataformas externas. Dois processos de aprovação podem transformar uma entrega de 7 dias em um projeto de 30+ dias se não forem disparados no momento certo:

Business Verification do Meta (Facebook/Instagram)

O que é: Processo de validação da identidade e legitimidade do negócio que permite criar System User tokens — requisito obrigatório para enviar eventos server-side via Conversions API.

Por que demora:

• Análise manual de documentos (CNPJ, contrato social, comprovante de endereço)
• Verificação de domínio e consistência de informações públicas
• Fila de aprovação que pode variar de 2 a 14 dias úteis (ou mais em períodos de alta demanda)
• Possibilidade de solicitação de documentos adicionais, reiniciando o prazo

Impacto no projeto: Sem o System User token aprovado, você não consegue enviar eventos server-side. O tracking fica limitado ao Pixel (browser-side), perdendo:

• Resiliência contra bloqueadores de anúncios
• Dados de conversões que acontecem fora do navegador
• Capacidade de closed-loop (conversão offline)

Acesso à API do Google Ads

O que é: Permissão para usar a Google Ads API e enviar Enhanced Conversions e conversões offline programaticamente.

Por que demora:

• Requer Developer Token em nível Standard (Basic só permite acesso de teste)
• Processo de aprovação avalia histórico da conta MCC, volume de gastos e conformidade
• Google exige formulário detalhado sobre o caso de uso e arquitetura
• Tempo médio: 3 a 10 dias úteis, mas pode chegar a 3 semanas se houver pendências

Impacto no projeto: Sem acesso à API, você não consegue:

• Enviar Enhanced Conversions server-side (apenas browser-side via gtag)
• Registrar conversões offline (cliente fechou contrato 15 dias depois do clique)
• Automatizar upload de listas de clientes para otimização de lances

A estratégia de paralelização

Dia 1 — duas frentes simultâneas:

Frente Técnica (sua equipe)	Frente Burocrática (plataformas)
Instrumentar site com Pixel + gtag	Iniciar Business Verification (Meta)
Configurar formulários e botões WA	Solicitar acesso à API (Google)
Validar browser-side tracking	Aguardar aprovações externas
Entrega: Nível 0 funcionando	Desbloqueio: Nível 1 e 2 liberados

Resultado: Quando o browser-side estiver validado (fim da Semana 1), as aprovações externas já estarão prontas ou em estágio avançado. Você não perde tempo de projeto esperando.

Checklist de início imediato (Fase 0)

Meta — Business Verification:

• Acessar Business Settings → Security Center → Business verification
• Preparar documentos: CNPJ, contrato social, comprovante de endereço comercial
• Submeter formulário e aguardar e-mail de confirmação
• Monitorar status diariamente (pode solicitar docs adicionais)

Google Ads — API Access:

• Acessar Google Ads API Center na conta MCC
• Preencher formulário de solicitação de Developer Token (nível Standard)
• Descrever caso de uso: "Enhanced Conversions e conversões offline para clientes de agência jurídica"
• Aguardar e-mail de aprovação (verificar spam)

Custo de atrasar

Cenário real:

• Cliente aprova o projeto na segunda-feira
• Você implementa browser-side em 2 dias (quarta-feira)
• Só então inicia as aprovações externas
• Meta aprova em 7 dias (quarta-feira seguinte)
• Google aprova em 10 dias (sábado seguinte)
• Server-side só sobe 14 dias depois do kickoff

Cenário otimizado (Fase 0 no Dia 1):

• Cliente aprova na segunda-feira
• Você dispara aprovações E implementa browser-side em paralelo
• Meta aprova em 7 dias (segunda-feira seguinte)
• Google aprova em 10 dias (quinta-feira seguinte)
• Server-side sobe 10 dias depois do kickoff (4 dias de ganho)

Regra de ouro: Trate a Fase 0 como pré-requisito não-bloqueante. O cliente já vê valor (browser-side) enquanto você destrava o futuro (server-side + closed loop).

Dia 1: Implementação do Nível 0 (Browser-Side)

(seção não gerada — tente novamente)

Fundação nas Plataformas de Anúncios

Antes de instrumentar o site, é preciso preparar o terreno nas plataformas de anúncios. Esta fundação garante que os eventos capturados no navegador sejam corretamente atribuídos e processados pelo Google Ads e Meta Ads. Sem ela, você terá dados fragmentados ou perdidos.

Google Ads: Configuração Base

1. Auto-Tagging (GCLID)

O auto-tagging adiciona automaticamente o parâmetro gclid (Google Click Identifier) a todas as URLs de destino dos seus anúncios. Este identificador é essencial para atribuição precisa.

Como ativar:

1. Acesse Google Ads → Configurações → Configurações da conta
2. Localize a seção Auto-tagging
3. Marque a opção Marcar o URL ao qual as pessoas clicam no meu anúncio
4. Salve as alterações

⚠️ Atenção: Se você usa UTMs personalizados, certifique-se de que o auto-tagging está configurado para substituir os parâmetros manuais, não para conviver com eles (isso evita conflitos de atribuição).

2. Ação de Conversão de Lead

Crie (ou confirme) a ação de conversão que será o marco principal do funil. Para escritórios de advocacia, tipicamente é o envio do formulário de contato.

Configuração recomendada:

Campo	Valor Sugerido
Categoria	Lead
Nome	Lead - Formulário de Contato
Valor	Use o mesmo para todas as conversões (ex: R$ 100) ou não atribua valor
Contagem	Uma (cada envio de formulário conta uma vez)
Janela de conversão	90 dias (padrão para leads jurídicos)
Janela de view-through	1 dia (conservador para evitar atribuição inflada)
Modelo de atribuição	Baseado em dados (se houver volume) ou Último clique

Onde criar: Google Ads → Metas → Conversões → + Nova ação de conversão → Site

3. Enhanced Conversions for Leads (EC)

As Enhanced Conversions enviam dados hash (email, telefone, nome) junto com a conversão, melhorando o match rate e a atribuição cross-device.

Como ativar:

1. Na ação de conversão criada acima, vá em Configurações
2. Localize Enhanced conversions
3. Escolha o método Google Tag Manager ou Google tag (gtag.js)
4. Marque Ativar enhanced conversions para leads
5. Salve

💡 Importante: O horus-tracker.js já envia os dados hash automaticamente quando o formulário é submetido. Você só precisa ativar o recurso no Google Ads.

Validação rápida:

• Após ativar, o status da conversão deve mostrar "Enhanced conversions registrando" em até 24h
• Se aparecer "Não detectado", revise se o email está sendo capturado no formulário

---

Meta Ads: Dataset e Domínio Verificado

1. Verificação de Domínio

O Meta exige que você prove ser proprietário do domínio antes de usar recursos avançados como a API de Conversões.

Passos:

1. Acesse Meta Business Suite → Configurações de negócios → Segurança da marca → Domínios
2. Clique em Adicionar e insira o domínio da landing page (ex: contato.seuescritorio.com.br)
3. Escolha o método de verificação:
   • DNS (TXT record): mais confiável, mas requer acesso ao painel de DNS
   • Upload de arquivo HTML: mais rápido, mas requer acesso FTP/cPanel
   • Meta-tag no <head>: intermediário, requer acesso ao código-fonte
4. Siga as instruções e aguarde a confirmação (geralmente instantânea para DNS)

⚠️ Atenção: Verifique o domínio raiz (ex: seuescritorio.com.br), não apenas o subdomínio. Isso evita problemas futuros com múltiplas landing pages.

2. Confirmação de HTTPS

O Meta não aceita eventos de sites sem certificado SSL válido. Antes de prosseguir:

• Acesse a landing page e confirme o cadeado verde na barra de endereços
• Teste com SSL Labs (nota A ou B é suficiente)
• Certifique-se de que não há conteúdo misto (imagens/scripts HTTP em página HTTPS)

3. Dataset (Pixel) no Events Manager

O Dataset é o "contêiner" que recebe os eventos do Pixel (browser-side) e da API de Conversões (server-side). Ele será o ponto central de deduplicate.

Criar ou confirmar:

1. Acesse Events Manager → Fontes de dados
2. Se já existe um Pixel para o cliente, use-o. Caso contrário:
   • Clique em Adicionar → Pixel do Meta
   • Nomeie de forma clara: [Nome do Cliente] - Site
   • Escolha Instalação manual (não use integração de plataforma)
3. Anote o Pixel ID (número de 15 dígitos) — você precisará dele na instrumentação
4. Anote também o Dataset ID (aparece na URL quando você abre o Pixel no Events Manager: .../datasets/DATASET_ID/...)

Configuração de Deduplicate:

• No Dataset, vá em Configurações → Deduplicação de eventos
• Certifique-se de que está ativada (padrão)
• Janela de deduplicate: 48 horas (padrão, suficiente)

💡 Como funciona: Quando o mesmo evento chega pelo Pixel (browser) e pela API de Conversões (server) com o mesmo event_id, o Meta mantém apenas um registro, priorizando os dados server-side.

---

Checklist de Validação da Fundação

Antes de partir para a instrumentação do site, confirme:

Google Ads:

• Auto-tagging ativado e testado (clique em um anúncio de teste e veja se o gclid aparece na URL)
• Ação de conversão de Lead criada e configurada
• Enhanced Conversions for Leads ativado na ação de conversão
• Status da ação mostra "Registrando" ou "Ativo" (não "Não verificado")

Meta Ads:

• Domínio verificado no Business Manager (badge verde ao lado do domínio)
• HTTPS válido e sem avisos no navegador
• Dataset (Pixel) criado no Events Manager
• Pixel ID e Dataset ID anotados
• Deduplicação de eventos ativada no Dataset

Acesso e Permissões:

• Conta de anúncios do Google Ads com acesso de Administrador para a agência
• Meta Business Manager com acesso de Administrador para a agência
• Developer token do Google Ads confirmado (nível de acesso Standard ou superior)
• Business verification do Meta iniciada (necessária para System User token)

---

Tempo Estimado

Tarefa	Tempo (primeira vez)	Tempo (clientes seguintes)
Auto-tagging + ação de conversão	15 min	5 min
Enhanced Conversions	5 min	2 min
Verificação de domínio Meta	30 min (DNS) ou 10 min (HTML)	10 min (se domínio já verificado)
Criação de Dataset	5 min	3 min
Total	~55 min	~20 min

Dica de eficiência: Para clientes da mesma agência, o domínio raiz costuma ser o mesmo (ex: agenciajuridica.com.br). Verifique-o uma vez e reutilize para todos os subdomínios.

---

Próximos Passos

Com a fundação pronta, você está preparado para:

1. Instrumentar o site (Pixel, horus-tracker.js, formulários)
2. Validar eventos no navegador (Test Events do Meta, GTM Preview)
3. Partir para server-side (Níveis 1 e 2)

Sem esta base, os eventos chegarão fragmentados ou não chegarão. Invista o tempo necessário aqui — é o alicerce de tudo.

Instrumentação do Site e Landing Page

(seção não gerada — tente novamente)

Semana 1: Níveis 1 e 2 (Server-Side e Closed Loop)

(seção não gerada — tente novamente)

Coleta de Credenciais Específicas do Cliente

Esta etapa acontece durante a Semana 1, após o Nível 0 estar validado. Aqui você reúne os identificadores e tokens necessários para ativar o server-side tracking e o closed loop. Cada cliente exige seu próprio conjunto de credenciais — são elas que permitem ao Porteiro enviar eventos em nome da conta de anúncios.

Meta (Facebook/Instagram Ads)

O que coletar:

Credencial	Onde encontrar	Exemplo
dataset_id	Meta Events Manager → Dataset (Pixel) → Configurações → ID do conjunto de dados	123456789012345
pixel_id	Meta Events Manager → Dataset → Visão geral (número logo abaixo do nome)	987654321098765
System User token	Meta Business Settings → Usuários → System Users → Gerar novo token	EAAx... (começa com EAA)

Passo a passo para o System User token:

1. Acesse Meta Business Settings da conta do cliente.
2. Vá em Usuários → System Users.
3. Crie um novo System User (ex.: "Horus Tracking") ou use um existente.
4. Clique em Gerar novo token e selecione o App da agência (ou o app padrão do Business).
5. Conceda as permissões:
   • ads_management
   • business_management
   • ads_read (opcional, mas recomendado)
6. Atribua o System User ao Dataset (Pixel) com permissão de Administrador ou Editor.
7. Copie o token gerado — ele não será exibido novamente.

⚠️ Atenção: O System User token só pode ser gerado após a Business verification estar aprovada. Inicie esse processo na Fase 0 para evitar atrasos.

---

Google Ads

O que coletar:

Credencial	Onde encontrar	Exemplo
customer_id	Google Ads → Configurações → Detalhes da conta → Número do cliente	1234567890 (sem traços)
login-customer-id	Conta de gerente (MCC) da agência	9876543210 (sem traços)
conversion_action_id	Google Ads → Metas → Conversões → Clique na conversão → URL da página	Último número da URL (ex.: .../conversions/12345678)
refresh_token	Gerado via OAuth 2.0 Playground ou script de autorização	1//... (começa com 1//)

Passo a passo para o refresh_token:

1. Use o OAuth 2.0 Playground do Google ou um script local de autorização.
2. Configure o Client ID e Client Secret do projeto OAuth da agência.
3. Solicite os escopos:
   • https://www.googleapis.com/auth/adwords
4. Autorize com uma conta que tenha acesso administrativo à conta Google Ads do cliente.
5. Troque o código de autorização por um refresh_token.
6. Guarde o token com segurança — ele permite acesso contínuo sem nova autorização.

💡 Dica: O refresh_token é gerado uma vez e reutilizado. Se a conta do cliente já estiver vinculada ao MCC da agência, você pode usar um único token para múltiplos clientes (desde que o token tenha sido autorizado com uma conta que enxergue o MCC).

Validar o conversion_action_id:

• Acesse Metas → Conversões no Google Ads.
• Localize a ação de conversão de Lead (ex.: "Lead Form Submit").
• Clique nela e copie o ID numérico da URL.
• Confirme que o tipo é Import ou Website (não App).

---

Checklist de validação das credenciais

Antes de provisionar o tenant, valide:

• Meta: Token testado com uma chamada à API (ex.: GET /{dataset_id} retorna 200).
• Meta: System User tem permissão no Dataset (não apenas no Business).
• Google: customer_id confirmado no formato correto (10 dígitos, sem traços).
• Google: conversion_action_id corresponde à ação de Lead (não Purchase ou outra).
• Google: refresh_token testado (troca por access_token bem-sucedida).
• Google: Conta do cliente vinculada ao MCC da agência (confirme o login-customer-id).

---

Onde armazenar as credenciais

Todas as credenciais sensíveis devem ser guardadas no Supabase Vault (ou equivalente seguro):

• meta_system_user_token_{tenant}
• google_refresh_token_{tenant}
• google_developer_token (compartilhado entre clientes, nível agência)
• google_client_secret (compartilhado, nível agência)

Nunca commite tokens ou IDs sensíveis no código. A tabela tracking.client_config armazena apenas nomes dos segredos, não os valores.

---

Tempo estimado

• Meta: 10–15 minutos (se Business verification já estiver aprovada).
• Google: 15–20 minutos (se o cliente já estiver no MCC e o OAuth configurado).
• Total por cliente: ~30 minutos, assumindo infraestrutura OAuth pronta.

Se a Business verification ou o acesso à API do Google ainda estiverem pendentes, esse tempo pode se estender para dias — por isso a Fase 0 começa no Dia 1.

Provisionamento do Tenant no Sistema

(seção não gerada — tente novamente)

Como Configurar o Closed Loop: Trigger vs Action

(seção não gerada — tente novamente)

Validação Completa Antes do Go-Live

Antes de escalar o investimento em mídia, você precisa confirmar que todos os três níveis de tracking estão funcionando e conversando entre si. Esta fase de validação é crítica: um erro aqui multiplica custos e compromete a atribuição por semanas.

Por que validar antes de ir ao ar?

• Evitar desperdício de budget: conversões mal rastreadas levam o algoritmo a otimizar para o público errado.
• Garantir atribuição confiável: sem validação, você não saberá se o closed loop está realmente fechando.
• Proteger a reputação da agência: clientes percebem quando os números não batem.

A validação acontece em quatro camadas: Meta, Google, end-to-end e qualidade dos dados.

---

1. Meta: Test Events e Deduplicação

O que validar:

• Lead de teste aparece no Events Manager → Test Events com o código de teste ativo
• O mesmo event_id aparece duas vezes: uma vez via Pixel (browser) e outra via Conversions API (servidor)
• O Meta marca o evento como "Deduplicated" — isso confirma que o sistema reconheceu que são o mesmo lead
• O Event Match Quality (EMQ) do evento servidor está ≥ 8.0 (idealmente 9.0+)

Como testar:

1. Ative um test_event_code temporário na config do tenant.
2. Preencha o formulário na landing com dados reais (seu email, telefone com DDI).
3. Acesse Events Manager → Test Events e filtre pelo código.
4. Confirme que aparecem dois eventos Lead com o mesmo event_id e timestamp próximo.
5. Verifique se há a tag "Deduplicated" — se não houver, o event_id não está sendo passado corretamente do browser pro servidor.

Troubleshooting comum:

Problema	Causa provável	Solução
Evento só aparece via Pixel	Porteiro não está recebendo o lead	Verifique se o action do form aponta pro /leads e se o CRM está enviando pro porteiro
Evento só aparece via servidor	Pixel não carregou ou consent não foi dado	Verifique console do navegador e aceite do banner LGPD
Dois eventos, mas não deduplica	event_id diferente ou ausente	Confirme que horus-tracker.js gera o event_id e o passa no campo oculto horus_event_id
EMQ < 8.0	Dados de contato incompletos ou mal formatados	Revise normalização de email/telefone no porteiro

---

2. Google Ads: GCLID, Enhanced Conversions e Diagnóstico

O que validar:

• GCLID capturado: no console do navegador (ou GTM Preview), confirme que o parâmetro gclid está presente na URL após clicar no anúncio.
• Campos ocultos preenchidos: horus_gclid, horus_fbclid, horus_fbc, horus_fbp devem estar populados no momento do submit (inspecione o form antes de enviar).
• Enhanced Conversions ativo: no painel do Google Ads, vá em Tools → Conversions → [sua ação de Lead] e confirme que o diagnóstico mostra "Enhanced conversions are recording".
• Upload de conversões offline: após marcar um lead como "cliente" no CRM, acesse Tools → Conversions → Uploads e veja se há registros recentes da sua ação.

Como testar:

1. Clique em um anúncio real do Google Ads (pode ser em preview mode).
2. Abra o DevTools (F12) → Console e digite new URLSearchParams(window.location.search).get('gclid') — deve retornar uma string longa.
3. Inspecione o formulário (botão direito → Inspect) e localize os campos <input type="hidden" name="horus_gclid"> — confirme que o value está preenchido.
4. Envie o lead de teste.
5. No Google Ads, vá em Conversions → [ação de Lead] → Diagnostics e confirme que há uploads recentes nas últimas horas.
6. Marque o lead como "cliente" no CRM e, após ~15 minutos, verifique se a conversão offline aparece em Uploads.

Troubleshooting comum:

Problema	Causa provável	Solução
GCLID não capturado	Auto-tagging desligado	Ative em Account Settings → Auto-tagging
Enhanced Conversions não registra	Dados de contato não normalizados ou ausentes	Revise hash SHA-256 de email/telefone no payload
Upload offline não aparece	Trigger do CRM não disparou ou gclid não foi salvo	Confirme que o lead tem gclid no banco e que o trigger está ativo

---

3. Teste End-to-End Real

Este é o teste mais importante: simula o fluxo completo de um lead que vira cliente.

Passo a passo:

1. Clique no anúncio (Meta ou Google) em um dispositivo real (não simulador).
2. Preencha o formulário com dados reais (use seu email/telefone pessoal).
3. Confirme no CRM: o lead deve aparecer com os campos de atribuição preenchidos (gclid, fbclid, utm_source, etc.).
4. Marque como "cliente" no CRM (ou o status que dispara o closed loop).
5. Aguarde 15 minutos e verifique:
   • Meta: novo evento Purchase (ou Lead offline) no Events Manager (sem test code agora).
   • Google Ads: conversão offline na aba Uploads.
6. Confirme a dedupe offline: no Meta, o evento offline deve ter o mesmo event_id do lead original (se você guardou o ID no CRM).

Checklist do teste:

• Lead aparece no CRM com atribuição completa
• Status "cliente" dispara o webhook/trigger
• Conversão offline sobe no Meta (Events Manager)
• Conversão offline sobe no Google Ads (Uploads)
• contract_value correto (se aplicável)
• Timestamp da conversão offline corresponde à data de fechamento

---

4. Métricas de Qualidade: EMQ e Match Rate

Essas métricas determinam quanto do seu tracking o algoritmo consegue usar.

Event Match Quality (EMQ) — Meta

Meta: ≥ 8.0 (idealmente 9.0+)

Onde ver:

• Events Manager → Dataset → Event Match Quality (coluna da tabela de eventos)

O que melhora o EMQ:

Parâmetro	Peso	Como garantir
em (email)	Alto	Normalizar (lowercase, trim) e hashear SHA-256
ph (telefone)	Alto	Formato E.164 (+5511999999999) antes do hash
client_user_agent	Médio	Capturar do header User-Agent no servidor
client_ip_address	Médio	IP real do usuário (não do servidor)
fbc / fbp	Médio	Cookies do Pixel, enviados pelo browser
fn, ln, ct, st, zp	Baixo	Nome, cidade, estado, CEP (se disponíveis)

Se EMQ < 8.0:

1. Revise a normalização de email/telefone no porteiro.
2. Confirme que client_ip_address e client_user_agent estão sendo enviados.
3. Adicione parâmetros opcionais (nome, localização) se o formulário captura.

Match Rate — Google Ads (Conversões Offline)

Meta: ≥ 50% (idealmente 70%+)

Onde ver:

• Google Ads → Tools → Conversions → Uploads → clique no upload → coluna "Match rate"

O que melhora o match rate:

• GCLID sempre presente: é o identificador mais confiável.
• Email e telefone normalizados: lowercase, sem espaços, telefone com DDI.
• Timestamp preciso: conversão offline deve ter timestamp real do fechamento, não do upload.

Se match rate < 50%:

1. Confirme que o gclid está sendo salvo no CRM e enviado no upload.
2. Revise a normalização de email (Google é sensível a maiúsculas).
3. Verifique se o conversion_date_time está no formato ISO 8601 correto.

---

Checklist Final de Validação

Antes de remover o test_event_code e declarar go-live:

• Meta Test Events: evento deduplicated com EMQ ≥ 8.0
• Console/GTM: gclid, _fbc, _fbp capturados e campos ocultos preenchidos
• Google Ads: diagnóstico de EC mostra "recording", uploads recentes visíveis
• End-to-end real: lead → CRM com atribuição → cliente → conversão offline nas duas plataformas
• EMQ ≥ 8.0 confirmado em eventos reais (fora do test code)
• Match rate ≥ 50% confirmado nos uploads do Google Ads
• Sem erros no porteiro: logs do Supabase Functions sem 4xx/5xx relacionados ao tenant

Só depois de todos os itens acima estarem verdes, você pode:

1. Remover o test_event_code da config.
2. Definir a conversão como primária no Google Ads (evita dupla contagem com GA4).
3. Escalar o budget com confiança.

---

Ferramentas de Validação Recomendadas

• Meta Pixel Helper (extensão Chrome): confirma disparo do Pixel em tempo real.
• Google Tag Assistant (extensão Chrome): valida tags do Google (GA4, Ads).
• GTM Preview Mode: vê todos os eventos disparados e variáveis capturadas.
• Supabase Logs (Functions): monitora requisições pro porteiro e respostas das APIs.
• Postman/Insomnia: testa manualmente o endpoint /leads do CRM (simula submit do form).

---

Próximo Passo

Com a validação completa, você está pronto para o Go-Live e Rotina de Monitoramento — a última etapa antes de declarar o cliente em produção.

Checklist de Validação Técnica

(seção não gerada — tente novamente)

Go-Live e Rotina de Monitoramento

Depois de validar todos os níveis de tracking, o go-live marca a transição do ambiente de testes para produção plena. Esta fase exige atenção a três frentes: limpeza de artefatos de validação, configuração final das plataformas de anúncios e estabelecimento de uma rotina de monitoramento que garanta a saúde contínua do sistema.

Limpeza Pós-Validação

Antes de escalar o investimento em mídia, remova todos os elementos utilizados exclusivamente para testes:

• Meta Test Event Code: acesse o Events Manager, navegue até o dataset do cliente e remova o test_event_code da configuração. Eventos de produção não devem mais carregar este parâmetro.
• Eventos de teste: limpe manualmente os eventos de teste da interface do Meta (Test Events) e do Google Ads (diagnóstico de conversões) para evitar poluir os relatórios iniciais.
• Alertas temporários: desative quaisquer logs verbosos ou alertas de debug que tenham sido ativados durante a validação no Porteiro ou no CRM.

Configuração de Conversão Primária

Para evitar dupla contagem entre o Google Ads nativo e o GA4, defina explicitamente qual conversão será usada como métrica principal:

Plataforma	Ação Requerida	Impacto
Google Ads	Marque a ação de conversão de Lead como Primária nas configurações de conversões	O Smart Bidding priorizará esta métrica; conversões secundárias (ex: GA4) não influenciam lances
Meta Ads	Defina o evento Lead (ou Purchase, conforme o marco escolhido) como evento de conversão na campanha	O algoritmo de otimização focará neste evento específico
GA4	Marque o evento correspondente como conversão nas configurações de eventos	Permite análise cross-platform, mas não interfere nos lances do Google Ads se a conversão primária estiver corretamente configurada

Exemplo de fluxo de configuração no Google Ads:

1. Acesse Ferramentas e Configurações → Medição → Conversões
2. Localize a ação de conversão "Lead" criada na Fase 0
3. Clique em Editar configurações
4. Na seção Objetivo e tipo de ação, selecione Primária
5. Salve as alterações

Rotina de Revisão — Primeiros 14 Dias

Nos primeiros 14 dias pós-go-live, agende revisões semanais (duas no total) para detectar anomalias rapidamente. Use este checklist:

Semana 1 (Dia 7)

• Volume de eventos: compare o volume de PageView, Lead e conversões offline com a baseline esperada (baseada no histórico pré-tracking ou em benchmarks do setor)
• EMQ (Event Match Quality): confirme que se mantém ≥ 8.0 no Meta. Quedas indicam problemas de captura de PII (email, telefone) ou de hash
• Match rate offline: verifique no Google Ads (Diagnóstico de Conversões) e no Meta (Event Manager) se o match rate está ≥ 50%. Taxas baixas sugerem dados incompletos ou dessincronizados
• Dedupe: inspecione manualmente 5–10 leads recentes no Meta Test Events (mesmo após remover o code, você ainda pode filtrar por event_id na aba de eventos). Confirme que eventos com mesmo event_id aparecem como deduplicated
• Latência do closed loop: meça o tempo entre a marcação de "cliente" no CRM e a chegada da conversão offline nas plataformas. Deve ser < 5 minutos. Atrasos maiores indicam problemas no trigger ou na fila do Porteiro
• Erros no Porteiro: revise os logs do Supabase Functions (aba Logs do Edge Function porteiro) em busca de HTTP 4xx ou 5xx. Erros 401/403 indicam credenciais expiradas; 400 indicam payload malformado

Semana 2 (Dia 14)

• Consistência temporal: compare os volumes de conversões (browser-side vs. server-side vs. offline) ao longo dos 7 dias. Discrepâncias crescentes sugerem drift de configuração
• Atribuição no CRM: valide que 100% dos leads têm utm_source, utm_medium e gclid/fbclid preenchidos. Campos vazios indicam falha na captura de parâmetros ocultos
• Custo por conversão: se o CPL (browser-side) e o CPA (offline) divergirem muito (>30%), investigue se o closed loop está reportando todos os clientes ou se há filtros indevidos no trigger
• Feedback qualitativo: converse com o time de vendas do cliente. Leads estão chegando com qualidade esperada? Há padrões de origem (ex: só Google, só Meta) que merecem ajuste de budget?

Rotina de Revisão Mensal

Após os primeiros 14 dias, estabeleça uma revisão mensal mais aprofundada. Agende para o dia 1 de cada mês (analisando o mês anterior completo):

Checklist Mensal

• Auditoria de EMQ: exporte o histórico de EMQ do Meta via API (ou manualmente, se o volume for baixo) e calcule a média mensal. Investigue quedas > 0.5 pontos
• Match rate offline — tendência: compare o match rate do mês atual com o anterior. Quedas progressivas podem indicar mudanças no fluxo de captura de dados (ex: campo de telefone tornado opcional)
• Conversões offline vs. browser-side — ratio: calcule a taxa de conversão de Lead → Cliente. Se o ratio mudar drasticamente (ex: de 10% para 5%), pode haver problema no closed loop ou mudança real no processo de vendas do cliente
• Renovação de credenciais: tokens do Google OAuth expiram a cada 6 meses (ou antes, dependendo da configuração). Verifique a data de emissão do refresh_token e agende renovação proativa 15 dias antes do vencimento
• Revisão de contract_value: se o valor fixo proxy foi usado, compare com os valores reais de contratos fechados no mês. Ajuste o proxy se a discrepância for > 20%
• Performance de campanhas por tenant: se a agência gerencia múltiplos clientes, compare KPIs (CPL, CPA, ROAS) entre tenants. Outliers podem indicar problemas técnicos ou oportunidades de otimização
• Backup de configuração: exporte a linha de tracking.client_config do tenant e salve em repositório versionado (ex: Git). Facilita rollback em caso de alteração acidental

Documentação de Incidentes

Se durante as revisões você identificar anomalias, documente no formato abaixo (pode ser uma planilha compartilhada ou um board no Notion/Linear):

Data	Tenant	Sintoma	Causa Raiz	Ação Corretiva	Responsável	Status
2025-01-15	acme-law	EMQ caiu de 8.5 para 6.2	Campo de telefone removido do form	Telefone restaurado; hash revalidado	João	✅ Resolvido
2025-01-20	beta-legal	Conversões offline pararam	refresh_token expirado	Token renovado via OAuth flow	Maria	✅ Resolvido

Esta documentação serve como base de conhecimento para acelerar troubleshooting futuro e treinar novos membros da equipe.

Alertas Automatizados (Opcional, mas Recomendado)

Para reduzir a carga de monitoramento manual, configure alertas automáticos:

• Supabase: crie uma Database Webhook que dispare um alerta no Slack/email se o volume de leads em crm.leads cair > 50% em relação à média dos últimos 7 dias
• Meta: use a API de Insights para criar um script que verifique diariamente o EMQ e notifique se cair abaixo de 7.5
• Google Ads: configure um alerta de conversões na interface (Ferramentas → Regras Automatizadas) para notificar se o volume de conversões cair > 40% em 24h

Ponto de Contato com o Cliente

Ao final de cada revisão mensal, gere um relatório executivo para o cliente (1 página, formato PDF) contendo:

1. Resumo de performance: leads gerados, taxa de conversão Lead → Cliente, CPA
2. Saúde técnica: EMQ, match rate, uptime do tracking
3. Ações tomadas: correções aplicadas, otimizações implementadas
4. Próximos passos: sugestões de testes (ex: novas criativos, ajustes de segmentação)

Este relatório reforça o valor entregue pela agência e mantém o cliente informado sobre a infraestrutura invisível que sustenta os resultados.

---

Próxima seção recomendada: Troubleshooting de Problemas Comuns — um guia rápido para resolver os 10 erros mais frequentes identificados durante as revisões.

Ficha de Registro do Cliente

Esta ficha consolida todos os identificadores, credenciais e configurações essenciais de cada cliente onboardado. Mantenha uma cópia preenchida por tenant — ela serve como fonte única de verdade para troubleshooting, auditorias e handoff entre times.

Tabela de Configuração

Campo	Valor	Observações
Tenant (slug)		Identificador único no sistema (ex: escritorio-silva)
Domínio da landing		URL completa onde o tracking está instrumentado
Meta dataset_id		ID do Pixel/Dataset no Events Manager (formato numérico)
Meta pixel_id		ID legado do Pixel (pode coincidir com dataset_id)
Google customer_id		ID da conta Google Ads sem traços (ex: 1234567890)
Google login-customer-id		ID da conta MCC da agência (gerenciadora)
Google conversion_action_id		ID da ação de conversão de Lead (formato customers/{id}/conversionActions/{action})
Caminho offline	☐ Trigger ☐ Action	Método escolhido para closed loop (trigger no banco é recomendado)
contract_value (regra)		Valor fixo ou lógica (ex: "R$ 5.000 fixo" ou "campo valor_contrato do CRM")
Marcos de conversão	Lead / Schedule / Purchase	Eventos rastreados (adapte conforme jornada do cliente)
Data go-live Nível 0	//________	Quando browser-side entrou no ar
Data go-live Nível 1+2	//________	Quando server-side + closed loop foram ativados
Responsável técnico		Nome do dev/analista que fez a implementação
Status	☐ Ativo ☐ Em validação ☐ Pausado	Estado atual do tracking

Credenciais Armazenadas no Vault

Por segurança, nunca registre tokens/secrets nesta ficha. Liste apenas os nomes dos segredos no Supabase Vault:

• Meta System User token: meta_token_{tenant}
• Google Developer token: google_dev_token (compartilhado entre clientes)
• Google Client Secret: google_client_secret
• Google Refresh Token: google_refresh_token_{tenant}
• Porteiro Ingest Key: porteiro_ingest_key (compartilhada)

Checklist de Documentação Complementar

• Screenshot do Events Manager mostrando Test Event deduplicated
• Print do diagnóstico de conversão no Google Ads (Enhanced Conversions ativo)
• Registro da primeira conversão offline bem-sucedida (log do Porteiro)
• Aprovação do cliente para início do rastreamento (email/contrato)
• Mapeamento de status do CRM → evento de conversão (ex: "cliente" → Purchase)

Exemplo Preenchido

Campo	Valor	Observações
Tenant (slug)	advocacia-santos
Domínio da landing	https://advocaciasantos.com.br
Meta dataset_id	987654321098765
Meta pixel_id	987654321098765	Mesmo valor do dataset
Google customer_id	1234567890
Google login-customer-id	9876543210	MCC da agência
Google conversion_action_id	customers/1234567890/conversionActions/987654321
Caminho offline	☑ Trigger ☐ Action	Trigger na migration 0002
contract_value (regra)	R$ 8.000 fixo	Valor médio de contrato do escritório
Marcos de conversão	Lead / Schedule / Purchase	Schedule = reunião agendada
Data go-live Nível 0	15/01/2025
Data go-live Nível 1+2	22/01/2025
Responsável técnico	Ana Costa
Status	☑ Ativo ☐ Em validação ☐ Pausado

---

Dica de organização: Mantenha essas fichas em uma planilha compartilhada (Google Sheets/Notion) com controle de versão, ou em um diretório /docs/clients/ no repositório. Atualize sempre que houver mudança de credenciais, domínio ou configuração de conversão.

Gargalos Críticos e Como Antecipá-los

(seção não gerada — tente novamente)

Ritmo-Alvo de Implementação

A implementação de tracking segue um ritmo deliberadamente dividido em duas entregas de valor:

Dia 1: Valor Rápido (Nível 0 — Browser-Side)

Objetivo: Entregar atribuição funcional e captura de leads em menos de 24 horas.

O que está no ar ao final do Dia 1:

• ✅ Pixel do Meta instalado e disparando PageView + Lead
• ✅ Enhanced Conversions for Leads ativo no Google Ads
• ✅ Auto-tagging capturando gclid e fbclid
• ✅ Formulário instrumentado com campos ocultos (horus_*)
• ✅ Botões de WhatsApp rastreados
• ✅ Consentimento LGPD integrado ao tracking

Por que começar pelo browser-side?

Porque ele não depende de aprovações externas. O cliente já começa a capturar leads com atribuição correta enquanto você aguarda:

• Business verification do Meta (pode levar 3–5 dias úteis)
• Acesso à API do Google Ads (depende do nível de acesso do developer token)
• Aprovação de tokens OAuth do CRM

Esforço real: 2–4 horas de trabalho técnico (assumindo que o site já tem HTTPS e o domínio está verificado).

---

Semana 1: Closed Loop Completo (Níveis 1 e 2)

Objetivo: Habilitar server-side tracking e conversões offline antes de escalar budget.

O que está no ar ao final da Semana 1:

• ✅ Conversions API do Meta enviando eventos duplicados (deduplicated por event_id)
• ✅ Google Ads Offline Conversions subindo conversões de clientes fechados
• ✅ Tenant provisionado no sistema com credenciais seguras no Vault
• ✅ Closed loop ativo (trigger ou server action, conforme escolha)
• ✅ Validação end-to-end completa (EMQ ≥ 8.0, match rate ≥ 50%)

Por que não fazer tudo no Dia 1?

Porque o gargalo é externo, não técnico. Enquanto você aguarda:

1. Meta: Business verification + System User token com permissão no dataset
2. Google: Developer token aprovado + OAuth refresh token do cliente
3. CRM: Credenciais de API e mapeamento de status

Você já entregou valor no Dia 1. A Semana 1 é para completar o ciclo quando as aprovações destravarem.

Esforço real: 3–6 horas de trabalho técnico (config do tenant + validação + ajustes no CRM).

---

Linha do Tempo Típica

Marco	Prazo	Depende de	Entrega de Valor
Kickoff (Fase 0)	Dia 1 (paralelo)	Nada — dispare imediatamente	Aprovações externas em andamento
Browser-side (Nível 0)	Dia 1	HTTPS + domínio verificado	Atribuição e captura de leads
Credenciais coletadas	Dias 2–5	Aprovações do Meta e Google	—
Server-side (Nível 1)	Dia 5–7	Tokens aprovados	Dedupe + EMQ melhorado
Closed loop (Nível 2)	Dia 7	Acesso ao CRM	Conversões offline + ROI real
Validação completa	Dia 7	Dados reais de leads	Go-live seguro

---

Regra de Ouro: Paralelizar Aprovações

Dispare a Fase 0 no mesmo dia do kickoff. Não espere o site estar pronto. Não espere o CRM estar mapeado. As aprovações externas são o gargalo — inicie-as antes de qualquer trabalho técnico.

Se você seguir essa regra, o ritmo real fica:

• Dia 1: Browser-side no ar (2–4h de trabalho)
• Dia 7: Server-side + closed loop completos (3–6h de trabalho)
• Total de esforço técnico por cliente: 5–10 horas

O resto do tempo é espera de aprovações externas — que você antecipou.

---

Quando Escalar Budget?

Somente após a validação completa da Semana 1. Critérios mínimos:

• EMQ ≥ 8.0 no Meta
• Match rate ≥ 50% nas conversões offline
• Pelo menos 1 lead real passou pelo ciclo completo (form → CRM → conversão offline)
• Test Events do Meta mostram dedupe correto (Pixel + Servidor com mesmo event_id)

Escalar antes disso significa queimar budget sem saber se o closed loop está funcionando.

Próximos Passos Após a Implementação

(seção não gerada — tente novamente)