# CDP Edge — Events Reference
> Catálogo completo de todos os eventos, payloads e mapeamento por plataforma.

---

## Como enviar um evento

### Via SDK browser (cdpTrack.js)
```javascript
// Genérico
window.cdpTrack.track('EventName', { param1: 'valor', param2: 'valor' });

// Atalhos
window.cdpTrack.trackLead({ email: '...', phone: '...' });
window.cdpTrack.trackPurchase({ value: 97, currency: 'BRL', order_id: '...' });
window.cdpTrack.trackViewContent({ content_name: '...', value: 97 });
window.cdpTrack.trackAddToCart({ content_id: '...', value: 97 });
```

### Via Worker direto (server-to-server)
```bash
curl -X POST https://track.seudominio.com.br/track \
  -H "Content-Type: application/json" \
  -d '{ "event": "Lead", "email": "fulano@exemplo.com", "phone": "11999998888" }'
```

---

## Eventos Principais

### PageView
Disparado automaticamente pelo SDK ao carregar qualquer página.

```json
{
  "event": "PageView",
  "url": "https://seudominio.com.br/pagina",
  "title": "Título da Página"
}
```

| Plataforma | Nome do evento |
|---|---|
| Meta CAPI | `PageView` |
| GA4 | `page_view` |
| TikTok | `PageView` |

---

### Lead
Captura de lead com dados pessoais. O Worker faz SHA256 automaticamente — enviar dados crus.

```json
{
  "event": "Lead",
  "email": "fulano@exemplo.com",
  "phone": "11999998888",
  "firstName": "João",
  "lastName": "Silva",
  "city": "São Paulo",
  "state": "SP",
  "zip": "01310100",
  "country": "BR"
}
```

| Plataforma | Nome do evento |
|---|---|
| Meta CAPI | `Lead` |
| GA4 | `generate_lead` |
| TikTok | `SubmitForm` |
| Pinterest | `lead` |
| Reddit | `Lead` |
| LinkedIn | `LEAD` |

**Campos obrigatórios:** pelo menos um entre `email` ou `phone`.

---

### Purchase
Compra confirmada. Pode vir do browser ou do webhook de gateway.

```json
{
  "event": "Purchase",
  "value": 297.00,
  "currency": "BRL",
  "order_id": "ORD-12345",
  "email": "fulano@exemplo.com",
  "phone": "11999998888",
  "content_name": "Curso XYZ",
  "content_ids": ["SKU-001"]
}
```

| Plataforma | Nome do evento |
|---|---|
| Meta CAPI | `Purchase` |
| GA4 | `purchase` |
| TikTok | `CompletePayment` |
| Pinterest | `checkout` |
| Reddit | `Purchase` |
| LinkedIn | `PURCHASE` |

**Campos obrigatórios:** `value`, `currency`.

---

### InitiateCheckout
Clique no botão de compra ou entrada na página de checkout.

```json
{
  "event": "InitiateCheckout",
  "value": 297.00,
  "currency": "BRL",
  "content_name": "Curso XYZ",
  "content_ids": ["SKU-001"]
}
```

| Plataforma | Nome do evento |
|---|---|
| Meta CAPI | `InitiateCheckout` |
| GA4 | `begin_checkout` |
| TikTok | `InitiateCheckout` |

---

### ViewContent
Visualização de produto, oferta ou conteúdo de valor.

```json
{
  "event": "ViewContent",
  "content_name": "Página de Vendas — Curso XYZ",
  "content_type": "product",
  "value": 297.00,
  "currency": "BRL",
  "content_ids": ["SKU-001"]
}
```

| Plataforma | Nome do evento |
|---|---|
| Meta CAPI | `ViewContent` |
| GA4 | `view_item` |
| TikTok | `ViewContent` |
| Pinterest | `pagevisit` |
| Reddit | `ViewContent` |

---

### AddToCart
Adição ao carrinho (e-commerce ou checkout multi-produto).

```json
{
  "event": "AddToCart",
  "value": 97.00,
  "currency": "BRL",
  "content_name": "Produto XYZ",
  "content_ids": ["SKU-002"],
  "num_items": 1
}
```

| Plataforma | Nome do evento |
|---|---|
| Meta CAPI | `AddToCart` |
| GA4 | `add_to_cart` |
| TikTok | `AddToCart` |
| Pinterest | `addtocart` |
| Reddit | `AddToCart` |

---

### CompleteRegistration
Cadastro completo (criação de conta, inscrição em lista, acesso liberado).

```json
{
  "event": "CompleteRegistration",
  "email": "fulano@exemplo.com",
  "content_name": "Webinar Gratuito XYZ"
}
```

| Plataforma | Nome do evento |
|---|---|
| Meta CAPI | `CompleteRegistration` |
| GA4 | `sign_up` |
| TikTok | `CompleteRegistration` |
| LinkedIn | `REGISTRATION` |
| Spotify | `SIGN_UP` |

