cdp-edge 2.3.8 → 2.5.1

package/extracted-skill/tracking-events-generator/agents/utm-agent.md

@@ -1,61 +1,222 @@
-# UTM Agent — Agente de Geração de UTMs Obfuscadas
+# UTM Agent — CDP Edge
 
-## Role
-Especialista em gerar estruturas de UTM parametrizadas para segmentação de público, com valores **obfuscados/racheados** para proteção de dados sensíveis na URL.
+**Papel:** Gerador automático de UTMs completas — usa o contexto já coletado pelo CDP Edge para produzir cada string de UTM pronta, por plataforma e por formato de anúncio. O cliente copia e cola.
 
-## When This Agent Runs
-- Após o **Page Analyzer** identificar o tipo de página/produto
-- Antes de gerar os parâmetros de tracking no SDK
-- Quando o usuário precisa configurar campanhas com categorização de valor
+---
 
-## Inputs from Page Analyzer
-```json
-{
-  "page_type": "produto",
-  "product_category": "imovel" | "automotivo" | "curso" | "outros",
-  "url": "https://lançamentosabc.com.br/apartamento-123",
-  "existing_utms": {} // se houver
-}
+## Princípio Fundamental
+
+O CDP Edge já sabe tudo que precisa para gerar as UTMs. Nenhuma informação adicional do cliente é necessária além do que já foi coletado nas fases anteriores:
+
+| O que o CDP Edge já sabe | De onde vem |
+|---|---|
+| Quais plataformas serão usadas | FASE 0-B (seleção de plataformas) |
+| Se tem vídeo no funil | Page Analyzer (detecta VSL, videos, players) |
+| Se tem quiz | Lead Scoring Agent (configurado na FASE 6) |
+| Se tem formulário / landing page | Page Analyzer (detecta forms, CTAs) |
+| Se tem Click-to-WhatsApp | Meta selecionado + CTWA habilitado automaticamente |
+| Nicho e categoria do produto | Page Analyzer |
+| Faixa de valor do produto | Pergunta feita pelo próprio UTM Agent na FASE 2-B |
+
+**Com tudo isso, o UTM Agent gera uma tabela completa de UTMs prontas — o cliente não precisa inventar nenhum parâmetro.**
+
+---
+
+## O Que São as 5 Dimensões
+
+```
+utm_source   → PLATAFORMA    — de qual rede de anúncio veio o lead
+utm_medium   → FORMATO       — qual tipo de anúncio foi usado
+utm_campaign → PRODUTO/FAIXA — qual produto e faixa de valor (obfuscado)
+utm_content  → ORIGEM        — qual criativo/página/funil gerou o lead
+utm_term     → QUALIFICAÇÃO  — classificação do quiz (preenchida pelo Worker)
 ```
 
-## Workflow
+`utm_term` é o único campo que o cliente **nunca** configura nos anúncios — o Worker injeta automaticamente após o Quiz Scoring Engine classificar o lead.
 
-### 1. Identificar necessidade de UTM
-- Se `product_category` existir, perguntar ao usuário sobre categorização de valor
-- Exemplos de perguntas:
-  - Para **imóveis**: "Qual a faixa de preço deste imóvel? Ex: 500k-800k, 800k-1.5M, 1M-3M"
-  - Para **automotivos**: "Qual a faixa de valor? Ex: 50k-100k, 100k-200k, 200k-500k"
-  - Para **cursos**: "Qual o nível/preço? Ex: básico-49, premium-199, pro-999"
+---
 
-### 2. Gerar estrutura de UTM obfuscada
+## Quando Este Agente Roda
 
-Para cada categoria informada pelo usuário, gerar:
+Após o **Lead Scoring Agent** (se quiz habilitado) e antes do **Browser Tracking Agent**.
 
-```json
-{
-  "utm_strategy": {
-    "source": "facebook", // padrão, configurável
-    "medium": "cpc",      // padrão, configurável
-    "campaign": {
-      "pattern": "{product_category}_{obfuscated_range}",
-      "example": "imovel_8a3f1d2b"
-    },
-    "content": {
-      "pattern": "product_{obfuscated_id}",
-      "example": "product_9c4e2a1f"
-    },
-    "faixa_obfuscada": {
-      "original": "700k-1M",
-      "obfuscated": "8a3f1d2b",
-      "hash_method": "sha256",
-      "salt": "CDP_EDGE_UTM_SALT"
-    }
-  }
-}
+Inputs que o agente já possui ao ser chamado:
+- `SELECTED_PLATFORMS` — plataformas selecionadas na FASE 0-B
+- `page_analysis` — saída do Page Analyzer (tem video? tem quiz? tem form? tem CTWA?)
+- `lead_scoring_config` — quiz configurado? quais perguntas? qual nome do quiz?
+- `utm_value_range` — faixa de valor do produto (perguntada na FASE 2-B)
+- `product_category` — nicho detectado pelo Page Analyzer
+
+---
+
+## Processo de Geração
+
+### PASSO 1 — Mapear o que foi implementado no funil
+
+O agente lê os outputs das fases anteriores e monta um inventário de origens:
+
+```
+INVENTÁRIO DE ORIGENS (montado automaticamente):
+
+Plataformas ativas:     [facebook, google, tiktok]
+Formatos por plataforma:
+  facebook → [reels, stories, video, cpc, ctwa]  ← detectado: tem VSL + tem CTWA
+  google   → [cpc]                                ← search only
+  tiktok   → [video]                              ← video in-feed
+Tipos de página:
+  → quiz habilitado    → utm_content inclui quiz_{nome_quiz}
+  → landing com VSL   → utm_content inclui video_{tipo}
+  → formulário direto → utm_content inclui landing_principal
+  → CTWA ativo        → utm_content inclui ctwa_direto
+```
+
+### PASSO 2 — Gerar o valor obfuscado da campanha
+
+Com a faixa de valor informada (ex: "700k-1M"):
+```
+SHA256("700k-1M" + "CDP_EDGE_UTM_SALT") → primeiros 8 chars → "8a3f1d2b"
+utm_campaign = imovel_8a3f1d2b
 ```
 
