pixel-builder

v1.4.0

Published

11 days ago

Pixel Builder - Quantum Tracking - Sistema multi-agente para tracking digital Cloudflare Native (Workers + D1)

0High
0Medium
0Low

ricasoares2026

pixel tracking meta caut capi tiktok ga4 cloudflare workers d1 analytics conversion server-side

🚀 Pixel Builder - Quantum Tracking

Padrão Quantum Tracking: 100% Cloudflare Edge. Sem GTM. Sem Stape. Sem cookies de terceiros.

Precisão Máxima: Meta CAPI v22.0+, GA4 MP e TikTok Events API v1.3.
Identity Graph: Persistência de leads e eventos via Cloudflare D1.
Anti-Adblock: Endpoint Same-Domain indetectável.
Human-Behavior Engine: Score de engajamento (0-100) em tempo real.

🏗️ ARQUITETURA QUANTUM (CLOUDFARE NATIVE)

O PixelBuilder não é um "script de rastreio", é uma Content Delivery Network (CDN) com inteligência de dados acoplada.

graph TD
    User((Usuário)) -->|Interação| SDK[pbTrack SDK + Behavior Engine]
    SDK -->|Edge Fetch| Worker[Cloudflare Worker Agent]
    Worker -->|Identity Graph| D1[(D1 SQL Database)]
    Worker -->|Background Job| Queue[Cloudflare Queues]
    Queue -->|Server Dispatch| Meta[Meta CAPI v22.0]
    Queue -->|Server Dispatch| Google[GA4 / Google Ads]
    Queue -->|Server Dispatch| TikTok[TikTok API v1.3]
    D1 -->|Retention Reports| Dash[Dashboard Agent]

🖱 CATÁLOGO DE AGENTES ESPECIALISTAS

O sistema é composto por mais de 30 agentes coordenados pelo Master Orchestrator. Cada um possui uma função técnica específica:

🧠 Núcleo de Inteligência

| Agente | Função | |---|---| | Master Orchestrator | Coordenação central de especialistas e validação Quantum Tier. | | Page Analyzer | Mapeamento automático de CTAs, Forms e Nicho do site. | | Validator Agent | Auditoria de código, segurança e conformidade de APIs. | | Memory Agent | Gestão de contexto e checkpoints técnicos da sessão. | | Intelligence Agent | Monitoramento de atualizações de API (Meta v22.0+, etc). |

🚀 Despachantes de Plataforma

| Agente | Especialidade | |---|---| | Meta Agent | Facebook Pixel + CAPI (EMQ Max). | | Google Agent | GA4 + Google Ads Server-Side. | | TikTok Agent | TikTok Pixel + Events API v1.3. | | Plataformas Ads | Pinterest, Reddit, Bing, LinkedIn, Spotify. | | Browser Agent | Geração do SDK pbTrack.js lightweight. |

🛡️ Módulos Enterprise (Premium)

| Agente | Função | |---|---| | Attribution Agent | Atribuição Multi-Touch de alta fidelidade. | | Security Agent | Rate Limiting, Criptografia AES-256 e Bot Defense. | | Compliance Agent | Gestão de LGPD e GDPR (Consent Mode v2). | | Performance Opt. | Otimização de Caches e Queries D1 SQL. | | CRM Integration | Sincronia D1 ↔ HubSpot/Salesforce via CRM Agent. |

💻 INSTALAÇÃO E USO (POWERShell)

Opção 1: Instalar Globalmente

# 1. Instalar o pacote
npm install -g pixel-builder

# 2. Verificar instalação
pixel-builder --version

# 3. Executar
pixel-builder

Opção 2: Usar via npx (sem instalar)

# Executar direto
npx pixel-builder

📋 COMANDOS DISPONÍVEIS

Comando Único (Wizard Interativo)

# Inicia wizard completo no diretório atual
pixel-builder

# Ou em outro diretório
pixel-builder "C:\caminho\do\projeto"

Comandos Específicos

1. Setup Completo

# Configuração interativa completa
pixel-builder setup

# Setup em diretório específico
pixel-builder setup "C:\meu-projeto"

O que faz:

Pergunta plataformas (Meta, TikTok, GA4, etc.)
Pergunta tipo de produto (lead, checkout, webinar, etc.)
Analisa arquivos do projeto
Gera código de tracking (Browser + Server)
Cria schema D1 SQL
Gera configuração Wrangler

2. Analisar Páginas

# Analisar diretório atual
pixel-builder analyze .

# Analisar projeto específico
pixel-builder analyze "C:\caminho\do\projeto"

O que faz:

Lê todos os arquivos HTML/JS
Detecta CTAs e formulários
Identifica nicho do negócio
Sugere micro-eventos comportamentais

3. Gerar Infraestrutura Server

# Gerar Worker + D1 no diretório atual
pixel-builder server .

# Gerar em diretório específico
pixel-builder server "C:\meu-worker-cloudflare"

Arquivos gerados:

worker.js - Cloudflare Worker completo
schema.sql - Schema D1 para persistência
wrangler.toml - Configuração do Wrangler

4. Validar Tracking Existente

# Validar arquivo específico
pixel-builder validate "C:\meu-projeto\tracking.js"

O que verifica:

Presença de event_id (deduplicação)
Hashing SHA256 para PII (e-mail, telefone)
Detecção de GTM/Stape (avisa para migrar)
Conformidade com APIs mais recentes

5. Guia de Infraestrutura

# Mostra guia passo a passo do zero ao deploy
pixel-builder infra

Cobre:

Criação de conta Cloudflare
Instalação Wrangler CLI
Configuração D1 Database
Setup de secrets (API tokens)
Deploy via wrangler deploy
Configuração de domínio e rotas

