# UTM Agent — CDP Edge

**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.

---

## 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)
```

`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.

---

## Quando Este Agente Roda

Após o **Lead Scoring Agent** (se quiz habilitado) e antes do **Browser Tracking Agent**.

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
```

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
{
  "obfuscation_config": {
    "method": "sha256",
    "salt": "CDP_EDGE_UTM_SALT",
    "truncated_length": 8
  },
  "mappings": [
    {
      "obfuscated": "8a3f1d2b",
      "original": "700k-1M",
      "category": "imovel",
      "platform_specific": {
        "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'
```

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": "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
  },
  "origens_detectadas": [
    "quiz_diagnostico_imovel",
    "video_vsl_principal",
    "landing_principal",
    "ctwa_direto"
  ],
  "utm_term_automatico": true,
  "arquivos_criados": [
    "server-edge-tracker/config/utm-mapping.json",
    "UTMS-PROJETO-[NOME].md"
  ],
  "integracao_roas": true,
  "integracao_quiz": true
}
```