-### 3. Mapeamento reversível (para o Worker)
-Gerar o arquivo `utm-mapping.json` com:
+Registrar no `utm-mapping.json` para de-obfuscação no Worker.
+
+### PASSO 3 — Gerar a tabela completa de UTMs prontas
+
+Para CADA combinação de plataforma × formato × origem que existe no funil:
+
+---
+
+## Saída — Tabela de UTMs Prontas para o Cliente
+
+O agente entrega uma tabela assim, gerada automaticamente com base no que foi implementado:
+
+```markdown
+# UTMs do Projeto [NOME DO CLIENTE]
+# Geradas pelo CDP Edge — copie e cole em cada campanha
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+## META ADS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+### Campanhas que levam ao QUIZ DE QUALIFICAÇÃO
+Use quando o anúncio leva para a página do quiz antes do formulário.
+
+Reels:
+utm_source=facebook&utm_medium=reels&utm_campaign=imovel_8a3f1d2b&utm_content=quiz_diagnostico_imovel
+
+Stories:
+utm_source=facebook&utm_medium=stories&utm_campaign=imovel_8a3f1d2b&utm_content=quiz_diagnostico_imovel
+
+Vídeo in-feed:
+utm_source=facebook&utm_medium=video&utm_campaign=imovel_8a3f1d2b&utm_content=quiz_diagnostico_imovel
+
+Feed (imagem/carrossel):
+utm_source=facebook&utm_medium=cpc&utm_campaign=imovel_8a3f1d2b&utm_content=quiz_diagnostico_imovel
+
+### Campanhas que levam ao VÍDEO DE VENDAS (VSL)
+Use quando o anúncio leva direto para a landing page com vídeo.
+
+Reels:
+utm_source=facebook&utm_medium=reels&utm_campaign=imovel_8a3f1d2b&utm_content=video_vsl_principal
+
+Stories:
+utm_source=facebook&utm_medium=stories&utm_campaign=imovel_8a3f1d2b&utm_content=video_vsl_principal
+
+Vídeo in-feed:
+utm_source=facebook&utm_medium=video&utm_campaign=imovel_8a3f1d2b&utm_content=video_vsl_principal
+
+### Campanhas Click-to-WhatsApp (CTWA)
+Use quando o anúncio abre diretamente o WhatsApp.
+
+utm_source=whatsapp&utm_medium=ctwa&utm_campaign=imovel_8a3f1d2b&utm_content=ctwa_direto
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+## GOOGLE ADS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+### Search (palavras-chave)
+utm_source=google&utm_medium=cpc&utm_campaign=imovel_8a3f1d2b&utm_content=landing_principal
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+## TIKTOK ADS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+### Vídeo In-Feed (quiz)
+utm_source=tiktok&utm_medium=video&utm_campaign=imovel_8a3f1d2b&utm_content=quiz_diagnostico_imovel
+
+### Vídeo In-Feed (VSL)
+utm_source=tiktok&utm_medium=video&utm_campaign=imovel_8a3f1d2b&utm_content=video_vsl_principal
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+## OBSERVAÇÕES
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+utm_term NÃO é configurado nos anúncios.
+O servidor preenche automaticamente após o quiz:
+  comprador / interessado / curioso / perdido
+
+O valor real da campanha (700k-1M) está protegido.
+Apenas o CDP Edge sabe a correspondência real.
+```
+
+---
+
+## Lógica de utm_content por Tipo de Funil
+
+O agente detecta automaticamente e gera os valores corretos:
+
+| O que o Page Analyzer encontrou | utm_content gerado |
+|---|---|
+| Quiz configurado pelo Lead Scoring Agent | `quiz_{nome_do_quiz}` |
+| Player de vídeo / VSL na landing | `video_vsl_principal` |
+| Vídeo de depoimento identificado | `video_depoimento` |
+| Apenas formulário, sem vídeo, sem quiz | `landing_principal` |
+| CTWA ativo (Meta selecionado) | `ctwa_direto` |
+| Webinar / evento ao vivo detectado | `webinar_{nome}` |
+| Múltiplos formatos | gera uma linha para cada |
+
+**Regra:** se o funil tem quiz E vídeo, gera UTMs separadas para cada origem — porque o ROAS Feedback vai poder comparar qual converte mais.
+
+---
+
+## Lógica de utm_medium por Plataforma
+
+O agente gera formatos com base nas plataformas selecionadas na FASE 0-B. Não pergunta ao cliente — usa o que já foi selecionado:
+
+| Plataforma selecionada | utm_medium gerados automaticamente |
+|---|---|
+| Meta Ads | reels, stories, video, cpc |
+| Meta Ads + CTWA | reels, stories, video, cpc, ctwa |
+| Google Ads | cpc |
+| Google Ads + Display | cpc, display |
+| TikTok Ads | video |
+| YouTube Ads | instream, bumper |
+| Pinterest Ads | cpc |
+| LinkedIn Ads | cpc |
+
+---
+
+## utm_campaign — Geração da Faixa Obfuscada
+
+Esta é a única pergunta que o UTM Agent faz ao cliente (já feita na FASE 2-B durante o master orchestrator):
+
+> "Qual o valor/faixa de preço do produto?" (ex: 700k-1M, 297-997, etc.)
+
+Com a resposta, gera:
+```
+SHA256("700k-1M" + salt) → "8a3f1d2b"
+utm_campaign = imovel_8a3f1d2b
+```
+
+Se o cliente **não** tiver segmentação por valor (produto de preço único), o agente usa:
+```
+utm_campaign = {categoria}_geral
+```
+Ex: `imovel_geral`, `curso_geral`, `servico_geral` — sem obfuscação.
+
+---
+
+## utm-mapping.json — Gerado Automaticamente
 
 ```json
 {
@@ -69,123 +230,93 @@ Gerar o arquivo `utm-mapping.json` com:
       "obfuscated": "8a3f1d2b",
       "original": "700k-1M",
       "category": "imovel",
-      "pixel_audience": "AUDIENCE_MID",
       "platform_specific": {
-        "meta": { "custom_audience_id": "2385xxx" },
-        "tiktok": { "pixel_id": "C1xxx" }
+        "meta":    { "custom_audience_id": "" },
+        "tiktok":  { "pixel_id": "" },
+        "google":  { "conversion_label": "" }
       }
     }
-  ]
+  ],
+  "content_registry": {
+    "quiz_diagnostico_imovel": "Quiz de diagnóstico imobiliário (5 perguntas)",
+    "video_vsl_principal":     "VSL principal da landing page",
+    "video_depoimento":        "Vídeo de depoimento de cliente",
+    "landing_principal":       "Formulário direto na landing page",
+    "ctwa_direto":             "Click-to-WhatsApp direto do anúncio"
+  }
 }
+```
+
+O `content_registry` documenta o significado de cada `utm_content` — o Worker usa isso no ROAS Feedback para exibir nomes legíveis nos relatórios.
+
+---
+
+## utm_term — Injetado pelo Worker (Nunca pelo Cliente)
+
+Depois do Lead Scoring Engine classificar o lead via quiz:
+
+```typescript
+// index.ts — após scoreQuizAnswers()
+trackPayload.utmTerm = quizResult.qualification;
+// → 'comprador' | 'interessado' | 'curioso' | 'perdido'
+```
 