🔄 CICLO DE VIDA DO SETUP (/setup)

FASE 0 — Checkpoint: Sincronização de contexto via Memory Agent.
FASE 1 — Análise: Detecção automática de nicho e estrutura da página.
FASE 2 — Mapeamento: Identificação de CTAs, Forms e Gateways de venda.
FASE 3 — Geração: Código paralelo para Browser (pbTrack), Worker e D1 SQL.
FASE 4 — Auditoria: Validação rigorosa e correções automáticas (Validator).
FASE 5 — Deploy: Publicação instantânea via wrangler deploy.

📁 ESTRUTURA DO REPOSITÓRIO

PixelBuilder/
├── README.md                 # Você está aqui. A bíblia do sistema.
├── CLAUDE.md                 # Guia de desenvolvimento e padrões.
├── extracted-skill/          # O motor da IA (Agentes e Knowledge Base).
│   ├── agents/               # Definições técnicas de cada especialista.
│   ├── models/               # Checklists de cenários de negócio.
│   └── knowledge-base.md     # Enciclopédia de APIs e Schemas.
├── server-pixel-tracker/     # O código do Servidor Cloudflare (Worker).
└── .zai/                     # Configurações de inteligência artificial.

📚 EXEMPLOS DE USO POWERShell

Cenário 1: Setup Completo para Landing Page

# 1. Navegar para o projeto
cd "C:\Users\comer\meus-projetos\landing-page-lead"

# 2. Executar setup
pixel-builder setup

# 3. Responder perguntas do wizard
# - Plataformas: [ ] Meta (Facebook/Instagram)
# - Tipo: Lead Capture (Formulário)
# - Server-side: [x] Sim

# 4. Arquivos gerados automaticamente:
#    - pbTrack.js (Browser SDK)
#    - tracking.config.js
#    - worker.js (Cloudflare Worker)
#    - schema.sql (D1 Database)

Cenário 2: Apenas Infraestrutura Cloudflare

# 1. Criar diretório para o Worker
New-Item -Path "C:\meu-worker-cloudflare" -ItemType Directory
cd "C:\meu-worker-cloudflare"

# 2. Gerar infraestrutura
pixel-builder server .

# 3. Deploy com Wrangler
wrangler deploy

# 4. Configurar secrets
wrangler secret put META_ACCESS_TOKEN
wrangler secret put TIKTOK_ACCESS_TOKEN

Cenário 3: Validar Código Existe

# 1. Validar arquivo de tracking
pixel-builder validate "C:\meu-projeto\tracking.js"

# 2. Ver relatório
# Status: PASS
# Score:  85/100
#
# ⚠️  Avisos:
#   └─ Hashing não detectado para PII

Cenário 4: Análise de Projeto

# 1. Analisar projeto completo
pixel-builder analyze "C:\meu-projeto-web"

# 2. Resultado
# 📊 Eventos detectados:
#   leads: 2
#   purchases: 1
#   views: 3
#   custom: 0
#
# 🎯 Nicho identificado: E-commerce (SaaS)

⚡ COMANDOS RÁPIDOS (CLI)

| Comando | Descrição | |---------|-----------| | pixel-builder | Wizard interativo completo | | pixel-builder setup [dir] | Configuração guiada | | pixel-builder analyze <dir> | Análise de páginas | | pixel-builder server <dir> | Gerar infraestrutura Workers + D1 | | pixel-builder validate <file> | Auditoria de código | | pixel-builder infra | Guia Cloudflare | | pixel-builder --help | Ajuda completa | | pixel-builder --version | Versão instalada |

🔧 SOLUÇÃO DE PROBLEMAS

Erro: "pixel-builder não é reconhecido"

# Solução 1: Instalar globalmente
npm install -g pixel-builder

# Solução 2: Usar npx
npx pixel-builder

# Solução 3: Verificar PATH
$env:Path -split ';' | Where-Object { $_ -like '*node*' }

Erro: "Permissão negada ao escrever arquivos"

# Executar PowerShell como Administrador
# 1. Clique com botão direito no PowerShell
# 2. "Executar como administrador"

Erro: "Módulo não encontrado"

# Limpar cache npm
npm cache clean --force

# Reinstalar pacote
npm install -g pixel-builder

🖱️ HUMAN-BEHAVIOR ENGINE (O MOTOR DE INTENÇÃO)

A joia da coroa do PixelBuilder. Capturamos o que o usuário sente e faz, e não apenas onde ele clica.

🌡️ Engagement Scoring Engine (0-100)

Cada ação do usuário soma (ou subtrai) pontos em tempo real:

Scroll (25-90%): +5 a +15 pontos.
VSL Watch (25-100%): +10 a +50 pontos.
Copy Intent: +20 pontos ao copiar cupons ou chaves PIX.
Form Interaction: +10 pontos por campo preenchido.
Rage Click: -10 pontos (sinal de frustração técnica).
Gatilho Hot Lead: Ao atingir 80 pontos, disparar High_Intent_Lead para as plataformas.

🎥 VSL & Video Tracker

Monitoramento nativo de retenção em vídeos YouTube e Vimeo sem necessidade de scripts externos pesados.

📞 SUPORTE

Documentação: Verifique CLAUDE.md para padrões de desenvolvimento
Issues: https://github.com/ricardosoli777/Pixel-Builder-Premium/issues
Releases: https://github.com/ricardosoli777/Pixel-Builder-Premium/releases

PixelBuilder — By Rica Soares

"Dados sem inteligência são apenas ruído. No Quantum Tier, transformamos dados em ROAS."