cdp-edge 1.2.0

package/extracted-skill/tracking-events-generator/models/captura-de-lead.md

@@ -0,0 +1,78 @@
+# Modelo: Captura de Lead (Cloudflare Native)
+
+Este modelo é destinado a páginas de captura de leads (Opt-in), onde o objetivo principal é coletar o e-mail e/ou telefone do usuário antes de redirecioná-lo para a próxima etapa do funil.
+
+---
+
+## 🏗️ ARQUITETURA TÉCNICA (Quantum Tier)
+
+O rastreamento é realizado de forma síncrona com o envio do formulário:
+1. **Página**: Captura os dados do formulário e envia via `cdpTrack.track()`.
+2. **Servidor (Worker)**: Recebe os dados, realiza o hashing SHA-256 e envia para as APIs.
+3. **Database (D1)**: Armazena o lead e vincula aos IDs de rastreamento (`fbp`, `fbc`).
+
+---
+
+## 📘 EVENTOS PRINCIPAIS
+
+| Evento | Gatilho | PII (Dados Pessoais) |
+|---|---|---|
+| **PageView** | Carregamento da página | IP, User-Agent, URL |
+| **Lead** | Clique no botão de enviar | E-mail, Telefone, Nome (crus) |
+
+---
+
+## 🛠️ PASSO 1: CONFIGURAÇÃO DO SITE
+
+### 1.1 SDK de Rastreamento (Header)
+```html
+<script src="/js/cdpTrack.js" async></script>
+<script>
+  window.cdpConfig = {
+    metaId: 'SEU_PIXEL_ID',
+    ttId: 'SEU_TIKTOK_ID'
+  };
+</script>
+```
+
+### 1.2 Captura do Formulário
+Este script deve ser inserido antes da tag `</body>`. Ele garante que o evento seja enviado antes do redirecionamento.
+
+```javascript
+<script>
+document.querySelector('#meu-formulario').addEventListener('submit', async (e) => {
+  e.preventDefault();
+  
+  const leadData = {
+    email: e.target.email.value,
+    phone: e.target.phone.value,
+    first_name: e.target.name.value,
+    event_id: cdpTrack.generateId() // ID único para deduplicação
+  };
+
+  // Envia para o Worker (Cloudflare)
+  await cdpTrack.track('Lead', leadData);
+  
+  // Prossegue com o envio real do formulário
+  e.target.submit();
+});
+</script>
+```
+
+---
+
+## ⚡ PASSO 2: SERVIDOR (CLOUDFLARE WORKER)
+
+O PlayerBuilder Quantum Tier processa o evento via Cloudflare Worker:
+1. **Deduplicação**: Utiliza o `event_id` do browser para 100% de precisão na Meta CAPI.
+2. **Advanced Matching**: Aplica SHA256 em `email`, `phone`, `first_name` e `last_name` (WebCrypto native).
+3. **D1 Store**: Salva o lead e o Identity Graph na tabela `leads`.
+4. **API Dispatch**: Envia assincronamente para Meta CAPI (v22.0) e TikTok Events API (v1.3).
+
+---
+
+## ✅ VALIDAÇÃO TÉCNICA
+
+- **Deduplicação**: Verifique se o `event_id` gerado no site é o mesmo recebido no Gerenciador de Eventos.
+- **Match Quality**: O envio de e-mail e telefone hasheados pelo servidor garante a máxima pontuação de qualidade.
+- **Persistência**: O lead deve aparecer no banco D1 imediatamente após o envio.

package/extracted-skill/tracking-events-generator/models/captura-lead-evento-externo.md

@@ -0,0 +1,99 @@
+# Modelo: Captura com Evento Externo (Cloudflare Native)
+
+Este modelo combina a captura de leads no site com o recebimento de eventos externos (Webhooks) de plataformas de vendas (Ticto, Hotmart, Kiwify, Eduzz, etc.). Os dados são cruzados no banco **D1** para garantir uma atribuição de alta qualidade.
+
+---
+
+## 🏗️ ARQUITETURA TÉCNICA (Quantum Tier)
+
+O fluxo de dados segue o enriquecimento de identidade:
+1. **Site**: Captura o lead e gera o `event_id` inicial, disparando para o Worker.
+2. **Servidor (Worker)**: Salva o lead no D1 vinculando e-mail aos cookies (`fbp`, `fbc`, `ttp`).
+3. **Webhook**: O Worker recebe a venda, busca o lead no D1 e dispara a CAPI com todos os dados recuperados.
+
+---
+
+## 🛠️ PASSO 1: CONFIGURAÇÃO DO SITE
+
+### 1.1 SDK de Rastreamento
+```html
+<script src="/js/cdpTrack.js" async></script>
+<script>
+  window.cdpConfig = {
+    metaId: 'SEU_PIXEL_ID',
+    ttId: 'SEU_TIKTOK_ID'
+  };
+</script>
+```
+
+### 1.2 Captura de Lead
+```javascript
+document.querySelector('#form-lead').addEventListener('submit', async (e) => {
+  e.preventDefault();
+  
+  const leadData = {
+    email: e.target.email.value,
+    phone: e.target.phone.value,
+    first_name: e.target.name.value,
+    event_id: cdpTrack.generateId()
+  };
+
+  await cdpTrack.track('Lead', leadData);
+  
+  e.target.submit();
+});
+```
+
+---
+
+## 🖥️ PASSO 2: RECEBIMENTO DE WEBHOOK
+
+O Worker recebe o Webhook da plataforma de vendas, busca o lead no D1 e dispara as APIs.
+
+### 2.1 Exemplo de Lógica no Worker
+```javascript
+export default {
+  async fetch(request, env, ctx) {
+    if (request.method === 'POST') {
+      const payload = await request.json();
+      const email = payload.email || payload.customer?.email;
+
+      // Busca o lead no banco D1
+      const lead = await env.DB.prepare(
+        "SELECT * FROM leads WHERE email = ?"
+      ).bind(email).first();
+
+      if (lead) {
+        const capiData = {
+          event_name: 'Purchase',
+          event_id: payload.transaction_id,
+          user_data: {
+            em: lead.email,
+            ph: lead.phone,
+            fbp: lead.fbp,
+            fbc: lead.fbc,
+            client_ip_address: lead.ip,
+            client_user_agent: lead.ua
+          },
+          custom_data: {
+            value: payload.price,
+            currency: 'BRL'
+          }
+        };
+
+        ctx.waitUntil(dispatchCAPI(capiData, env));
+      }
+
+      return new Response('OK', { status: 200 });
+    }
+  }
+}
+```
+
+---
+
+## ✅ VALIDAÇÃO TÉCNICA
+
+- **Enriquecimento**: Verifique se a CAPI está enviando os campos `fbp` e `fbc` mesmo em eventos que vêm de Webhook.
+- **Match Quality**: O cruzamento via e-mail no D1 deve garantir uma pontuação máxima de qualidade no Gerenciador de Eventos.
+- **Deduplicação**: O `event_id` da venda deve ser o ID de transação da plataforma.

