Facebook Catalog Validator

Um validador completo para feeds do Facebook Catalog que verifica tanto a estrutura XML quanto os eventos do Facebook Pixel nas páginas dos produtos.

🚀 Funcionalidades

• ✅ Validação XML: Verifica estrutura do feed RSS/XML segundo regras do Facebook
• 🔍 Validação de Pixel: Testa eventos ViewContent e AddToCart em páginas reais
• 🤖 Anti-Bot: Contorna proteções anti-bot usando Chrome nativo
• 📊 Relatórios Detalhados: Análises completas com erros, avisos e estatísticas
• ⚡ Múltiplos Modos: XML (rápido), Pixel (completo) ou ambos

📦 Instalação

Via NPM (Recomendado)

# Instalar globalmente
npm install -g @metricasboss/facebook-catalog-validator

# Usar o comando diretamente
facebook-catalog-validator --help

Via Código Fonte

# Clone o repositório
git clone https://github.com/metricasboss/facebook-catalog-validator.git
cd facebook_catalog_validator

# Instale as dependências
npm install

# Torne o script executável
chmod +x validator.js

🎯 Como Usar

Comandos Principais

# Validação XML apenas (rápida)
facebook-catalog-validator xml feed.xml
# ou se instalado via código fonte:
node validator.js xml feed.xml

# Validação de Pixel apenas (lenta, mas completa)
facebook-catalog-validator pixel feed.xml --limit 10

# Validação completa (XML + Pixel)
facebook-catalog-validator both feed.xml --pixel-limit 5

# Compatibilidade (executa XML)
facebook-catalog-validator feed.xml

Exemplos Práticos

# Validar feed local com limite
node validator.js xml meu-feed.xml --limit 50 --verbose

# Validar pixel de URL remota
node validator.js pixel https://example.com/feed.xml --headless --limit 10

# Validação completa com configurações específicas
node validator.js both feed.xml --limit 100 --pixel-limit 20 --headless

# Apenas erros XML
node validator.js xml feed.xml --errors-only

# Formato JSON
node validator.js xml feed.xml --format json

⚙️ Opções de Linha de Comando

Opções Globais

• --help - Mostra ajuda
• --version - Mostra versão

Validação XML

• --limit <N> - Processa apenas os primeiros N produtos
• --verbose - Saída detalhada
• --format <tipo> - Formato de saída (text, json)
• --errors-only - Mostra apenas erros
• --warnings-only - Mostra apenas avisos
• --no-colors - Desabilita cores

Validação de Pixel

• --limit <N> - Processa apenas os primeiros N produtos
• --headless - Executa sem interface gráfica (mais rápido)
• --skip-errors - Continua mesmo com erros
• --concurrent <N> - Número de workers paralelos (padrão: 1)
• --timeout <ms> - Timeout por página (padrão: 30000ms)
• --wait-after-click <ms> - Tempo após clique no botão (padrão: 3000ms)

Comando "both"

• Combina todas as opções XML e Pixel
• --pixel-limit <N> - Limite específico para validação de pixel

📋 Regras de Validação XML

O validador verifica os seguintes campos obrigatórios:

Campos Obrigatórios

• g:id - ID único do produto (max 100 caracteres)
• g:title - Título do produto (max 200 caracteres)
• g:description - Descrição (max 9.999 caracteres)
• g:link - URL válida do produto
• g:image_link - URL válida da imagem
• g:availability - "in stock" ou "out of stock"
• g:price - Formato: "99.99 BRL"
• g:brand - Marca (max 100 caracteres)
• g:condition - "new", "refurbished" ou "used"

Validações Adicionais

• ⚠️ Título > 65 caracteres (risco de corte)
• ❌ IDs duplicados
• ❌ URLs malformadas
• ❌ Formatos de preço incorretos

🔍 Validação de Pixel

O que é validado:

• ViewContent: Evento disparado ao carregar página do produto
• AddToCart: Evento disparado ao clicar em "Adicionar ao Carrinho"
• IDs correspondentes: Se os IDs do XML batem com os eventos
• Parâmetros obrigatórios: content_ids, value, currency

Como funciona:

1. Carrega a página do produto em um navegador real
2. Intercepta requisições de rede do Facebook Pixel
3. Simula clique no botão "Adicionar ao Carrinho"
4. Verifica se eventos foram disparados corretamente
5. Compara IDs do feed XML com IDs dos eventos

📊 Exemplos de Relatórios

Relatório XML

=== RELATÓRIO DE VALIDAÇÃO ===
Fonte: meu-feed.xml
Total de itens: 1000
Itens válidos: 950
Itens com erros: 30
Itens com avisos: 20

DETALHES POR PRODUTO:
──────────────────────────────────────
Produto ID: ABC123 (índice: 5)
ERROS:
  ❌ Campo obrigatório ausente: Brand
AVISOS:
  ⚠️ Excede 65 caracteres: Title (78 caracteres)

Relatório de Pixel

=== RELATÓRIO DE VALIDAÇÃO DO FEED ===
Produtos validados: 10
Taxa de sucesso: 80.0%

EVENTOS:
ViewContent funcionando: 8 (80.0%)
AddToCart funcionando: 6 (60.0%)

CORRESPONDÊNCIA DE IDs:
Catálogo → Página: 9 (90.0%)
Catálogo → ViewContent: 7 (70.0%)
Catálogo → AddToCart: 5 (50.0%)

RECOMENDAÇÕES:
1. [HIGH] 2 produtos não disparam ViewContent
2. [MEDIUM] 4 produtos não disparam AddToCart

🛠️ Solução de Problemas

Erro: "Navigation timeout"

# Aumente o timeout
node validator.js pixel feed.xml --timeout 60000

Erro: "No such file or directory"

# Verifique se o arquivo existe
ls -la meu-feed.xml

# Use caminho absoluto
node validator.js xml /caminho/completo/para/feed.xml

Site bloqueia automação

# Use modo headless para ser mais discreto
node validator.js pixel feed.xml --headless

# Reduza a concorrência
node validator.js pixel feed.xml --concurrent 1

Validação muito lenta

# Use limite menor
node validator.js pixel feed.xml --limit 20

# Pule erros para acelerar
node validator.js pixel feed.xml --skip-errors

🎯 Casos de Uso

1. Validação Rápida Antes do Upload

# Verificar estrutura básica
node validator.js xml meu-feed.xml --errors-only

2. Auditoria Completa do E-commerce

# Validação completa para auditoria
node validator.js both feed.xml --limit 100 --verbose

3. Monitoramento de Produção

# Validar amostra de produtos diariamente
node validator.js pixel feed.xml --limit 50 --headless --format json > relatorio.json

4. Debugging de Pixel

# Validar pixel com navegador visível
node validator.js pixel feed.xml --limit 3

5. CI/CD Pipeline

# Validação automática em pipeline
node validator.js xml feed.xml --format json --no-colors

📁 Estrutura do Projeto

facebook_catalog_validator/
├── validator.js              # CLI principal
├── package.json              # Dependências
├── src/
│   ├── xml/                  # Validação XML
│   │   ├── feedLoader.js     # Carregamento de feeds
│   │   ├── xmlParser.js      # Parser XML
│   │   ├── validator.js      # Regras de validação
│   │   └── reporter.js       # Geração de relatórios
│   └── pixel/                # Validação de Pixel
│       ├── validation/       # Lógica de validação
│       ├── capture/          # Captura de eventos
│       └── detection/        # Detecção de elementos
└── tests/                    # Testes e feeds de exemplo

👨‍💻 Autor

Lucian Fialho - Métricas Boss

Desenvolvido para auxiliar e-commerces na validação de feeds do Facebook Catalog e eventos de Pixel.

🤝 Contribuindo

1. Fork o projeto
2. Crie uma branch (git checkout -b feature/nova-funcionalidade)
3. Commit suas mudanças (git commit -m 'feat: adiciona nova funcionalidade')
4. Push para a branch (git push origin feature/nova-funcionalidade)
5. Abra um Pull Request

📄 Licença

ISC License

🆘 Suporte

Para problemas ou dúvidas:

1. Verifique a seção de Solução de Problemas
2. Execute com --verbose para mais detalhes
3. Abra uma issue no repositório

Tip: Para feeds grandes (>1000 produtos), sempre use --limit nas primeiras validações para testar a configuração! 🚀