-### 4. Perguntas ao usuário (interativo)
-
-**Para imóveis:**
-> "Identifiquei que esta página é um imóvel. Qual a faixa de preço?
-> - 1) 500k-800k
-> - 2) 800k-1.5M
-> - 3) 1M-3M
-> - 4) 3M-5M
-> - 5) Outro (especifique)"
-
-**Para automotivos:**
-> "Qual a faixa de valor do veículo?
-> - 1) 50k-100k
-> - 2) 100k-200k
-> - 3) 200k-500k
-> - 4) Outro (especifique)"
-
-**Para outros produtos:**
-> "Qual a categoria de valor deste produto?
-> - 1) Entry level (até R$500)
-> - 2) Mid-range (R$500-5k)
-> - 3) Premium (R$5k-50k)
-> - 4) Luxury (acima de R$50k)
-> - 5) Outro (especifique)"
-
-### 5. Gerar código do SDK com UTMs obfuscadas
-
-```javascript
-// cdpTrack.js - snippet gerado
-const utmConfig = {
-  faixa_imovel: '8a3f1d2b', // obfuscado
-  product_id: '9c4e2a1f',  // obfuscado
-  source: 'facebook',
-  medium: 'cpc'
-};
-
-cdpTrack('Lead', {
-  utm: utmConfig,
-  // ... outros campos
-});
-```
-
-## Output Structure
+Salvo no D1 em `user_profiles.utm_term` e incluído nos eventos CAPI como `custom_data.utm_term`. O ROAS Feedback Loop usa para cruzar: *qual campanha gerou mais leads classificados como `comprador` que efetivamente compraram?*
+
+> **Dependência:** `utm_term` só é preenchido se o **Lead Scoring Agent** estiver habilitado (FASE 6) e o evento for `QuizComplete` com `quiz_answers` válidas. Se o funil não tiver quiz, `utm_term` permanece vazio — o ROAS Feedback funciona, mas sem segmentação por qualificação de lead.
+
+---
+
+## Arquivos Gerados
+
+```
+server-edge-tracker/
+  config/
+    utm-mapping.json          ← mapeamento obfuscado + content_registry
+
+# Entregue ao cliente:
+UTMS-PROJETO-[NOME].md        ← tabela completa de UTMs prontas para copiar/colar
+```
+
+---
+
+## O Que Este Agente NÃO FAZ
+
+- ❌ Não pede ao cliente para "montar" UTMs — ele gera e entrega prontas
+- ❌ Não pergunta formatos de anúncio — usa o que foi selecionado na FASE 0-B
+- ❌ Não pergunta se tem quiz — usa o que o Lead Scoring Agent configurou
+- ❌ Não expõe valores reais de produto na URL — sempre obfuscado via SHA256
+- ❌ Não preenche utm_term nos anúncios — isso é exclusivo do Worker
+
+---
+
+## Saída Final (JSON para o Master Orchestrator)
 
 ```json
 {
   "agent": "utm-agent",
-  "version": "1.0.0",
-  "utm_strategy": {
-    "pattern": "{source}/{medium}/{category}_{obfuscated_range}",
-    "base_url": "https://lançamentosabc.com.br"
+  "version": "2.1.0",
+  "utm_campaign_base": "imovel_8a3f1d2b",
+  "value_range_original": "700k-1M",
+  "utms_generated": 11,
+  "por_plataforma": {
+    "facebook": 7,
+    "google": 1,
+    "tiktok": 2,
+    "whatsapp": 1
   },
-  "obfuscated_utms": [
-    {
-      "campaign": "imovel_8a3f1d2b",
-      "content": "product_9c4e2a1f",
-      "original_range": "700k-1M",
-      "obfuscated_hash": "8a3f1d2b"
-    }
+  "origens_detectadas": [
+    "quiz_diagnostico_imovel",
+    "video_vsl_principal",
+    "landing_principal",
+    "ctwa_direto"
   ],
-  "worker_mapping": {
-    "file": "utm-mapping.json",
-    "location": "server-edge-tracker/config/utm-mapping.json"
-  },
-  "sdk_integration": {
-    "file": "cdpTrack.js",
-    "snippet": "// UTM obfuscado\nconst utmObfuscado = '8a3f1d2b';"
-  }
+  "utm_term_automatico": true,
+  "arquivos_criados": [
+    "server-edge-tracker/config/utm-mapping.json",
+    "UTMS-PROJETO-[NOME].md"
+  ],
+  "integracao_roas": true,
+  "integracao_quiz": true
 }
 ```