package/extracted-skill/tracking-events-generator/models/checkout-proprio.md

@@ -0,0 +1,111 @@
+# Modelo: Checkout Próprio (Cloudflare Native)
+
+Este modelo é destinado a checkouts integrados diretamente no seu site (WooCommerce, Shopify, ou checkouts customizados). O rastreamento cobre desde a entrada no checkout até a confirmação de compra na infraestrutura Cloudflare.
+
+---
+
+## 🏗️ ARQUITETURA TÉCNICA (Quantum Tier)
+
+Fluxo de conversão:
+1. **Site**: Captura de passos (`InitiateCheckout`, `AddPaymentInfo`) via Fetch direto.
+2. **Servidor (Worker)**: Processamento e despacho para as APIs.
+3. **D1 Database**: Repositório de pedidos e perfis de compradores.
+
+---
+
+## 📘 IDENTIFICADORES
+
+| Evento | Gatilho | Dados Enviados |
+|---|---|---|
+| `InitiateCheckout` | Entrada na página de checkout | `email`, `phone` (se preenchidos) |
+| `AddPaymentInfo` | Seleção da forma de pagamento | `email`, `payment_type` |
+| `Purchase` | Clique no botão de finalizar | `email`, `value`, `order_id` |
+
+---
+
+## 🛠️ PASSO 1: CONFIGURAÇÃO DO SITE
+
+### 1.1 Script de Tracking de Checkout
+Este script captura dados à medida que o usuário preenche o formulário.
+
+```javascript
+<script>
+(function() {
+  const WORKER_URL = 'https://api.seusite.com/api/tracking';
+  
+  // Atualização de identidade ao sair do campo (Blur Event)
+  const inputs = document.querySelectorAll('input[type="email"], input[type="tel"]');
+  inputs.forEach(input => {
+    input.addEventListener('blur', function() {
+      window.cdpTrack('IdentityUpdate', {
+        email: document.querySelector('[name="email"]')?.value || '',
+        phone: document.querySelector('[name="phone"]')?.value || ''
+      });
+    });
+  });
+
+  // Evento: Entrada no Checkout
+  window.cdpTrack('InitiateCheckout', {
+    num_items: 1,
+    content_name: 'Produto Premium'
+  });
+
+  // Evento: Finalizar Compra
+  const purchaseBtn = document.querySelector('#btn-finalizar');
+  purchaseBtn?.addEventListener('click', function() {
+    window.cdpTrack('Purchase', {
+      value: 197.00,
+      currency: 'BRL',
+      order_id: 'ord_' + Date.now()
+    });
+  });
+})();
+</script>
+```
+
+---
+
+## ⚡ PASSO 2: SERVIDOR (CLOUDFLARE WORKER)
+
+O Worker gerencia o estado da transação e a persistência.
+
+### 2.1 Persistência de Pedido
+Ao receber o evento `Purchase`, o Worker salva na tabela `leads` com o status correspondente.
+
+### 2.2 Despacho para APIs
+- O Worker envia `Purchase` para as APIs (Meta CAPI v22.0, TikTok v1.3).
+- O `InitiateCheckout` prévio no D1 permite automação de recuperação de carrinho.
+
+---
+
+## 📊 PASSO 3: BANCO DE DADOS D1
+
+```sql
+INSERT INTO leads (
+  event_name, event_id, email, value, currency, utm_source, page_url
+) VALUES (?, ?, ?, ?, ?, ?, ?);
+```
+
+---
+
+## ✅ VALIDAÇÃO TÉCNICA
+
+- **Captura Intermediária**: Verifique se o e-mail é enviado ao Worker antes do clique final (evento Blur).
+- **Deduplicação**: O `order_id` deve ser utilizado como `event_id`.
+- **Integridade D1**: O valor da compra e moeda devem ser gravados corretamente no banco.
+
+---
+
+## 🔄 EXEMPLOS DE INTEGRAÇÃO
+
+### Stripe
+```javascript
+stripe.confirmPayment({ ... }).then(result => {
+  if (!result.error) {
+    cdpTrack.track('Purchase', { value: 197.0, order_id: result.paymentIntent.id });
+  }
+});
+```
+
+### Mercado Pago / PagSeguro
+Chamar o disparo de `Purchase` no callback de `status === 'approved'`.