# CDP Edge — Início rápido

> Do zero ao tracking server-side funcionando na sua conta Cloudflare.

## O que você precisa

| Item | Para quê |
|---|---|
| Node.js 18 ou superior | Rodar o instalador |
| Conta Cloudflare (gratuita serve para testar) | Hospeda o Worker, o banco D1 e o KV |
| Domínio do site no Cloudflare | Tracking no mesmo domínio (first-party) — opcional para testes via `workers.dev` |
| Pixel ID + Access Token da Meta | Conversions API (opcional: GA4 e TikTok) |

> Plano **Workers Paid** ($5/mês) habilita o rate limiting na borda. Sem ele o instalador remove esse recurso automaticamente.

## 1. Instalar

No PowerShell ou terminal, dentro da pasta do projeto:

```bash
npx cdp-edge install . --name "Nome do Projeto"
```

O instalador:

1. copia o CDP Edge para `cdp-edge/` (sem credenciais locais);
2. cria `.claude/commands/cdp.md` (comando `/cdp` no Claude Code) e `CLAUDE.md`;
3. **pede os acessos** e configura a Cloudflare (passo 2).

Opções: `--no-setup` (só copia os arquivos), `--force` (sobrescreve, com backup `.bak`), `--cursor` (cria `.cursorrules`).

## 2. Informar os acessos

O instalador pergunta, nesta ordem:

| Pergunta | Onde encontrar |
|---|---|
| Login na Cloudflare | Abre o navegador (`wrangler login`). Alternativa: variável `CLOUDFLARE_API_TOKEN` |
| Domínio e zona | O domínio do seu site e o domínio raiz no Cloudflare |
| Meta Pixel ID e Access Token | Events Manager → Fontes de dados → seu Pixel → Configurações |
| GA4 Measurement ID e API Secret | GA4 → Admin → Fluxos de dados → Segredos da API do Measurement Protocol |
| TikTok Pixel ID e Access Token | TikTok Events Manager → Web Events |
| Checkout (Hotmart, Kiwify, Ticto) | O instalador gera as chaves de webhook |
| WhatsApp / CallMeBot | Opcional |

Tokens e senhas vão **direto para a Cloudflare** (`wrangler secret put` via stdin) e não são gravados em arquivos. As chaves geradas (`ADMIN_API_TOKEN` e webhooks) aparecem **uma única vez** no final — guarde-as.

Depois disso ele cria D1, KV, filas e R2, aplica os schemas, publica o Worker e grava os secrets. Se algo falhar, rode `npx cdp-edge onboard` de novo: cada etapa é idempotente.

## 3. Colocar o SDK nas páginas

```html
<script type="module">
  import { init } from '/js/cdpTrack.js';
  await init();
</script>
```

Copie `cdp-edge/extracted-skill/tracking-events-generator/cdpTrack.js` (e `micro-events.js`) para a pasta pública do site. Veja [sdk-reference.md](./sdk-reference.md) e [events-reference.md](./events-reference.md).

## 4. Configurar os webhooks de compra

No painel da plataforma de checkout, use:

| Plataforma | URL | Chave |
|---|---|---|
| Hotmart | `https://SEU_DOMINIO/webhook/hotmart` | `WEBHOOK_SECRET_HOTMART` |
| Kiwify | `https://SEU_DOMINIO/webhook/kiwify` | `WEBHOOK_SECRET_KIWIFY` |
| Ticto | `https://SEU_DOMINIO/webhook/ticto` | `WEBHOOK_SECRET_TICTO` (HMAC) |

Sem a chave configurada o webhook responde `503`; com assinatura inválida, `401` (fail-closed).

## 5. Validar

```bash
npx cdp-edge validate https://SEU_DOMINIO --admin-token "<ADMIN_API_TOKEN>"
```

Também:

- `https://SEU_DOMINIO/health` deve responder `{"status":"ok"}`;
- no Meta Events Manager, use o *Test Event Code* para ver os eventos chegando.

## 6. Privacidade e compras (recomendado)

- Ligue o banner de cookies do site ao `cdpTrack.updateConsent({ ads, analytics })`. A recusa é respeitada no servidor.
- Com banner integrado, ative o modo estrito: `wrangler secret put REQUIRE_CONSENT` (valor `1`).
- Defina o prazo de retenção combinado com o cliente: `wrangler secret put DATA_RETENTION_DAYS` (ex.: `365`).
- Com webhook de checkout configurado, o `Purchase` do navegador é bloqueado automaticamente (`BROWSER_PURCHASE=auto`). Checkout próprio sem webhook: `BROWSER_PURCHASE=on`.

Detalhes: [privacidade-lgpd.md](./privacidade-lgpd.md).

## 7. Usar o assistente (opcional)

Abra a pasta no Claude Code e digite `/cdp`. O Master Orchestrator lê suas páginas, identifica formulários e botões e gera o plano de eventos.

## Atualizar uma instalação existente

Cuidado: `wrangler deploy` **substitui as variáveis** (`[vars]`) pelas do `wrangler.toml`. Valores configurados só no painel (pixels, domínio) seriam apagados.

1. Copie `server-edge-tracker/.client.env.example` para `.client.env` (arquivo ignorado pelo git) e preencha `DATABASE_ID`, `KV_ID` (`wrangler d1 list` / `wrangler kv namespace list`), `SITE_DOMAIN` e os pixels com os valores **atuais** do Worker.
2. Confira: `node deploy-client.cjs --validate-only`.
3. Aplique migrações novas do D1 (todas idempotentes) — ex.: `server-edge-tracker/migrate-v8.sql` (v2.13.0) e `meta-dashboard-full/migrate-security.sql`.
4. Publique: `node deploy-client.cjs`.
5. Verifique `/health`, `/track` e os webhooks. Para voltar: `wrangler rollback <version-id>`.

## Problemas comuns

| Sintoma | Causa provável |
|---|---|
| `503 Webhook secret not configured` | Falta o `WEBHOOK_SECRET_*` da plataforma |
| `401` nas rotas `/api/*` | `Authorization: Bearer <ADMIN_API_TOKEN>` ausente ou errado |
| `503 ADMIN_API_TOKEN não configurado` | Rode `wrangler secret put ADMIN_API_TOKEN` |
| Erro `10000` no wrangler | O token em `CLOUDFLARE_API_TOKEN` não tem permissão; use `wrangler login` |
| Meta responde erro `190` | Token da Meta inválido/expirado: envie um novo com `POST /admin/meta-token` ([guia](./meta-token.md)) |
| Eventos TikTok não saem | `TIKTOK_PIXEL_ID` vazio |
| CORS bloqueando o site | `SITE_DOMAIN` diferente do domínio real da página |