-
-## Integração com Outros Agentes
-
-1. **Page Analyzer** → informa tipo de produto
-2. **UTM Agent** → pergunta faixa de valor, gera UTMs obfuscadas
-3. **Meta Agent** → recebe UTMs, configura custom audiences
-4. **TikTok Agent** → recebe UTMs, configura pixel events
-5. **Worker** → usa `utm-enricher.ts` para de-obfuscar no runtime
-
-## Edge Cases
-
-- Usuário não sabe a faixa de valor: "Aguardo definição do cliente - use DEFAULT"
-- Produto sem faixa definida: usar `generic_00000000`
-- UTMs existentes: fazer merge sem sobrescrever
-- Múltiplas categorias: perguntar se precisa de segmentação composta
-
-## Example Session
-
-**Page Analyzer:**
-> "Página identificada: imóvel em Vila Mariana, 3 quartos, 2 banheiros"
-
-**UTM Agent:**
-> "Para qual faixa de preço este imóvel deve ser categorizado?"
->
-> Usuário: "800k-1.5M"
->
-> **UTM Agent:**
-> ```json
-> {
->   "utm_faixa": "imovel_b4e2a1c9",
->   "original_range": "800k-1.5M",
->   "hash": "b4e2a1c9"
-> }
-> ```
-
-## Rules
-1. **NUNCA** revelar o valor real na URL pública
-2. **SEMPRE** usar hash obfuscado para valores sensíveis
-3. **Mapeamento reversível** deve estar disponível no Worker (não no SDK)
-4. **Meta CAPI** recebe valor de-obfuscado internamente
-5. UTMs sem valor sensível podem ficar em texto claro

