# CDP Edge Premium Tracking Intelligence - Integração Completa (Quantum Tier) ## 📋 Índice 1. [Arquitetura Completa](#arquitetura-completa) 2. [Instalação](#instalação) 3. [Configuração do SDK](#configuração-do-sdk) 4. [Configuração do Worker](#configuração-do-worker) 5. [Fluxo End-to-End](#fluxo-end-to-end) 6. [Exemplos de Uso](#exemplos-de-uso) 7. [Validação e Testes](#validação-e-testes) 8. [Deployment](#deployment) 9. [Troubleshooting](#troubleshooting) --- ## 🏗️ Arquitetura Completa ``` ┌─────────────────────────────────────────────────────────────────┐ │ BROWSER SDK (cdpTrack.js) │ ├─────────────────────────────────────────────────────────────────┤ │ 1. cdpTrack.js (SDK Principal) │ │ 2. micro-events.js (Scroll, Time, Video, Click, Hover) │ │ 3. engagement-scoring.js (Score 0-5.0 browser-side) │ │ 4. advanced-matching.js (Normalização de PII) │ │ 5. anti-blocking.js (Retry, Beacon, Ad-block detection) │ │ 6. behavior-engine.js (Rage click, Idle, A/B, VSL) │ └─────────────────────────────────────────────────────────────────┘ │ ▼ fetch('/track') │ (same-domain) ┌─────────────────────────────────────────────────────────────────┐ │ CLOUDFLARE WORKER (worker.js) │ ├─────────────────────────────────────────────────────────────────┤ │ 1. Receiver (POST /track) │ │ 2. Identity Graph Sync (D1) │ │ 3. Advanced Matching (SHA256 PII + Meta AM) │ │ 4. Engagement Scoring Server-Side (0-5.0 final) │ │ 5. Dispatcher (Meta, Google, TikTok) │ │ 6. Retry System (Queue + Escalation) │ └─────────────────────────────────────────────────────────────────┘ │ ┌──────────┼──────────┬──────────┐ ▼ ▼ ▼ ▼ ┌────────┐ ┌────────┐ ┌─────────┐ │ Meta │ │ Google │ │ TikTok │ │ CAPI │ │ GA4 MP │ │ Events API│ │ v25.0 │ │ │ │ v1.3 │ └────────┘ └────────┘ └─────────┘ ``` --- ## 📦 Instalação ### Passo 1: Adicionar Scripts ao Site ```html ``` ### Passo 2: Deploy do Worker ```bash # 1. Criar arquivo tracking.config.js (se não existir) cat > tracking.config.js << 'EOF' export default { pixelId: 'SEU_PIXEL_ID_META', ga4MeasurementId: 'G-XXXXXXXXXX', tiktokPixelId: 'SEU_PIXEL_ID_TIKTOK', platforms: ['meta', 'google', 'tiktok'], enableAutoCapture: true, enableMicroEvents: true, enableEngagementScoring: true }; EOF # 2. Criar schema D1 wrangler d1 execute cdp-edge-db --file=schema.sql # 3. Configurar secrets wrangler secret put META_ACCESS_TOKEN wrangler secret put GA4_API_SECRET wrangler secret put TIKTOK_ACCESS_TOKEN # 4. Deploy wrangler deploy # 5. Testar wrangler tail ``` --- ## ⚙️ Configuração do SDK ### tracking.config.js ```javascript export default { // Plataformas ativas platforms: ['meta', 'google', 'tiktok'], // IDs dos Pixels pixelId: '123456789012345', // Meta Pixel ID ga4MeasurementId: 'G-XXXXXXXXXX', // GA4 Measurement ID tiktokPixelId: 'CAKJXXXXXX', // TikTok Pixel ID // Configurações de funcionalidades enableAutoCapture: true, // Auto-captura de formulários enableMicroEvents: true, // Micro-events (scroll, time, video) enableEngagementScoring: true, // Engagement scoring enableBehaviorEngine: true, // Rage click, idle, A/B testing enableAntiBlocking: true, // Anti-blocking (retry, beacon) // Configurações de checkout pass-through enableCheckoutPassThrough: true, checkoutPlatforms: ['hotmart', 'kiwify', 'eduzz', 'monetizze', 'cartpanda'], // Ambiente environment: 'production', // 'development' | 'production' debugMode: false // Mostra logs detalhados }; ``` --- ## 🌩 Configuração do Worker ### schema.sql (Atualizado com Premium Tracking) ```sql -- TABELA DE EVENTOS CREATE TABLE IF NOT EXISTS events_log ( id INTEGER PRIMARY KEY AUTOINCREMENT, event_id TEXT UNIQUE NOT NULL, event_name TEXT NOT NULL, platform TEXT, session_id TEXT, heat_score INTEGER DEFAULT 0, user_data TEXT, page_url TEXT, utm_source TEXT, utm_medium TEXT, utm_campaign TEXT, status TEXT DEFAULT 'pending', error_msg TEXT, created_at TEXT DEFAULT (datetime('now')) ); -- IDENTITY GRAPH CREATE TABLE IF NOT EXISTS identity_graph ( id INTEGER PRIMARY KEY AUTOINCREMENT, fingerprint TEXT UNIQUE, fbp TEXT, fbc TEXT, ga_client_id TEXT, external_id TEXT, ttclid TEXT, first_utm TEXT, heat_score_avg INTEGER DEFAULT 0, visit_count INTEGER DEFAULT 1, last_seen TEXT DEFAULT (datetime('now')), created_at TEXT DEFAULT (datetime('now')) ); -- BEHAVIORAL EVENTS (Engagement Scoring) CREATE TABLE IF NOT EXISTS behavioral_events ( id INTEGER PRIMARY KEY AUTOINCREMENT, event_id TEXT NOT NULL UNIQUE, user_id TEXT, session_id TEXT, -- Browser-side score (0-5.0) engagement_score REAL DEFAULT 0.0, time_level TEXT, scroll_score REAL DEFAULT 0.0, click_score REAL DEFAULT 0.0, video_score REAL DEFAULT 0.0, hover_score REAL DEFAULT 0.0, intention_level TEXT, -- Server-side final score server_engagement_score REAL DEFAULT 0.0, final_intention_level TEXT, -- Advanced Matching (hashes) email_hash TEXT, phone_hash TEXT, first_name_hash TEXT, last_name_hash TEXT, -- Advanced Matching (não hashados - Meta AM) city TEXT, state TEXT, zip TEXT, country TEXT, dob TEXT, page_url TEXT, utm_source TEXT, utm_medium TEXT, utm_campaign TEXT, click_ids TEXT, created_at TEXT DEFAULT (datetime('now')) ); -- ÍNDICES CREATE INDEX IF NOT EXISTS idx_events_id ON events_log(event_id); CREATE INDEX IF NOT EXISTS idx_behavioral_session ON behavioral_events(session_id); CREATE INDEX IF NOT EXISTS idx_behavioral_user ON behavioral_events(user_id); CREATE INDEX IF NOT EXISTS idx_behavioral_engagement ON behavioral_events(server_engagement_score); ``` --- ## 🔄 Fluxo End-to-End ### 1. Page View (Carregamento) ``` Usuário acessa site ↓ cdpTrack.init() é chamado ↓ Anti-Blocking inicializado (detecção de ad-blocker) ↓ Micro-Events inicializados (scroll, time, video, click, hover) ↓ Engagement Scoring inicializado (score 0-5.0) ↓ Behavior Engine inicializado (A/B testing, rage click, idle) ↓ PageView event enviado para Worker ↓ Worker recebe payload ↓ Sync Identity Graph (D1) ↓ Calculate Server-Side Engagement Score (0-5.0 com histórico) ↓ Dispatch para Meta CAPI v25.0 (com engagement score + advanced matching) ↓ Dispatch para Google GA4 MP (com engagement score) ↓ Dispatch para TikTok Events API v1.3 (com engagement score) ↓ Log no D1 (behavioral_events + events_log) ``` ### 2. Lead Capture (Formulário) ``` Usuário preenche formulário ↓ setupAutoFormCapture() intercepta submit ↓ extractFormPII() captura dados crus (email, phone, name, city, state, zip, dob) ↓ Normaliza dados (lowercase, remove acentos, DDI 55 no telefone) ↓ cdpTrack.trackLead(piiData) enviado para Worker ↓ Worker recebe dados PII CRUS ↓ Normaliza PII no servidor ↓ SHA256 de email, phone, first_name, last_name ↓ Cidade, estado, zip, dob NÃO são hashados (Meta AM) ↓ Calculate Engagement Score (com PII + histórico) ↓ Dispatch para Meta CAPI v25.0: user_data: { em: [sha256_email], ph: [sha256_phone_ddi55], fn: [sha256_first_name], ln: [sha256_last_name], ct: 'sao paulo', // Não hashado st: 'sp', // Não hashado zp: '01310100', // Não hashado db: '19900101' // Não hashado }, custom_data: { engagement_score: 3.5, intention_level: 'comprador', value: 100, currency: 'BRL' } ``` --- ## 📝 Exemplos de Uso ### Exemplo 1: Auto-Captura de Leads (Sem Código Manual) ```html ``` ### Exemplo 2: Manual - Track Lead com PII ```javascript document.querySelector('#lead-form')?.addEventListener('submit', async (e) => { e.preventDefault(); const userData = { email: e.target.email.value, phone: e.target.phone.value, first_name: e.target.name.value, last_name: e.target.lastname.value, city: e.target.city.value, state: e.target.state.value, zip: e.target.zip.value, dob: e.target.dob.value }; // Captura lead com Advanced Matching Maximum await cdpTrack.trackLead(userData, e.target); e.target.submit(); }); ``` ### Exemplo 3: Track Purchase ```javascript document.querySelector('#checkout-form')?.addEventListener('submit', async (e) => { e.preventDefault(); const orderData = { order_id: 'ORDER_12345', value: 297.00, currency: 'BRL', items: [ { item_id: 'PROD_001', quantity: 1, price: 297.00 } ] }; // Captura compra com PII do usuário await cdpTrack.trackPurchase(orderData, e.target); e.target.submit(); }); ``` ### Exemplo 4: Track Event Customizado ```javascript // Track clique em botão CTA document.querySelector('.cta-button')?.addEventListener('click', async () => { await cdpTrack.track('CTA_Click', { button_text: 'Comprar Agora', button_location: 'hero_section' }); }); // Track vídeo assistido document.querySelector('video')?.addEventListener('ended', async () => { await cdpTrack.track('Video_Complete', { video_id: 'intro-vsl', video_platform: 'youtube', video_duration: 180, watch_time: 180 }); }); ``` ### Exemplo 5: Passar Parâmetros para Checkout Externo ```javascript import { passCheckoutParams } from '/pb/cdpTrack.js'; // Hotmart passCheckoutParams({ platforms: ['hotmart'] }); // Todos os checkouts passCheckoutParams({ platforms: ['hotmart', 'kiwify', 'eduzz', 'monetizze'], domains: ['meusite.com/checkout'] }); // Links serão automaticamente atualizados: // hotmart.com/?xcod=user123&sck=source|medium|campaign|content|term // kiwify.com.br/?src=source&utm_medium=medium&utm_campaign=campaign ``` --- ## ✅ Validação e Testes ### Teste 1: Health Check Rápido ```javascript import { runQuickTest } from '/pb/integration-test.js'; const quickResult = await runQuickTest(); console.log('Status:', quickResult.status); // Esperado: { status: 'ready', worker_online: true, all_modules_loaded: true } ``` ### Teste 2: Suite Completa de Integração Adicione `?cdp_test=true` à URL do site: ``` https://meusite.com/?cdp_test=true ``` Isso exibirá um painel de testes com: - ✅ Status dos módulos - ✅ Health check do Worker - ✅ Teste de envio de eventos - ✅ Validação de payload - ✅ Validação de normalização de PII - ✅ Validação de micro-events ### Teste 3: Verificar Worker Logs ```bash wrangler tail ``` Procure por: - ✅ Worker Online - ✅ Evento {nome} enviado com sucesso - ✅ Engagement Score calculado - ✅ Meta CAPI enviado - ✅ GA4 enviado - ✅ TikTok enviado --- ## 🚀 Deployment ### Checklist de Deployment - [ ] 1. Criar conta Cloudflare - [ ] 2. Criar Worker - [ ] 3. Criar banco D1 - [ ] 4. Executar migrations (schema.sql) - [ ] 5. Configurar secrets (META_ACCESS_TOKEN, GA4_API_SECRET, TIKTOK_ACCESS_TOKEN) - [ ] 6. Deploy do Worker (`wrangler deploy`) - [ ] 7. Configurar custom domain - [ ] 8. Configurar DNS (CNAME para Worker) - [ ] 9. Adicionar scripts ao site - [ ] 10. Testar integração end-to-end - [ ] 11. Validar eventos no Meta Events Manager - [ ] 12. Validar eventos no GA4 DebugView - [ ] 13. Validar eventos no TikTok Events Manager --- ## 🔧 Troubleshooting ### Problema 1: Eventos não chegam ao Meta **Solução:** 1. Verificar se `META_ACCESS_TOKEN` está configurado no Worker 2. Verificar se Pixel ID está correto 3. Verificar logs do Worker (`wrangler tail`) 4. Validar payload no Meta Events Manager ### Problema 2: Advanced Matching não funciona **Solução:** 1. Verificar se dados PII estão sendo capturados 2. Verificar se `extractFormPII()` está funcionando 3. Verificar se Worker está fazendo SHA256 corretamente 4. Validar normalização (minusculas, sem acentos, DDI 55) ### Problema 3: Engagement Score sempre baixo **Solução:** 1. Verificar se micro-events estão capturando dados 2. Verificar se engagement-scoring.js está calculando 3. Verificar se Worker está calculando score server-side 4. Verificar histórico de sessões no D1 (visit_count) ### Problema 4: Ad-blocker bloqueia tracking **Solução:** 1. Verificar se endpoint está no mesmo domínio (`/track`) 2. Verificar se está usando first-party cookies 3. Verificar se `sendWithRetry()` está funcionando 4. Verificar logs de ad-blocker detection --- ## 📊 Performance Esperada ### Impacto no CPL Com Premium Tracking Intelligence implementado: - **Redução esperada no CPL:** 30-50% - **Aumento na taxa de conversão:** 15-25% - **Melhoria na qualidade dos leads:** 40-60% - **Redução em fraudes:** 25-35% ### Fórmula de Sucesso ``` Score = 1 / (Event Match Quality × Signal Strength × Behavioral Intelligence) ``` Onde: - **Event Match Quality**: Advanced Matching (0-8 campos PII) - **Signal Strength**: Engagement Score (0-5.0) - **Behavioral Intelligence**: Micro-Events + Histórico de Sessões --- ## 📞 Suporte Para suporte, consulte: - Documentação completa: `SKILL.md` - Agentes especialistas: `agents/*.md` - Casos de uso: `models/scenarios/*.md` --- *CDP Edge Premium Tracking Intelligence - Integração Completa (Quantum Tier)* *Versão 1.0.0 - Atualizado em 2026-03-27* --- ## Pipeline de Melhoria Contínua Automática (Fase 5) A Fase 5 não adiciona novos eventos de tracking — ela fecha o ciclo de dados para que cada evento coletado melhore automaticamente a qualidade dos próximos. ### Arquitetura do pipeline ``` Browser (cdpTrack.js) │ └─ POST /track │ ├─ [Auto-Enrich] Antes do dispatch Meta CAPI: │ Worker consulta user_profiles por userId │ → recupera email/fbp/fbc ausentes do perfil │ → evento vai para Meta com Advanced Matching completo │ ├─ [Dispatch Meta CAPI] │ → Grava match_quality_log (has_email, has_fbp, etc.) │ ├─ [LTV Prediction] │ → Usa ltv_model_weights (se modelo treinado disponível) │ → Fallback para heurística │ └─ [D1 Writes] → leads, user_profiles, match_quality_log Cron semanal (Worker scheduled) │ ├─ Treina regressão logística → ltv_model_weights (is_active=1) │ → cached em KV para ~0ms no próximo /track │ ├─ Analisa match_quality_log (janela 2h) │ → email_rate < 40% → alerta CallMeBot │ → fbp_rate < 30% → alerta CallMeBot │ → composite < 45% → alerta CallMeBot │ ├─ Verifica experimentos A/B LTV │ → variação bate controle por ≥5pp → auto-winner declarado │ → alerta WhatsApp com prompt ativado │ └─ Export Customer Match → leads high_intent → GET /export/customer-match → CSV para Google Ads (SHA-256 hashed) ``` ### Novas tabelas D1 criadas na Fase 5 | Tabela | Migration | Conteúdo | |---|---|---| | `ltv_model_weights` | `migrate-v7.sql` | Pesos do modelo treinado (trained_at, is_active, accuracy, weights_json) | | `match_quality_log` | `migrate-v7.sql` | Flags por evento: has_email, has_fbp, has_phone, has_fbc, was_email_recovered | **View:** `v_match_quality_24h` — agrega match quality das últimas 24h para consulta rápida. ### Migration completa atualizada (incluindo Fase 5) ```bash wrangler d1 execute cdp-edge-db --file=schema.sql --remote wrangler d1 execute cdp-edge-db --file=migrate-v6.sql --remote wrangler d1 execute cdp-edge-db --file=schema-segmentation.sql --remote wrangler d1 execute cdp-edge-db --file=schema-bidding.sql --remote wrangler d1 execute cdp-edge-db --file=schema-ab-ltv.sql --remote wrangler d1 execute cdp-edge-db --file=schema-fraud.sql --remote wrangler d1 execute cdp-edge-db --file=schema-indexes.sql --remote wrangler d1 execute cdp-edge-db --file=migrate-v7.sql --remote ``` ### Endpoints novos para monitoramento | Endpoint | O que monitora | |---|---| | `GET /api/fraud/stats` | Fraude 24h + qualidade de sinal | | `GET /api/segmentation/list` | Clusters ML ativos com métricas de LTV | | `GET /api/bidding/status` | Bids recomendados por segmento × plataforma | | `GET /api/ltv/ab-test/results` | Acurácia por variação de prompt LTV | | `GET /export/customer-match` | Export CSV de leads high-intent para Google Ads | ### Impacto esperado no funil | Componente | Mecanismo | Resultado | |---|---|---| | Advanced Matching Meta | Auto-Enrich recupera email/fbp de sessões anteriores | EMQ sobe → atribuição mais precisa | | LTV Score | Modelo treinado em dados reais do funil | Bids mais precisos → menor CPA | | Match Quality Alerts | Degradação detectada automaticamente | Fix em horas, não em dias | | A/B Auto-Winner | Melhor prompt LTV ativado automaticamente | LTV scores mais precisos sem revisão manual | | Customer Match | Leads high-intent exportados semanalmente | Audiência Google sempre atualizada |