npm - cdp-edge - Versions diffs - 1.2.0 - Mend

cdp-edge 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (128) hide show

package/extracted-skill/tracking-events-generator/INSTALACAO-CDPEDGE.md ADDED Viewed

@@ -0,0 +1,58 @@
+# Instalação: CDP Edge (Quantum Tier)
+O **CDP Edge** é um sistema de tracking digital completo que opera de forma nativa na Cloudflare. Ele analisa os arquivos do seu projeto, identifica formulários e botões automaticamente, e gera todo o código de tracking para Meta, Google, TikTok e mais — incluindo servidor na borda e banco de dados D1, garantindo alta precisão e soberania total de dados.
+---
+## 🚀 PASSO A PASSO DA INSTALAÇÃO
+### 1. Preparação da Conta Cloudflare
+- Acesse [cloudflare.com](https://cloudflare.com).
+- Ative o banco de dados **D1**.
+- Crie um **Worker** para processamento de eventos.
+### 2. Implantação do SDK (Site)
+- Adicione o script `cdpTrack.js` ao `<head>` do seu site.
+- Configure os IDs (Meta, TikTok, GA4) no `cdpConfig.js`.
+### 3. Configuração do Servidor (Worker)
+- Faça o deploy do código gerado pelo **Server Agent**.
+- Conecte o banco D1 ao seu Worker via `wrangler.toml`.
+- Configure as Variáveis de Ambiente (Tokens de API).
+---
+## ⚡ ARQUITETURA TÉCNICA (Quantum Tier SUPREME)
+| Componente | Função | Vantagem |
+|---|---|---|
+| **cdpTrack.js** | SDK do Site | Envio direto via Fetch para o Worker |
+| **Workers** | Processamento | Execução na borda com baixa latência |
+| **D1 Database** | Persistência | Armazenamento seguro de leads e eventos |
+| **CAPI v22.0** | Despacho | Atribuição de alta qualidade via servidor |
+### Plataformas Suportadas (Server-Side)
+| Plataforma | Status | Protocolo |
+|---|---|---|
+| Meta / Facebook Pixel | ✅ | ✅ CAPI v22.0 |
+| Google Analytics 4 | ✅ | ✅ Measurement Protocol |
+| Google Ads | ✅ | ✅ Conversão + User-provided Data |
+| TikTok Pixel | ✅ | ✅ Events API v1.3 |
+| Pinterest Tag | ✅ | — |
+| Bing / Microsoft Ads | ✅ | — |
+### Tipos de página reconhecidos automaticamente
+| Tipo | Quando usa |
+|---|---|
+| Captura de Lead | Formulário com email/nome/telefone |
+| Lead + Evento Externo | Formulário + compra em plataforma externa (Hotmart/Kiwify) |
+| Tráfego Direto | Página de vendas sem formulário → checkout externo |
+| Checkout Próprio | Cartão/Stripe/MercadoPago na página |
+| Página de Obrigado | Thank-you page pós-compra |
+---
+## 🏁 INICIANDO O SETUP
+Para começar, utilize o comando:
+> "/setup"
+O CDP Edge irá analisar seu site e gerar a infraestrutura necessária automaticamente.

package/extracted-skill/tracking-events-generator/INTEGRACAO-COMPLETA.md ADDED Viewed

@@ -0,0 +1,594 @@
+# 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('/api/tracking')
+                           │ (same-domain)
+┌─────────────────────────────────────────────────────────────────┐
+│               CLOUDFLARE WORKER (worker.js)                │
+├─────────────────────────────────────────────────────────────────┤
+│  1. Receiver (POST /api/tracking)                       │
+│  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│
+          │ v22.0  │  │        │  │  v1.3    │
+          └────────┘  └────────┘  └─────────┘
+```
+---
+## 📦 Instalação
+### Passo 1: Adicionar Scripts ao Site
+```html
+<!DOCTYPE html>
+<html lang="pt-BR">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <!-- 1. Configuração -->
+  <script type="module">
+    window.CDPEDGE_CONFIG = {
+      platforms: ['meta', 'google', 'tiktok'],
+      pixelId: 'SEU_PIXEL_ID_META',
+      ga4MeasurementId: 'G-XXXXXXXXXX',
+      tiktokPixelId: 'SEU_PIXEL_ID_TIKTOK',
+      enableAutoCapture: true,
+      enableMicroEvents: true,
+      enableEngagementScoring: true
+    };
+  </script>
+  <!-- 2. SDK Principal -->
+  <script type="module" src="/pb/cdpTrack.js"></script>
+  <!-- 3. Scripts de Suporte (opcional - para debug) -->
+  <script type="module" src="/pb/integration-test.js"></script>
+</head>
+<body>
+  <!-- Seu site aqui -->
+  <!-- 4. Tracking Automático (opcional) -->
+  <script type="module">
+    import { setupAutoFormCapture } from '/pb/cdpTrack.js';
+    // Capturar automaticamente formulários de lead
+    setupAutoFormCapture();
+    // Ou implementar manualmente:
+    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
+      };
+      await cdpTrack.trackLead(userData, e.target);
+      e.target.submit();
+    });
+  </script>
+</body>
+</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 v22.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 v22.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
+<script type="module" src="/pb/cdpTrack.js"></script>
+<form id="lead-form">
+  <input type="email" name="email" placeholder="Seu e-mail" required>
+  <input type="tel" name="phone" placeholder="Seu telefone" required>
+  <input type="text" name="name" placeholder="Seu nome" required>
+  <input type="text" name="city" placeholder="Sua cidade">
+  <input type="text" name="state" placeholder="Seu estado">
+  <input type="text" name="zip" placeholder="Seu CEP">
+  <button type="submit">Enviar</button>
+</form>
+<script type="module">
+  import { setupAutoFormCapture } from '/pb/cdpTrack.js';
+  setupAutoFormCapture();
+</script>
+```
+### 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 (`/api/tracking`)
+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*