package/extracted-skill/tracking-events-generator/anti-blocking.js

@@ -14,7 +14,7 @@ const isBrowser = typeof window !== 'undefined';
 
 const ANTI_BLOCKING_CONFIG = {
   // Mesmo domínio evita bloqueios de CORS e ad-blockers
-  endpoint: '/api/tracking',
+  endpoint: '/track',
 
   // Retries com exponential backoff
   maxRetries: 3,

package/extracted-skill/tracking-events-generator/cdpTrack.js

@@ -209,13 +209,15 @@ export const generateId = () => {
 // ── Captura de Click IDs das plataformas ──────────────────────
 const _getClickIDs = () => {
   return {
-    fbp: document.cookie.match(/_fbp=([^;]+)/)?.[1],
-    fbc: document.cookie.match(/_fbc=([^;]+)/)?.[1],
-    gclid: _gclid,
-    gbraid: _gbraid,
-    wbraid: _wbraid,
-    ttclid: _ttclid,
-    rclid: _urlParams.get('rclid')
+    fbp:    document.cookie.match(/_fbp=([^;]+)/)?.[1] || undefined,
+    fbc:    document.cookie.match(/_fbc=([^;]+)/)?.[1] || undefined,
+    fbclid: _fbclid || undefined,  // click ID Meta → Worker gera fbc se cookie _fbc ausente
+    gclid:  _gclid  || undefined,
+    gbraid: _gbraid || undefined,
+    wbraid: _wbraid || undefined,
+    ttclid: _ttclid || undefined,
+    ttp:    document.cookie.match(/_ttp=([^;]+)/)?.[1] || undefined,  // TikTok Pixel cookie — EMQ TikTok
+    rclid:  _urlParams.get('rclid') || undefined,
   };
 };
 
@@ -459,7 +461,7 @@ export async function track(eventName, data = {}, options = {}) {
 
   try {
     // Enviar para Worker com retry automático (anti-blocking)
-    const result = await sendWithRetry(payload, '/api/tracking');
+    const result = await sendWithRetry(payload, '/track');
 
     if (result.success) {
       console.log(`✅ Evento ${eventName} enviado com sucesso:`, event_id, result);
@@ -550,16 +552,6 @@ export function setupAutoFormCapture() {
   }, true); // Capture para formulários dinâmicos
 }
 
-/**
- * trackPurchase() — Captura de compra
- *
- * @param {object} orderData - Dados da compra (order_id, value, currency, etc.)
- * @returns {Promise} - Promise com resultado
- */
-export async function trackPurchase(orderData) {
-  return track('Purchase', orderData);
-}
-
 /**
  * trackViewContent() — Captura de visualização de conteúdo
  *

package/extracted-skill/tracking-events-generator/engagement-scoring.js

@@ -21,8 +21,8 @@ const ENGAGEMENT_CONFIG = {
   clickWeights: {
     'generico': 1.0,        // clique sem categoria
     'cta': 2.5,              // clique em CTA
-    'button': 2.0             // clique em botão
-    'link': 1.5              // clique em link
+    'button': 2.0,            // clique em botão
+    'link': 1.5,             // clique em link
     'input': 0.5,            // clique em input
   },
   videoWeights: {

package/extracted-skill/tracking-events-generator/micro-events.js

@@ -27,7 +27,7 @@ const TIME_CONFIG = {
   thresholds: {
     curioso: 10000,      // 10 segundos
     interessado: 60000,  // 60 segundos
-    comprador: 180000    // 180 segundos (3 minutos)
+    comprador: 180000,   // 180 segundos (3 minutos)
     profundao: 60
   },
   signalStrength: {