---

### Contact
Contato via WhatsApp (CTWA — Click to WhatsApp). Disparado automaticamente pelo webhook.

```json
{
  "event": "Contact",
  "phone": "5511999998888",
  "ctwa_clid": "ARAkLgFgg...",
  "action_source": "chat"
}
```

| Plataforma | Nome do evento |
|---|---|
| Meta CAPI | `Contact` (action_source: "chat") |

**Nota:** Este evento é gerado automaticamente pelo `processWhatsAppWebhook()` — não precisa ser disparado manualmente.

---

## Eventos de Micro-Engajamento

Gerados automaticamente pelo `micro-events.js`. Salvos no D1 (`behavioral_events`). Contribuem para o engagement score mas **não são enviados às plataformas de anúncio** individualmente.

### Scroll
```json
{
  "event": "Scroll",
  "scroll_depth": 75,
  "scroll_percent": 78,
  "signal_strength": 3.0,
  "time_on_page": 45
}
```

### TimeOnPage
```json
{
  "event": "TimeOnPage",
  "time_on_page": 180,
  "intention_level": "comprador",
  "signal_strength": 4.0
}
```
**Níveis:** `curioso` (10s) → `interessado` (60s) → `comprador` (180s)

### VideoPlay / VideoProgress / VideoComplete
```json
{
  "event": "VideoProgress",
  "video_id": "vsl-principal",
  "video_platform": "youtube",
  "progress_percent": 75,
  "progress_second": 423,
  "engagement_score": 5.0,
  "video_summary": {
    "totalVideos": 1,
    "startedCount": 1,
    "completedCount": 0,
    "maxProgress": 75
  }
}
```
**Plataformas suportadas:** `html5`, `youtube`, `vimeo`

### VideoDropout
Registra o segundo exato em que o usuário parou de assistir.
```json
{
  "event": "VideoDropout",
  "video_id": "vsl-principal",
  "dropout_percent": 62,
  "dropout_second": 743,
  "engagement_score": 2.5
}
```
**Disparado em:** pause sem retomada + `beforeunload` da página.

### Click
```json
{
  "event": "Click",
  "click_category": "cta",
  "position": { "x": 640, "y": 980, "relativeX": 50, "relativeY": 72 },
  "time_on_page": 120
}
```
**Categorias:** `button`, `link`, `input`, `cta`, `price`, `whatsapp`, `email`, `phone`, `generic`

### CTAHover
```json
{
  "event": "CTAHover",
  "cta_selector": "a[href*='checkout']",
  "hover_time_seconds": 4,
  "engagement_score": 3.0
}
```
Dispara apenas após 3 segundos de hover no botão de compra.

---

## Engagement Score

Calculado pelo Worker para cada evento recebido. Salvo em `leads.engagement_score`.

| Dimensão | Range | Descrição |
|---|---|---|
| `time_level` | 0–4.0 | Tempo na página |
| `scroll_score` | 0–4.0 | Profundidade de scroll |
| `click_score` | 0–2.5 | Cliques em CTAs |
| `video_score` | 0–5.0 | Progresso de vídeo |
| `hover_score` | 0–3.0 | Hover no botão de compra |
| **totalScore** | **0–5.0** | Média ponderada |

**Intention levels baseados no score:**

| Score | Label | Ação recomendada |
|---|---|---|
| 0.0–1.5 | `curioso` | Retargeting leve |
| 1.5–3.0 | `interessado` | Retargeting com oferta |
| 3.0–5.0 | `comprador` | Lookalike de alta qualidade |

---

## Webhooks de Gateway de Pagamento

Recebidos pelo Worker. Disparam `Purchase` automaticamente.

| Endpoint | Gateway | Autenticação |
|---|---|---|
| `POST /webhook/hotmart` | Hotmart | `HOTMART_HOTTOK` header |
| `POST /webhook/kiwify` | Kiwify | `KIWIFY_SECRET` HMAC |
| `POST /webhook/ticto` | Ticto | `TICTO_SECRET` HMAC-SHA256 |

---

## WhatsApp Webhook

| Endpoint | Método | Descrição |
|---|---|---|
| `/webhook/whatsapp` | `GET` | Verificação do Meta (challenge) |
| `/webhook/whatsapp` | `POST` | Recebe mensagens CTWA |

Configurar no Meta Business Suite → WhatsApp → Configuração → Webhook.

---

## Campos Normalizados Automaticamente

O Worker normaliza antes de fazer SHA256:

| Campo | Normalização |
|---|---|
| `email` | `lowercase` + `trim` |
| `phone` | Somente dígitos + DDI `55` (Brasil) |
| `firstName` / `lastName` | `Title Case` |
| `city` | `lowercase` + remove acentos |
| `state` | `uppercase` (ex: `SP`, `RJ`) |
| `zip` | Somente dígitos |
| `country` | `lowercase` (ex: `br`) |