cdp-edge 1.2.0

package/extracted-skill/tracking-events-generator/knowledge-base.md

@@ -0,0 +1,2894 @@
+# Knowledge Base: CDP Edge (Quantum Tier)
+
+Esta é a fonte técnica oficial para o CDP Edge. Toda implementação deve seguir os padrões de infraestrutura Cloudflare Native (Workers + D1) para garantir máxima atribuição e performance.
+
+---
+
+## 🏗️ 1. ARQUITETURA DE DADOS (CLOUDFLARE NATIVE)
+
+### Camadas do Sistema:
+1.  **Browser (Coleta)**: O SDK `cdpTrack.js` captura eventos de interação, dados de identidade e **micro-comportamentos**.
+2.  **Worker (Processamento)**: O Cloudflare Worker recebe os dados, normaliza, executa o hashing WebCrypto e persiste no banco D1.
+3.  **D1 Database (Persistência)**: Fonte de verdade para o Identity Graph e log de eventos completo (Low-level).
+4.  **APIs (Despacho)**: Envio seletivo e assíncrono para Meta, TikTok e GA4 via `ctx.waitUntil`.
+
+### Estratégia: D1 vs. Plataformas (EMQ Optimization)
+Para manter o Meta Pixel limpo e focado em conversão, aplicamos a regra de **Filtragem de Intent**:
+
+*   **D1 (Tudo)**: Salva 100% dos eventos (cliques x/y, rage clicks, scrolls, heartbeats). É sua ferramenta de auditoria e BI.
+*   **Plataformas (Meta/Google)**: Recebe apenas eventos de **Alta Intenção** (Milestones):
+    *   `Retention_Pulse` (Ex: usuário ativo por +60s).
+    *   `Rage_Click` (Exclusão técnica).
+    *   `VSL_25/50/75/100` (Funis de vídeo).
+    *   Eventos Standard (`Lead`, `Purchase`, `AddToCart`).
+
+---
+
+## 🛠️ 2. PADRÕES TÉCNICOS
+
+### 2.1 Identity Graph (Lead Lock)
+A identidade do usuário é o pilar da atribuição. Ela vincula identificadores anônimos a dados reais (PII) de forma segura.
+- **Campos**: `email_hash`, `phone_hash`, `fbp`, `fbc`, `ttp`, `ttclid`, `ip`, `ua`.
+- **Lógica**: Quando um Webhook de venda chega, o sistema busca no D1 pelo e-mail/telefone para recuperar os cookies de browser originais, garantindo Match Quality máximo.
+
+### 2.2 Deduplicação (Event ID)
+- Todo evento disparado no browser gera um `event_id` único.
+- Esse mesmo ID deve ser enviado na chamada de servidor (CAPI) para que as plataformas ignorem duplicatas.
+
+---
+
+## 🏗️ 3. HUMAN-BEHAVIOR ENGINE (MICRO-EVENTOS)
+
+Protocolos de captura para análise de CRO e saúde técnica.
+
+### 3.1 Rage Click Detector
+Detecta quando o usuário clica repetidamente (>3 cliques em 500ms) em uma área não interativa.
+*   **Ação**: Disparar `rage_click`.
+*   **Uso**: Identificar bugs de UI ou frustração do usuário.
+
+### 3.2 Visibility Heartbeat (Tab Focus)
+Detecta se o usuário mudou de aba (`document.visibilityState === 'hidden'`).
+*   **Ação**: Disparar `tab_visibility_change` com status `hidden` ou `visible`.
+*   **Uso**: Medir retenção real em VSLs onde o áudio continua mas o vídeo não é visto.
+
+### 3.3 Click Heatmap (D1 Only)
+Captura as coordenadas relativas do clique no documento.
+*   **Schema D1**: `x_pos` (float), `y_pos` (float), `element_id` (string), `element_class` (string).
+*   **Uso**: Reconstrução de mapas de calor sem ferramentas externas.
+
+### 3.4 Retention Pulse
+Disparado em intervalos fixos (30s, 60s, 120s) para medir o tempo de atenção ativa.
+*   **Ação**: Disparar `pulse_heartbeat` com o atributo `duration`.
+*   **Uso**: Treinar a IA da Meta com usuários de "Alto Tempo de Atenção".
+
+---
+
+## 🛠️ 4. GERADOR DE TRACKING (SDK UNIFICADO)
+
+**Gerado uma vez. Nunca editar.** Despacha cada evento para todas as plataformas ativas automaticamente.
+
+```js
+// src/tracking/tracking.js
+// ============================================================
+// CDPEDGE — Utilitário multi-plataforma unificado
+// Suporta: Meta · GA4 · Google Ads · TikTok · Pinterest · Bing · Reddit
+// NÃO edite — edite apenas tracking.config.js
+// ============================================================
+import CONFIG from './tracking.config.js';
+
+// ── Guards — segurança em SSR e SDK não carregado ──
+const isBrowser = typeof window !== 'undefined';
+const has = (fn) => isBrowser && typeof window[fn] === 'function';
+
+// ── Captura de parâmetros de URL no carregamento da página ──
+// Cada plataforma injeta seu próprio Click ID na URL quando o usuário clica em um anúncio.
+// Guardamos todos em memória para enviar ao servidor e garantir atribuição correta.
+const _urlParams = isBrowser ? new URLSearchParams(window.location.search) : new URLSearchParams();
+
+// Meta
+const _ctwaClid = _urlParams.get('ctwa_clid') || '';  // Click-to-WhatsApp Click ID
+const _fbclid   = _urlParams.get('fbclid')    || '';  // Meta Ads click ID → gera cookie _fbc
+
+// Google Ads (três variantes por tipo de match/privacy)
+const _gclid   = _urlParams.get('gclid')   || '';    // Google Ads standard click ID → gera cookie _gcl_aw
+const _wbraid  = _urlParams.get('wbraid')  || '';    // Google Ads (iOS, web-to-app, privacy preserving)
+const _gbraid  = _urlParams.get('gbraid')  || '';    // Google Ads (app campaigns, privacy preserving)
+
+// TikTok
+const _ttclid  = _urlParams.get('ttclid')  || '';    // TikTok Ads click ID → complementa cookie _ttp
+
+// UTMs — rastreamento interno de origem de tráfego (independente da atribuição das plataformas)
+const _utms = {
+  utm_source:   _urlParams.get('utm_source')   || '',
+  utm_medium:   _urlParams.get('utm_medium')   || '',
+  utm_campaign: _urlParams.get('utm_campaign') || '',
+  utm_content:  _urlParams.get('utm_content')  || '',
+  utm_term:     _urlParams.get('utm_term')     || '',
+};
+
+// ── User ID persistente (first-party cookie) ──────────────────────────────────
+// Identifica o mesmo usuário entre sessões diferentes, mesmo sem login.
+// Resolve o problema de cookies de terceiros bloqueados por ad-blockers.
+const _getUserId = () => {
+  if (!isBrowser) return '';
+  const KEY = '_cdp_uid';
+  let uid = document.cookie.match(new RegExp(`${KEY}=([^;]+)`))?.[1];
+  if (!uid) {
+    uid = `${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
+    // Cookie first-party de 365 dias — não bloqueado por navegadores
+    document.cookie = `${KEY}=${uid}; max-age=${60*60*24*365}; path=/; SameSite=Lax`;
+  }
+  return uid;
+};
+const _userId = isBrowser ? _getUserId() : '';
+
+/** getUTMs() — retorna os UTMs capturados na chegada do usuário
+ *  Útil para: salvar no CRM, incluir no payload do servidor, rastreamento interno.
+ *  Atribuição própria independente da janela das plataformas (último clique registrado). */
+export const getUTMs = () => ({ ..._utms });
+
+/** getUserId() — retorna o User ID persistente gerado como cookie first-party.
+ *  Identifica o mesmo usuário entre sessões. Não é bloqueado por ad-blockers.
+ *  Identificador de usuário persistente nativo. */
+export const getUserId = () => _userId;
+
+/**
+ * passCheckoutParams(options?) — adiciona UTMs + User ID nos links de checkout externo.
+ *
+ * Problema: quando o usuário clica em um link de Hotmart, Kiwify, Eduzz etc., os UTMs e
+ * o user ID são perdidos — a plataforma não sabe de onde veio o comprador.
+ *
+ * Solução: interceptar os links de checkout e adicionar os parâmetros de rastreamento
+ * na URL antes do clique, para que a plataforma receba e registre a origem.
+ *
+ * Plataformas suportadas e seus parâmetros:
+ *   hotmart  → xcod (user ID) + sck (UTMs pipe-separados: src|med|camp|con|term)
+ *   kiwify   → src (utm_source)
+ *   eduzz    → src (utm_source)
+ *   monetizze → src (utm_source)
+ *   cartpanda → utm_* passthrough direto
+ *   ticto    → utm_* + user_id (_cdp_uid) — capturado em wh.tracking e wh.url_params
+ *   custom   → qualquer domínio via opção `domains`
+ *
+ * Uso:
+ *   passCheckoutParams()                              // detecta automaticamente
+ *   passCheckoutParams({ platforms: ['hotmart'] })   // só Hotmart
+ *   passCheckoutParams({ domains: ['meusite.com/checkout'] }) // domínio customizado
+ */
+export const passCheckoutParams = (options = {}) => {
+  if (!isBrowser) return;
+
+  const {
+    platforms = ['hotmart', 'kiwify', 'eduzz', 'monetizze', 'cartpanda', 'ticto'],
+    domains   = [],   // domínios extras além das plataformas padrão
+    extra     = {},   // parâmetros extras a adicionar em todos os links
+  } = options;
+
+  const utms   = getUTMs();
+  const userId = _userId;
+
+  // Mapa de domínios por plataforma
+  const PLATFORM_DOMAINS = {
+    hotmart:    ['hotmart.com', 'pay.hotmart.com', 'payment.hotmart.com'],
+    kiwify:     ['kiwify.com.br', 'checkout.kiwify.com.br'],
+    eduzz:      ['eduzz.com', 'sun.eduzz.com'],
+    monetizze:  ['monetizze.com.br'],
+    cartpanda:  ['cartpanda.com', 'pay.cartpanda.com'],
+    ticto:      ['ticto.app', 'pay.ticto.app', 'checkout.ticto.app'],
+  };
+
+  // Constrói o `sck` do Hotmart: utm_source|utm_medium|utm_campaign|utm_content|utm_term
+  const buildSck = () =>
+    [utms.utm_source, utms.utm_medium, utms.utm_campaign, utms.utm_content, utms.utm_term]
+      .map(v => v || 'direto')
+      .join('|');
+
+  // Parâmetros por plataforma
+  const getParamsForUrl = (href) => {
+    const params = { ...extra };
+    const url    = href.toLowerCase();
+
+    const isMatch = (list) => list.some(d => url.includes(d));
+
+    if (platforms.includes('hotmart') && isMatch(PLATFORM_DOMAINS.hotmart)) {
+      if (userId)              params.xcod = userId;
+      if (utms.utm_source)     params.sck  = buildSck();
+    } else if (platforms.includes('kiwify') && isMatch(PLATFORM_DOMAINS.kiwify)) {
+      if (utms.utm_source)     params.src  = utms.utm_source;
+      if (utms.utm_medium)     params.utm_medium   = utms.utm_medium;
+      if (utms.utm_campaign)   params.utm_campaign = utms.utm_campaign;
+    } else if (
+      (platforms.includes('eduzz')     && isMatch(PLATFORM_DOMAINS.eduzz))    ||
+      (platforms.includes('monetizze') && isMatch(PLATFORM_DOMAINS.monetizze))
+    ) {
+      if (utms.utm_source)     params.src  = utms.utm_source;
+    } else if (platforms.includes('cartpanda') && isMatch(PLATFORM_DOMAINS.cartpanda)) {
+      // CartPanda recebe utm_* diretamente
+      Object.entries(utms).forEach(([k, v]) => { if (v) params[k] = v; });
+    } else if (platforms.includes('ticto') && isMatch(PLATFORM_DOMAINS.ticto)) {
+      Object.entries(utms).forEach(([k, v]) => { if (v) params[k] = v; });
+      if (userId) params.user_id = userId;
+    } else {
+      // Domínios customizados: repassa utm_* e userId
+      const allDomains = Object.values(PLATFORM_DOMAINS).flat().concat(domains);
+      if (!isMatch(allDomains)) return null;  // não é checkout conhecido
+      Object.entries(utms).forEach(([k, v]) => { if (v) params[k] = v; });
+      if (userId) params.user_id = userId;
+    }
+
+    return Object.keys(params).length ? params : null;
+  };
+
+  const applyParams = (link) => {
+    if (!link.href || link.href.startsWith('javascript')) return;
+    const p = getParamsForUrl(link.href);
+    if (!p) return;
+
+    try {
+      const url    = new URL(link.href);
+      Object.entries(p).forEach(([k, v]) => url.searchParams.set(k, v));
+      link.href = url.toString();
+    } catch { /* URL inválida — ignora */ }
+  };
+
+  // Aplica em todos os links existentes
+  document.querySelectorAll('a[href]').forEach(applyParams);
+
+  // Aplica em links adicionados dinamicamente (ex: botões de checkout lazy loaded)
+  new MutationObserver((mutations) => {
+    mutations.forEach(m => m.addedNodes.forEach(node => {
+      if (node.nodeType !== 1) return;
+      if (node.tagName === 'A') applyParams(node);
+      node.querySelectorAll?.('a[href]').forEach(applyParams);
+    }));
+  }).observe(document.body, { childList: true, subtree: true });
+};
+
+// ── Utilitários de formulário ─────────────────────────────────────────────────
+// Normalizam dados ANTES de enviar às plataformas, alinhados com as variáveis
+
+
+/** normalizePhone(tel) — normaliza telefone para o formato exigido pelas plataformas.
+ *  Remove tudo que não é número. Adiciona DDI Brasil 55 se necessário.
+ *  Meta exige somente dígitos com DDI — ex: '5511999998888'
+ *  Retorna undefined se vazio (evita enviar campo em branco às APIs). */
+export const normalizePhone = (tel = '') => {
+  let t = String(tel).replace(/\D/g, '');
+  if (!t) return undefined;
+  if (!t.startsWith('55') || t.length <= 11) t = '55' + t;
+  return t;
+};
+
+/** splitName(fullName) — divide nome completo em firstName e lastName.
+ *  firstName = todos os nomes menos o último (alinha com campo Meta fn).
+ *  lastName  = somente o último nome (alinha com campo Meta ln).
+ *  Ex: 'João da Silva' → { firstName: 'João da', lastName: 'Silva' }
+ *  Ex: 'João' → { firstName: 'João', lastName: undefined } */
+export const splitName = (fullName = '') => {
+  const parts = String(fullName).trim().split(/\s+/).filter(Boolean);
+  if (!parts.length) return { firstName: undefined, lastName: undefined };
+  if (parts.length === 1) return { firstName: parts[0], lastName: undefined };
+  return { firstName: parts.slice(0, -1).join(' '), lastName: parts.at(-1) };
+};
+
+/** isValidEmail(email) — valida formato de email antes de enviar.
+ *  Evita poluir os dados das plataformas com emails inválidos.
+ *  Validação de Email nativa do CDP Edge.
+ *  Retorna true se válido, false caso contrário. */
+export const isValidEmail = (email = '') =>
+  /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(email).toLowerCase().trim());
+
+/** readField(selector) — lê valor de campo de formulário por id, name ou seletor CSS.
+ *  ex: readField('email') → busca id="email" ou name="email"
+ *  ex: readField('#meu-email') ou readField('input[name="telefone"]') */
+export const readField = (selector = '') => {
+  if (!isBrowser) return '';
+  const el = /^[#.[]/.test(selector)
+    ? document.querySelector(selector)
+    : document.getElementById(selector) || document.querySelector(`[name="${selector}"]`);
+  return el?.value?.trim() || '';
+};
+
+/** normalizeCity(city) — normaliza cidade para o campo `ct` do Meta Advanced Matching.
+ *  Regra Meta: lowercase, sem acentos, sem espaços, sem caracteres especiais.
+ *  ex: 'São Paulo' → 'saopaulo' | 'Belo Horizonte' → 'belohorizonte'
+ *  DEVE ser aplicada ANTES do SHA256 no lado servidor (CAPI). */
+export const normalizeCity = (city = '') => {
+  if (!city) return undefined;
+  return String(city)
+    .normalize('NFD')                    // decompõe acentos (e.g. ã → a + ~)
+    .replace(/[\u0300-\u036f]/g, '')     // remove diacríticos
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, '');         // remove tudo que não é letra ou número
+};
+
+// ── Utilitários de DataLayer / Items ─────────────────────────────────────────
+// Transformam qualquer estrutura de produto para o formato GA4 items (a base de tudo).
+// O GA4 items é a "língua universal" — de lá convertemos para Meta, TikTok, etc.
+
+/**
+ * fixItems(malFormatted) — converte items MAL FORMATADOS para o padrão GA4.
+ * Recebe objeto ou array com qualquer estrutura de campo e mapeia para GA4.
+ * Uso: quando o dataLayer do site/plataforma chega com nomes diferentes dos esperados.
+ *
+ * Parâmetro fieldMap: { ga4Campo: 'nomeCampoOrigem' }
+ * Ex: fixItems(dlItems, { item_id:'id', item_name:'nome', price:'valor', quantity:'qtd' })
+ *
+ * Se não passar fieldMap, tenta detecção automática de campos comuns.
+ */
+export const fixItems = (malFormatted, fieldMap = {}) => {
+  if (!malFormatted) return [];
+  const arr = Array.isArray(malFormatted) ? malFormatted : [malFormatted];
+  const fm = {
+    item_id:   fieldMap.item_id   || 'id',
+    item_name: fieldMap.item_name || 'name' ,
+    price:     fieldMap.price     || 'price',
+    quantity:  fieldMap.quantity  || 'quantity',
+    currency:  fieldMap.currency  || 'currency',
+    item_brand:    fieldMap.item_brand    || 'brand',
+    item_category: fieldMap.item_category || 'category',
+    item_variant:  fieldMap.item_variant  || 'variant',
+  };
+  return arr.map((item, index) => ({
+    item_id:       item[fm.item_id]   || item.sku || item.product_id || '',
+    item_name:     item[fm.item_name] || item.title || item.nome || item.produto || '',
+    price:         parseFloat(String(item[fm.price] || 0).replace(',', '.')),
+    quantity:      parseInt(item[fm.quantity] || 1, 10),
+    index,
+    ...(item[fm.currency]     && { currency:      item[fm.currency] }),
+    ...(item[fm.item_brand]   && { item_brand:    item[fm.item_brand] }),
+    ...(item[fm.item_category]&& { item_category: item[fm.item_category] }),
+    ...(item[fm.item_variant] && { item_variant:  item[fm.item_variant] }),
+    // campos opcionais GA4 — passados direto se presentes
+    ...(item.item_category2   && { item_category2: item.item_category2 }),
+    ...(item.item_category3   && { item_category3: item.item_category3 }),
+    ...(item.affiliation      && { affiliation:    item.affiliation }),
+    ...(item.coupon           && { coupon:         item.coupon }),
+    ...(item.discount         && { discount:       parseFloat(item.discount) }),
+    ...(item.item_list_id     && { item_list_id:   item.item_list_id }),
+    ...(item.item_list_name   && { item_list_name: item.item_list_name }),
+    ...(item.item_variant     && { item_variant:   item.item_variant }),
+    ...(item.location_id      && { location_id:    item.location_id }),
+    ...(item.promotion_id     && { promotion_id:   item.promotion_id }),
+    ...(item.promotion_name   && { promotion_name: item.promotion_name }),
+  }));
+};
+
+/**
+ * buildItems(params) — monta array GA4 a partir de parâmetros SOLTOS.
+ * Uso: quando o produto chega em campos separados (product_id, product_name, etc.)
+ * em vez de um array items.
+ *
+ * Ex: buildItems({ item_id: 'SKU123', item_name: 'Produto', price: 99.9 })
+ *   → [{ item_id: 'SKU123', item_name: 'Produto', price: 99.9, quantity: 1 }]
+ */
+export const buildItems = (params = {}) => [{
+  item_id:       params.item_id || params.product_id || params.id || '',
+  item_name:     params.item_name || params.product_name || params.name || params.nome || '',
+  price:         parseFloat(params.price || params.valor || 0),
+  quantity:      parseInt(params.quantity || params.quantidade || 1, 10),
+  currency:      params.currency || 'BRL',
+  ...(params.item_brand    && { item_brand:    params.item_brand }),
+  ...(params.item_category && { item_category: params.item_category }),
+  ...(params.item_variant  && { item_variant:  params.item_variant }),
+  ...(params.item_category2&& { item_category2:params.item_category2 }),
+  ...(params.discount      && { discount:      parseFloat(params.discount) }),
+  ...(params.coupon        && { coupon:        params.coupon }),
+  ...(params.affiliation   && { affiliation:   params.affiliation }),
+}];
+
+/**
+ * ga4ItemsToMeta(items) — converte GA4 items para formato de content_ids + contents do Meta.
+ * Usado internamente pelo trackPurchase / trackAddToCart quando recebem _ga4Items.
+ * Converte dados para o formato Schema Standard da Meta.
+ */
+export const ga4ItemsToMeta = (items = []) => ({
+  content_ids: items.map(i => String(i.item_id)),
+  contents:    items.map(i => ({
+    id:         String(i.item_id),
+    quantity:   i.quantity   || 1,
+    item_price: i.price      || 0,
+    title:      i.item_name  || undefined,
+    category:   i.item_category || undefined,
+    brand:      i.item_brand || undefined,
+  })),
+  num_items:   items.reduce((s, i) => s + (i.quantity || 1), 0),
+  value:       items.reduce((s, i) => s + (i.price || 0) * (i.quantity || 1), 0),
+});
+
+/**
+ * ga4ItemsToTikTok(items) — converte GA4 items para formato de contents do TikTok Pixel.
+ * Converte dados para o formato Schema Standard do TikTok.
+ */
+export const ga4ItemsToTikTok = (items = []) => ({
+  contents: items.map(i => ({
+    content_id:       String(i.item_id),
+    content_name:     i.item_name     || undefined,
+    content_category: i.item_category || undefined,
+    brand:            i.item_brand    || undefined,
+    price:            i.price         || 0,
+    quantity:         i.quantity      || 1,
+  })),
+  value: items.reduce((s, i) => s + (i.price || 0) * (i.quantity || 1), 0),
+});
+
+// ── Dispatchers por plataforma ──
+const meta     = (type, name, p = {}) => has('fbq')    && window.fbq(type, name, p);
+const tiktok   = (name, p = {})       => has('ttq')    && window.ttq.track(name, p);
+const pinterest = (name, p = {})      => has('pintrk') && window.pintrk('track', name, p);
+const bing     = (name, p = {})       => isBrowser && window.uetq?.push({ ea: name, ...p });
+const reddit   = (name, p = {})       => has('rdt')    && window.rdt('track', name, p);
+const gtag     = (...a)               => has('gtag') && window.gtag(...a);
+
+// ── Verificação de credencial ──
+const active = (key) => !!CONFIG[key];
+
+// ── Dispatcher GA4 ──
+const ga4Event = (name, params = {}) => gtag('event', name, params);
+const ga4Ecommerce = (name, data) => gtag('event', name, { ecommerce: data });
+
+// ── Conversão Google Ads (com Enhanced Conversions / Conversões Otimizadas) ──
+const gadsConversion = (label, value = 0, currency = 'BRL', txId = '', email = '', phone = '') => {
+  if (!label || !active('googleAdsId')) return;
+  gtag('event', 'conversion', {
+    send_to: `${CONFIG.googleAdsId}/${label}`,
+    value, currency,
+    ...(txId && { transaction_id: txId }),
+    // Enhanced Conversions (Conversões Otimizadas) — atribuição a nível de usuário
+    ...(email     && { email_address: email }),
+    ...(phone     && { phone_number:  phone }),
+  });
+};
+
+// ============================================================
+// API PÚBLICA
+// ============================================================
+
+/** PageView — chame em cada página via useEffect(()=>{}, []) */
+export const trackPageView = (title = document.title, url = window.location.pathname) => {
+  if (active('metaPixelId'))    meta('track', 'PageView');
+  if (active('tiktokPixelId'))  tiktok('PageView');                // ttq.page() automático
+  if (active('pinterestTagId')) pinterest('pagevisit');
+  if (active('redditPixelId'))  reddit('PageVisit');
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'pageLoad' }); // Bing
+  ga4Event('page_view', { page_title: title, page_location: url });
+};
+
+/** ViewContent — ao carregar a página do produto/imóvel/serviço (NO useEffect, não no scroll) */
+export const trackViewContent = (params = {}) => {
+  const { _ga4Items = [], _tiktok = {}, ...metaParams } = params;
+
+  if (active('metaPixelId'))    meta('track', 'ViewContent', metaParams);
+  if (active('tiktokPixelId'))  tiktok('ViewContent', {
+    content_id: (_tiktok.content_id || metaParams.content_ids?.[0] || ''),
+    content_name: metaParams.content_name || '',
+    content_type: metaParams.content_type || 'product',
+    value: metaParams.value || 0,
+    currency: metaParams.currency || 'BRL',
+    ..._tiktok
+  });
+  if (active('pinterestTagId')) pinterest('viewcategory', {
+    product_id: metaParams.content_ids?.[0] || '',
+    product_name: metaParams.content_name || '',
+    value: metaParams.value || 0,
+    currency: metaParams.currency || 'BRL',
+  });
+  if (active('redditPixelId'))  reddit('ViewContent', { value: metaParams.value, currency: metaParams.currency });
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'view_content' });
+
+  ga4Ecommerce('view_item', {
+    currency: metaParams.currency || 'BRL',
+    value: metaParams.value || 0,
+    items: _ga4Items
+  });
+};
+
+// ── Geolocalização nativa (cidade do lead via OpenStreetMap — gratuito) ──
+const getCidade = () => new Promise((resolve) => {
+  if (!isBrowser || !navigator.geolocation) return resolve(null);
+  navigator.geolocation.getCurrentPosition(
+    async ({ coords: { latitude, longitude } }) => {
+      try {
+        const r = await fetch(
+          `https://nominatim.openstreetmap.org/reverse?lat=${latitude}&lon=${longitude}&format=json`,
+          { headers: { 'Accept-Language': 'pt-BR' } }
+        );
+        const d = await r.json();
+        resolve(d.address?.city || d.address?.town || d.address?.municipality || null);
+      } catch { resolve(null); }
+    },
+    () => resolve(null),          // usuário negou permissão → ignora silenciosamente
+    { timeout: 5000 }
+  );
+});
+
+/** Lead — envio de formulário (CONVERSÃO PRINCIPAL) — captura cidade automaticamente */
+export const trackLead = async (params = {}) => {
+  const eventId = genId();                                   // ID único — deduplicação browser ↔ servidor
+  const cidade  = await getCidade();                         // tenta capturar cidade
+  const base    = { value: 0, currency: 'BRL', ...params, ...(cidade && { city: cidade }) };
+
+  // Meta: eventID no 3º argumento → deduplicação com CAPI
+  if (active('metaPixelId'))    meta('track', 'Lead', base, { eventID: eventId });
+  if (active('tiktokPixelId')) {
+    // ttq.identify(): Advanced Matching — vincula eventos ao usuário (cross-session)
+    // Chamar ANTES do track para que o evento já carregue o match key
+    if ((base.email || base.phone) && has('ttq')) {
+      window.ttq.identify({
+        email:        base.email?.toLowerCase().trim() || '',
+        phone_number: base.phone ? `+${String(base.phone).replace(/\D/g, '')}` : '',
+        external_id:  _userId || '',
+      });
+    }
+    tiktok('Lead', { content_name: base.content_name || '', value: base.value, currency: base.currency });
+  }
+  if (active('pinterestTagId')) pinterest('lead', { lead_type: base.content_category || 'formulario', value: base.value, currency: base.currency });
+  if (active('redditPixelId'))  reddit('Lead', { value: base.value, currency: base.currency });
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'submit_form', ev: base.value || 0, ec: base.currency || 'BRL' });
+
+  // event_id incluído para deduplicação browser ↔ servidor
+  ga4Event('generate_lead', { method: 'formulario', currency: base.currency, value: base.value, event_id: eventId, ...(cidade && { city: cidade }) });
+  gadsConversion(CONFIG.googleAdsConversions?.lead, base.value, base.currency, '', base.email, base.phone);
+};
+
+/** Contact — clique em WhatsApp / telefone — captura cidade e ctwa_clid automaticamente */
+export const trackContact = async (method = 'whatsapp') => {
+  const eventId = genId();
+  const cidade  = await getCidade();
+  const extra   = cidade ? { city: cidade } : {};
+
+  // Meta: passa eventID para deduplicação com CAPI
+  if (active('metaPixelId'))    has('fbq') && window.fbq('track', 'Contact', extra, { eventID: eventId });
+  if (active('tiktokPixelId'))  tiktok('Contact', extra);
+  if (active('pinterestTagId')) pinterest('lead', { lead_type: method });
+  if (active('redditPixelId'))  reddit('Lead', extra);
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'contact', el: method });
+
+  // event_id incluído para deduplicação Meta
+  ga4Event('generate_lead', { method, currency: 'BRL', value: 0, event_id: eventId, ...extra });
+  gadsConversion(CONFIG.googleAdsConversions?.whatsapp);
+
+  // Server-side: envia ctwa_clid se veio de anúncio Click-to-WhatsApp
+  sendServerEvent('Contact', eventId, {
+    city:     cidade || '',
+    method,
+    // ctwaClid é incluído automaticamente via getCookies() dentro de sendServerEvent
+  });
+};
+
+/** Schedule — agendamento */
+export const trackSchedule = () => {
+  if (active('metaPixelId'))    meta('track', 'Schedule');
+  if (active('tiktokPixelId'))  tiktok('Schedule');
+  if (active('pinterestTagId')) pinterest('lead', { lead_type: 'agendamento' });
+  if (active('redditPixelId'))  reddit('Lead');
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'schedule' });
+
+  ga4Event('generate_lead', { method: 'agendamento', currency: 'BRL', value: 0 });
+  gadsConversion(CONFIG.googleAdsConversions?.schedule);
+};
+
+/** InitiateCheckout — clique em "Comprar" */
+export const trackInitiateCheckout = (params = {}) => {
+  const { _ga4Items = [], ...p } = params;
+  const base = { currency: 'BRL', value: 0, ...p };
+
+  if (active('metaPixelId'))    meta('track', 'InitiateCheckout', base);
+  if (active('tiktokPixelId'))  tiktok('InitiateCheckout', { value: base.value, currency: base.currency, content_id: base.content_ids?.[0] });
+  if (active('pinterestTagId')) pinterest('checkout', { value: base.value, currency: base.currency, order_quantity: 1 });
+  if (active('redditPixelId'))  reddit('AddToCart', { value: base.value, currency: base.currency });
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'initiate_checkout', ev: base.value, ec: base.currency });
+
+  ga4Ecommerce('begin_checkout', { currency: base.currency, value: base.value, items: _ga4Items });
+};
+
+/** AddToCart — adicionar ao carrinho */
+export const trackAddToCart = (params = {}) => {
+  const { _ga4Items = [], ...p } = params;
+  const base  = { currency: 'BRL', value: 0, ...p };
+  // Converte GA4 items → formato Meta/TikTok automaticamente (Universal Conversion)
+  const metaP = _ga4Items.length ? { ...base, ...ga4ItemsToMeta(_ga4Items) } : base;
+  const ttkP  = _ga4Items.length ? ga4ItemsToTikTok(_ga4Items) : { value: base.value, currency: base.currency };
+
+  if (active('metaPixelId'))    meta('track', 'AddToCart', metaP);
+  if (active('tiktokPixelId'))  tiktok('AddToCart', { ...ttkP, currency: base.currency, content_id: metaP.content_ids?.[0] });
+  if (active('pinterestTagId')) pinterest('addtocart', { value: metaP.value, currency: base.currency, product_id: metaP.content_ids?.[0] });
+  if (active('redditPixelId'))  reddit('AddToCart', { value: metaP.value, currency: base.currency });
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'add_to_cart', ev: metaP.value, ec: base.currency });
+
+  ga4Ecommerce('add_to_cart', { currency: base.currency, value: metaP.value, items: _ga4Items });
+};
+
+/** Purchase — compra concluída (value + currency obrigatórios) */
+export const trackPurchase = (params = {}) => {
+  const { _ga4Items = [], ...p } = params;
+  if (!p.value || !p.currency) console.warn('[CDP Edge] trackPurchase requer value e currency');
+  const txId  = p.order_id || `T_${Date.now()}`;
+  // Converte GA4 items → formato Meta/TikTok automaticamente (Universal Conversion)
+  const metaP = _ga4Items.length ? { ...p, ...ga4ItemsToMeta(_ga4Items) } : p;
+  const ttkP  = _ga4Items.length ? ga4ItemsToTikTok(_ga4Items) : { value: p.value };
+
+  if (active('metaPixelId'))    meta('track', 'Purchase', { currency: p.currency || 'BRL', ...metaP });
+  if (active('tiktokPixelId')) {
+    // identify() antes do track: Advanced Matching vincula compra ao usuário
+    if ((p.email || p.phone) && has('ttq')) {
+      window.ttq.identify({
+        email:        p.email?.toLowerCase().trim() || '',
+        phone_number: p.phone ? `+${String(p.phone).replace(/\D/g, '')}` : '',
+        external_id:  _userId || '',
+      });
+    }
+    tiktok('CompletePayment', { ...ttkP, currency: p.currency || 'BRL', order_id: txId });
+  }
+  if (active('pinterestTagId')) pinterest('checkout', { value: metaP.value, currency: p.currency || 'BRL', order_id: txId, order_quantity: metaP.num_items || 1 });
+  if (active('redditPixelId'))  reddit('Purchase', { value: metaP.value, currency: p.currency || 'BRL' });
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'purchase', ev: p.value, ec: p.currency || 'BRL', gc: txId });
+
+  // event_id = txId incluído para deduplicação Meta
+  ga4Ecommerce('purchase', { transaction_id: txId, event_id: txId, currency: p.currency || 'BRL', value: p.value, items: _ga4Items });
+  gadsConversion(CONFIG.googleAdsConversions?.purchase, p.value, p.currency || 'BRL', txId, p.email, p.phone);
+};
+
+/** CompleteRegistration — cadastro concluído */
+export const trackSignUp = (method = 'formulario') => {
+  if (active('metaPixelId'))    meta('track', 'CompleteRegistration', { status: 'completed' });
+  if (active('tiktokPixelId'))  tiktok('CompleteRegistration');
+  if (active('pinterestTagId')) pinterest('signup', { lead_type: method });
+  if (active('redditPixelId'))  reddit('SignUp');
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'sign_up' });
+
+  ga4Event('sign_up', { method });
+  gadsConversion(CONFIG.googleAdsConversions?.signup);
+};
+
+// ============================================================
+// EVENTOS COMPLETOS — E-COMMERCE E FUNIL AVANÇADO
+// ============================================================
+
+/** Search — busca no site */
+export const trackSearch = (query = '') => {
+  if (active('metaPixelId'))    meta('track', 'Search', { search_string: query });
+  if (active('tiktokPixelId'))  tiktok('Search', { query });
+  if (active('redditPixelId'))  reddit('Search');
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'search', el: query });
+  ga4Event('search', { search_term: query });
+};
+
+/** AddToWishlist — adicionar à lista de desejos / favoritos */
+export const trackAddToWishlist = (params = {}) => {
+  const { _ga4Items = [], ...p } = params;
+  const base = { currency: 'BRL', value: 0, ...p };
+
+  if (active('metaPixelId'))    meta('track', 'AddToWishlist', base);
+  if (active('tiktokPixelId'))  tiktok('AddToWishlist', { content_id: base.content_ids?.[0], value: base.value, currency: base.currency });
+  if (active('redditPixelId'))  reddit('AddToWishlist');
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'add_to_wishlist', ev: base.value, ec: base.currency });
+  ga4Ecommerce('add_to_wishlist', { currency: base.currency, value: base.value, items: _ga4Items });
+};
+
+/** RemoveFromCart — remover item do carrinho */
+export const trackRemoveFromCart = (params = {}) => {
+  const { _ga4Items = [], ...p } = params;
+  const base = { currency: 'BRL', value: 0, ...p };
+
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'remove_from_cart', ev: base.value, ec: base.currency });
+  ga4Ecommerce('remove_from_cart', { currency: base.currency, value: base.value, items: _ga4Items });
+  // Meta e TikTok não têm RemoveFromCart padrão — usar trackCustom se necessário
+};
+
+/** ViewCart — visualizar o carrinho */
+export const trackViewCart = (params = {}) => {
+  const { _ga4Items = [], ...p } = params;
+  const base = { currency: 'BRL', value: 0, ...p };
+
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'view_cart' });
+  ga4Ecommerce('view_cart', { currency: base.currency, value: base.value, items: _ga4Items });
+};
+
+/** ViewItemList — listagem de produtos (categoria, busca, vitrine) */
+export const trackViewItemList = (params = {}) => {
+  // aceita item_list_id/item_list_name (GA4 spec) ou list_id/list_name (compat)
+  const {
+    _ga4Items = [], items = _ga4Items,
+    item_list_id = params.list_id || '',
+    item_list_name = params.list_name || '',
+  } = params;
+
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'view_item_list' });
+  ga4Ecommerce('view_item_list', { item_list_name, item_list_id, items });
+};
+
+/** SelectItem — clicou em produto na lista */
+export const trackSelectItem = (params = {}) => {
+  const {
+    _ga4Items = [], items = _ga4Items,
+    item_list_id = params.list_id || '',
+    item_list_name = params.list_name || '',
+  } = params;
+
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'select_item' });
+  ga4Ecommerce('select_item', { item_list_name, item_list_id, items });
+};
+
+/** AddPaymentInfo — informou dados de pagamento */
+export const trackAddPaymentInfo = (params = {}) => {
+  const { _ga4Items = [], payment_type = '', ...p } = params;
+  const base = { currency: 'BRL', value: 0, ...p };
+
+  if (active('metaPixelId'))    meta('track', 'AddPaymentInfo', base);
+  if (active('tiktokPixelId'))  tiktok('AddPaymentInfo', { value: base.value, currency: base.currency });
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'add_payment_info', ev: base.value, ec: base.currency });
+  ga4Ecommerce('add_payment_info', { currency: base.currency, value: base.value, payment_type, items: _ga4Items });
+};
+
+/** AddShippingInfo — informou dados de entrega */
+export const trackAddShippingInfo = (params = {}) => {
+  const { _ga4Items = [], shipping_tier = '', ...p } = params;
+  const base = { currency: 'BRL', value: 0, ...p };
+
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'add_shipping_info' });
+  ga4Ecommerce('add_shipping_info', { currency: base.currency, value: base.value, shipping_tier, items: _ga4Items });
+};
+
+/** ViewPromotion — visualizou banner/promoção */
+export const trackViewPromotion = (params = {}) => {
+  const { _ga4Items = [], promotion_id = '', promotion_name = '', creative_name = '', creative_slot = '' } = params;
+
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'view_promotion' });
+  ga4Ecommerce('view_promotion', { promotion_id, promotion_name, creative_name, creative_slot, items: _ga4Items });
+};
+
+/** SelectPromotion — clicou em banner/promoção */
+export const trackSelectPromotion = (params = {}) => {
+  const { _ga4Items = [], promotion_id = '', promotion_name = '', creative_name = '', creative_slot = '' } = params;
+
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'select_promotion' });
+  ga4Ecommerce('select_promotion', { promotion_id, promotion_name, creative_name, creative_slot, items: _ga4Items });
+};
+
+/** Subscribe — assinou newsletter ou serviço recorrente */
+export const trackSubscribe = (params = {}) => {
+  const base = { value: 0, currency: 'BRL', predicted_ltv: 0, ...params };
+
+  if (active('metaPixelId'))    meta('track', 'Subscribe', base);
+  if (active('tiktokPixelId'))  tiktok('Subscribe', { value: base.value, currency: base.currency });
+  if (active('redditPixelId'))  reddit('Lead');
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'subscribe', ev: base.value, ec: base.currency });
+  ga4Event('generate_lead', { method: 'subscribe', currency: base.currency, value: base.value });
+  gadsConversion(CONFIG.googleAdsConversions?.signup);
+};
+
+/** StartTrial — iniciou período de teste gratuito
+ *  TikTok: usa evento padrão 'StartTrial' (não 'Subscribe') */
+export const trackStartTrial = (params = {}) => {
+  const base = { value: 0, currency: 'BRL', predicted_ltv: 0, ...params };
+
+  if (active('metaPixelId'))    meta('track', 'StartTrial', base);
+  if (active('tiktokPixelId'))  tiktok('StartTrial', { value: base.value, currency: base.currency });
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'start_trial' });
+  ga4Event('generate_lead', { method: 'trial', currency: base.currency, value: base.value });
+};
+
+/** FindLocation — buscou localização física da empresa */
+export const trackFindLocation = () => {
+  if (active('metaPixelId'))    meta('track', 'FindLocation');
+  if (active('tiktokPixelId'))  tiktok('FindLocation');
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'find_location' });
+  ga4Event('find_location');
+};
+
+/** Donate — fez uma doação */
+export const trackDonate = (params = {}) => {
+  const base = { value: 0, currency: 'BRL', ...params };
+
+  if (active('metaPixelId'))    meta('track', 'Donate', base);
+  if (active('redditPixelId'))  reddit('Purchase', { value: base.value, currency: base.currency });
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'donate', ev: base.value, ec: base.currency });
+  ga4Event('generate_lead', { method: 'donate', currency: base.currency, value: base.value });
+};
+
+/** SubmitApplication — enviou candidatura, inscrição ou formulário longo */
+export const trackSubmitApplication = (params = {}) => {
+  const base = { value: 0, currency: 'BRL', ...params };
+
+  if (active('metaPixelId'))    meta('track', 'SubmitApplication', base);
+  if (active('tiktokPixelId'))  tiktok('SubmitForm', { value: base.value, currency: base.currency });
+  if (active('redditPixelId'))  reddit('Lead');
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'submit_application' });
+  ga4Event('generate_lead', { method: 'application', currency: base.currency, value: base.value });
+  gadsConversion(CONFIG.googleAdsConversions?.lead);
+};
+
+/** Download — download de arquivo (PDF, app, material) */
+export const trackDownload = (params = {}) => {
+  const base = { file_name: '', file_extension: '', link_url: '', ...params };
+
+  if (active('tiktokPixelId'))  tiktok('Download', { content_name: base.file_name });
+  if (isBrowser && window.uetq) window.uetq.push({ ea: 'file_download', el: base.file_name });
+  ga4Event('file_download', { file_name: base.file_name, file_extension: base.file_extension, link_url: base.link_url });
+};
+
+/** CustomizeProduct — personalizou produto (cor, tamanho, gravação, etc.) */
+export const trackCustomizeProduct = (params = {}) => {
+  if (active('metaPixelId'))   meta('track', 'CustomizeProduct', params);
+  if (active('tiktokPixelId')) tiktok('CustomizeProduct', { content_name: params.content_name || '' });
+  ga4Event('customize_product', params);
+};
+
+// ============================================================
+// EVENTO GENÉRICO CUSTOMIZADO
+// ============================================================
+
+/** Evento customizado — qualquer nome de evento não coberto acima */
+export const trackCustom = (metaEventName, ga4EventName, params = {}) => {
+  if (active('metaPixelId'))   window.fbq?.('trackCustom', metaEventName, params);
+  if (active('tiktokPixelId')) window.ttq?.track(metaEventName, params);
+  ga4Event(ga4EventName, params);
+};
+
+/** Scroll depth tracker — utilitário para medir profundidade de scroll */
+export const scrollTracker = (threshold = 50, callback) => {
+  let fired = false;
+  return () => {
+    if (fired) return;
+    const pct = (window.scrollY / (document.body.scrollHeight - window.innerHeight)) * 100;
+    if (pct >= threshold) { fired = true; callback(); }
+  };
+};
+```
+
+---
+
+## PASSO 4 — Eventos por página e tipo de negócio
+
+### Regra de ouro por plataforma (NUNCA violar)
+
+| Plataforma | Regra crítica |
+|---|---|
+| **Meta** | `ViewContent` sempre no load da página — NUNCA em scroll. `Lead`/`Purchase` apenas quando ação é confirmada (onSubmit, não onClick) |
+| **GA4** | Sempre `{ecommerce: null}` antes de qualquer evento de e-commerce |
+| **TikTok** | `CompletePayment` = Purchase. `SubmitForm` = Lead. Nunca usar eventos Meta como nomes |
+| **Google Ads** | Conversão só no evento real de conversão (Lead confirmado, Purchase confirmado). Não usar em PageView |
+| **Geral** | `trackPageView()` em TODA rota via `useEffect(()=>{}, [])`. Em SPA nunca confiar no carregamento automático |
+
+---
+
+### 📄 TIPO 1 — Landing Page / Página de Captura (Infoproduto, Serviço, Imóvel)
+
+**Funil:** Visita → Interesse → Lead (formulário ou WhatsApp)
+
+```jsx
+// Eventos no LOAD (automáticos)
+// ✅ PageView → todas as plataformas
+// ✅ ViewContent → todas as plataformas (sinaliza o que o usuário está vendo)
+
+// Eventos na INTERAÇÃO (nunca automáticos)
+// ✅ Lead → no onSubmit do formulário (NÃO no onClick do botão)
+// ✅ Contact → no clique no botão de WhatsApp/telefone
+// ✅ Schedule → no clique em "Agendar"
+// ✅ trackCustom('FormStart') → no onFocus do primeiro campo (micro-conversão)
+// ❌ NUNCA: ViewContent no scroll, Lead no onClick, PageView duplicado
+
+import { useEffect } from 'react';
+import {
+  trackPageView, trackViewContent, trackLead,
+  trackContact, trackSchedule, trackCustom, scrollTracker,
+  readField, normalizePhone, splitName, isValidEmail, normalizeCity, // utilitários de formulário
+} from '../tracking/tracking';
+
+// ── Dados do conteúdo da página ────────────────────────────
+const CONTEUDO = {
+  content_ids:  ['ID_PRODUTO'],
+  content_type: 'product',        // 'home_listing' para imóveis
+  content_name: 'Nome do Produto / Serviço',
+  value:        0,                // 0 se não tiver preço fixo; preço real se tiver
+  currency:     'BRL',
+  _ga4Items: [{ item_id: 'ID_PRODUTO', item_name: 'Nome do Produto', price: 0, quantity: 1 }],
+};
+
+export function LandingPage() {
+
+  // ── LOAD: PageView + ViewContent (obrigatórios em toda landing page) ──
+  useEffect(() => {
+    trackPageView();
+    trackViewContent(CONTEUDO);
+  }, []);
+
+  // ── SCROLL: micro-conversão de interesse (opcional, não substitui ViewContent) ──
+  useEffect(() => {
+    return scrollTracker([75], (pct) =>
+      trackCustom('ScrollEngagement', { percent_scrolled: pct }));
+  }, []);
+
+  // ── INTERAÇÕES ──────────────────────────────────────────
+  const onWhatsApp = async () => {
+    await trackContact('whatsapp');           // Meta: Contact | GA4: generate_lead | TikTok: Contact
+    window.open('https://wa.me/55SEUNUMERO', '_blank');
+  };
+
+  const onFormFocus = () =>
+    trackCustom('FormStart', { form_name: 'captacao_lead' }); // sinaliza interesse em preencher
+
+  const onSubmit = async (e) => {
+    e.preventDefault();
+
+    // ── Leitura e normalização dos campos ──────────────────────────────
+    // readField() busca por id="X" ou name="X" — adaptar ao HTML real do site
+    const emailRaw = readField('email');        // id="email" ou name="email"
+    const nomeRaw  = readField('nome');         // id="nome" ou name="nome"
+    const telRaw   = readField('telefone');     // id="telefone" ou name="telefone"
+
+    // Validar email antes de disparar
+    if (!isValidEmail(emailRaw)) return;        // ← não dispara se email inválido
+
+    // Separar nome em firstName / lastName (alinha com campos fn/ln do Meta CAPI)
+    const { firstName, lastName } = splitName(nomeRaw);
+
+    // Normalizar telefone para formato Meta: somente dígitos + DDI
+    const phone = normalizePhone(telRaw);       // ex: '5511999998888'
+
+    await trackLead({                           // Meta: Lead | GA4: generate_lead | TikTok: SubmitForm
+      email:        emailRaw,                   // → SHA256 no servidor (Meta Advanced Matching / Google Enhanced Conversions)
+      phone,                                    // → já normalizado; SHA256 no servidor
+      firstName,                                // → SHA256 no servidor (campo fn no Meta CAPI)
+      lastName,                                 // → SHA256 no servidor (campo ln no Meta CAPI)
+      content_name: CONTEUDO.content_name,
+    });
+    // redirecionar ou mostrar mensagem de sucesso
+  };
+
+  const onSchedule = () =>
+    trackSchedule();                            // Meta: Schedule | GA4: generate_lead | TikTok: Schedule
+
+  return (
+    <div>
+      <button onClick={onWhatsApp}>Falar no WhatsApp</button>
+      {/* ── Campos com id E name ── */}
+      <form onSubmit={onSubmit}>
+        <input id="nome"      name="nome"      placeholder="Seu nome completo" required />
+        <input id="email"     name="email"     type="email" placeholder="Seu e-mail" required onFocus={onFormFocus} />
+        <input id="telefone"  name="telefone"  type="tel"   placeholder="Seu telefone" />
+        <button type="submit">Quero saber mais</button>
+      </form>
+      <button onClick={onSchedule}>Agendar visita</button>
+    </div>
+  );
+}
+
+```
+
+---
+
+### 🏠 TIPO 2 — Página de Imóvel (Real Estate)
+
+**Diferença:** `content_type: 'home_listing'` obrigatório para Meta Dynamic Ads imobiliário.
+
+```jsx
+const IMOVEL = {
+  content_ids:    ['APT-SBC-001'],
+  content_type:   'home_listing',            // ← obrigatório para catálogo Meta imobiliário
+  content_name:   'Apartamento 3 Quartos - São Bernardo',
+  city:           'São Bernardo do Campo',
+  region:         'SP',
+  country:        'BR',
+  neighborhood:   'Bairro Nobre',
+  value:          850000,
+  currency:       'BRL',
+  property_size:  260,
+  num_baths:      2,
+  num_beds:       3,
+  parking_spaces: 3,
+  _ga4Items: [{
+    item_id: 'APT-SBC-001', item_name: 'Apartamento 3 Quartos',
+    item_category: 'Residencial', item_category2: 'São Bernardo do Campo',
+    price: 850000, quantity: 1
+  }],
+};
+
+export function PaginaImovel() {
+  useEffect(() => {
+    trackPageView();
+    trackViewContent(IMOVEL);               // content_type: 'home_listing' → Dynamic Ads imobiliário
+  }, []);
+
+  // Scroll 75%: sinaliza leitura profunda (interesse qualificado)
+  useEffect(() => {
+    return scrollTracker([75], (pct) =>
+      trackCustom('ImovelLido', { content_name: IMOVEL.content_name, scroll_depth: pct }));
+  }, []);
+
+  const onWhatsApp = async () => { await trackContact('whatsapp'); window.open('https://wa.me/55...', '_blank'); };
+  const onSubmit   = async (e, d) => { e.preventDefault(); await trackLead({ ...d, content_name: IMOVEL.content_name }); };
+  const onSchedule = () => trackSchedule();
+}
+```
+
+---
+
+### 🛒 TIPO 3 — E-commerce: Página de Listagem de Produtos
+
+**Funil:** Listagem → Produto → Carrinho → Checkout → Confirmação
+
+```jsx
+// ── Listagem (Category / Collection page) ──────────────────
+// ✅ PageView no load
+// ✅ ViewItemList no load (GA4 e Bing — lista de produtos visíveis)
+// ✅ SelectItem no clique em qualquer produto
+// ✅ ViewPromotion se houver banner de promoção visível no load
+// ✅ SelectPromotion no clique no banner
+
+import {
+  trackPageView, trackViewItemList, trackSelectItem,
+  trackViewPromotion, trackSelectPromotion, trackSearch
+} from '../tracking/tracking';
+
+export function ListagemProdutos({ produtos, categoria }) {
+  useEffect(() => {
+    trackPageView();
+    trackViewItemList({
+      item_list_id:   categoria.id,
+      item_list_name: categoria.nome,
+      items: produtos.map((p, i) => ({
+        item_id: p.id, item_name: p.nome,
+        item_category: categoria.nome, price: p.preco,
+        index: i, quantity: 1,
+      })),
+    });
+    // Se tiver banner de promoção visível na página:
+    trackViewPromotion({ promotion_id: 'banner_topo', promotion_name: 'Oferta da Semana' });
+  }, []);
+
+  const onClicarProduto = (produto, index) => {
+    trackSelectItem({
+      item_list_id:   categoria.id,
+      item_list_name: categoria.nome,
+      items: [{ item_id: produto.id, item_name: produto.nome, price: produto.preco, index }],
+    });
+    // navegar para página do produto
+  };
+
+  const onClicarBanner = () =>
+    trackSelectPromotion({ promotion_id: 'banner_topo', promotion_name: 'Oferta da Semana' });
+
+  const onPesquisar = (termo) =>
+    trackSearch(termo);                      // Meta: Search | GA4: search | TikTok: Search
+
+  return (/* jsx */);
+}
+```
+
+---
+
+### 🛍️ TIPO 4 — E-commerce: Página de Produto
+
+```jsx
+// ✅ PageView + ViewContent no load (obrigatório)
+// ✅ AddToCart no clique em "Adicionar ao carrinho"
+// ✅ AddToWishlist no clique em "Favoritar"
+// ✅ CustomizeProduct se houver seleção de variante (cor, tamanho)
+// ❌ NUNCA: AddToCart automático no load
+
+import {
+  trackPageView, trackViewContent, trackAddToCart,
+  trackAddToWishlist, trackCustomizeProduct
+} from '../tracking/tracking';
+
+export function PaginaProduto({ produto }) {
+  useEffect(() => {
+    trackPageView();
+    trackViewContent({
+      content_ids:  [produto.id],
+      content_type: 'product',
+      content_name: produto.nome,
+      value:        produto.preco,
+      currency:     'BRL',
+      _ga4Items: [{ item_id: produto.id, item_name: produto.nome, price: produto.preco, quantity: 1 }],
+    });
+  }, []);
+
+  const onAddToCart = (quantidade = 1) => {
+    trackAddToCart({
+      content_ids:  [produto.id],
+      content_name: produto.nome,
+      value:        produto.preco * quantidade,
+      currency:     'BRL',
+      num_items:    quantidade,
+      _ga4Items: [{ item_id: produto.id, item_name: produto.nome, price: produto.preco, quantity: quantidade }],
+    });
+  };
+
+  const onFavoritar = () =>
+    trackAddToWishlist({
+      content_ids:  [produto.id],
+      content_name: produto.nome,
+      value:        produto.preco,
+      currency:     'BRL',
+    });
+
+  const onSelecionarVariante = (variante) =>
+    trackCustomizeProduct({ content_name: produto.nome, variante });
+
+  return (/* jsx */);
+}
+```
+
+---
+
+### 🛒 TIPO 5 — E-commerce: Página do Carrinho
+
+```jsx
+// ✅ PageView + ViewCart no load
+// ✅ RemoveFromCart ao remover item
+// ✅ InitiateCheckout no clique em "Finalizar compra"
+// ❌ NUNCA: Purchase aqui — apenas na confirmação
+
+import {
+  trackPageView, trackViewCart, trackRemoveFromCart, trackInitiateCheckout
+} from '../tracking/tracking';
+
+export function Carrinho({ itens, total }) {
+  useEffect(() => {
+    trackPageView();
+    trackViewCart({
+      value:    total,
+      currency: 'BRL',
+      _ga4Items: itens.map(i => ({ item_id: i.id, item_name: i.nome, price: i.preco, quantity: i.qtd })),
+    });
+  }, []);
+
+  const onRemoverItem = (item) =>
+    trackRemoveFromCart({
+      content_name: item.nome,
+      value:        item.preco * item.qtd,
+      currency:     'BRL',
+      _ga4Items: [{ item_id: item.id, item_name: item.nome, price: item.preco, quantity: item.qtd }],
+    });
+
+  const onFinalizarCompra = () => {
+    trackInitiateCheckout({
+      value:    total,
+      currency: 'BRL',
+      num_items: itens.length,
+      content_ids: itens.map(i => i.id),
+      _ga4Items: itens.map(i => ({ item_id: i.id, item_name: i.nome, price: i.preco, quantity: i.qtd })),
+    });
+    // navegar para checkout
+  };
+
+  return (/* jsx */);
+}
+```
+
+---
+
+### 💳 TIPO 6 — E-commerce: Página de Checkout
+
+```jsx
+// ✅ PageView no load
+// ✅ AddShippingInfo ao confirmar endereço de entrega
+// ✅ AddPaymentInfo ao informar dados de pagamento
+// ❌ NUNCA: Purchase aqui — apenas na confirmação do pedido
+
+import {
+  trackPageView, trackAddShippingInfo, trackAddPaymentInfo
+} from '../tracking/tracking';
+
+export function Checkout({ itens, total }) {
+  useEffect(() => { trackPageView(); }, []);
+
+  const onConfirmarEndereco = () =>
+    trackAddShippingInfo({
+      value:    total,
+      currency: 'BRL',
+      _ga4Items: itens.map(i => ({ item_id: i.id, item_name: i.nome, price: i.preco, quantity: i.qtd })),
+    });
+
+  const onInformarPagamento = (metodoPagamento) =>
+    trackAddPaymentInfo({
+      value:          total,
+      currency:       'BRL',
+      payment_type:   metodoPagamento,      // 'credit_card', 'pix', 'boleto'
+      _ga4Items: itens.map(i => ({ item_id: i.id, item_name: i.nome, price: i.preco, quantity: i.qtd })),
+    });
+
+  return (/* jsx */);
+}
+```
+
+---
+
+### ✅ TIPO 7 — E-commerce: Página de Confirmação / Obrigado (Compra)
+
+```jsx
+// ✅ PageView + Purchase no load — UMA VEZ (usar order_id único para deduplicação)
+// ✅ Purchase com value, currency e order_id obrigatórios
+// ❌ NUNCA: Purchase em qualquer outra página além desta
+// ❌ NUNCA: sem order_id (causa duplicação nos relatórios)
+
+import { useEffect, useRef } from 'react';
+import { trackPageView, trackPurchase } from '../tracking/tracking';
+
+export function PaginaObrigado({ pedido }) {
+  const fired = useRef(false);              // proteção contra double-fire no StrictMode
+
+  useEffect(() => {
+    if (fired.current) return;
+    fired.current = true;
+
+    trackPageView();
+    trackPurchase({
+      order_id:     pedido.id,             // OBRIGATÓRIO — evita duplicatas browser + servidor
+      value:        pedido.total,          // OBRIGATÓRIO
+      currency:     'BRL',                 // OBRIGATÓRIO
+      content_ids:  pedido.itens.map(i => i.id),
+      email:        pedido.email,          // Enhanced Matching Meta + Google Enhanced Conversions
+      phone:        pedido.telefone,
+      firstName:    pedido.nome,
+      _ga4Items: pedido.itens.map(i => ({
+        item_id: i.id, item_name: i.nome, price: i.preco, quantity: i.qtd
+      })),
+    });
+  }, []);
+
+  return (/* jsx */);
+}
+```
+
+---
+
+### 🎓 TIPO 8 — Infoproduto / SaaS: Página de Obrigado (Lead)
+
+```jsx
+// Quando o lead é capturado em outra página e confirmado aqui
+// ✅ PageView + Lead no load (se não foi disparado no formulário anterior)
+// ✅ SignUp se for cadastro de conta
+
+import { useEffect, useRef } from 'react';
+import { trackPageView, trackLead, trackSignUp } from '../tracking/tracking';
+
+export function ObrigadoLead({ dados }) {
+  const fired = useRef(false);
+
+  useEffect(() => {
+    if (fired.current) return;
+    fired.current = true;
+
+    trackPageView();
+    // Disparar Lead AQUI apenas se não foi disparado no formulário anterior
+    // Se o formulário já chamou trackLead(), NÃO chamar novamente aqui
+    trackLead({
+      email:        dados.email,
+      phone:        dados.phone,
+      firstName:    dados.nome,
+      content_name: 'Lead Capturado',
+      value:        0,
+      currency:     'BRL',
+    });
+  }, []);
+
+  return (/* jsx */);
+}
+```
+
+---
+
+### 📧 TIPO 9 — Página de Assinatura / Newsletter / SaaS Trial
+
+```jsx
+// ✅ PageView + ViewContent no load
+// ✅ Subscribe no onSubmit do formulário de assinatura
+// ✅ StartTrial no início de período de teste
+// ✅ SignUp na criação de conta
+
+import {
+  trackPageView, trackViewContent, trackSubscribe, trackStartTrial, trackSignUp
+} from '../tracking/tracking';
+
+export function PaginaAssinatura({ plano }) {
+  useEffect(() => {
+    trackPageView();
+    trackViewContent({ content_name: plano.nome, value: plano.preco, currency: 'BRL' });
+  }, []);
+
+  const onAssinar = async (e, dados) => {
+    e.preventDefault();
+    await trackSubscribe({ value: plano.preco, currency: 'BRL', email: dados.email });
+  };
+
+  const onIniciarTrial = async (e, dados) => {
+    e.preventDefault();
+    await trackStartTrial({ value: 0, currency: 'BRL', email: dados.email });
+  };
+
+  const onCriarConta = (metodo = 'email') => trackSignUp(metodo);
+
+  return (/* jsx */);
+}
+```
+
+---
+
+### 📰 TIPO 10 — Blog / Conteúdo / Artigo
+
+```jsx
+// ✅ PageView no load
+// ✅ ViewContent no load (o artigo é o conteúdo)
+// ✅ ScrollTracker para medir engajamento com o conteúdo
+// ✅ Download se houver material para baixar
+// ✅ Lead se houver formulário de newsletter inline
+
+import {
+  trackPageView, trackViewContent, trackDownload, trackLead, scrollTracker
+} from '../tracking/tracking';
+
+export function PaginaArtigo({ artigo }) {
+  useEffect(() => {
+    trackPageView();
+    trackViewContent({
+      content_ids:  [artigo.slug],
+      content_type: 'article',
+      content_name: artigo.titulo,
+    });
+  }, []);
+
+  useEffect(() => {
+    // Medir profundidade de leitura — útil para remarketing de leitores engajados
+    return scrollTracker([25, 50, 75, 90], (pct) =>
+      trackCustom('LeituraArtigo', { artigo: artigo.slug, scroll_depth: pct }));
+  }, []);
+
+  const onDownload = (arquivo) =>
+    trackDownload({ content_name: arquivo.nome, content_ids: [arquivo.id] });
+
+  const onNewsletterSubmit = async (e, email) => {
+    e.preventDefault();
+    await trackLead({ email, content_name: 'Newsletter', value: 0, currency: 'BRL' });
+  };
+
+  return (/* jsx */);
+}
+```
+
+---
+
+### 📍 TIPO 11 — Página de Localização / Franquia / Loja Física
+
+```jsx
+// ✅ PageView + ViewContent no load
+// ✅ FindLocation no clique em "Ver no mapa" ou "Como chegar"
+// ✅ Contact no clique em WhatsApp/telefone da unidade
+
+import {
+  trackPageView, trackViewContent, trackFindLocation, trackContact
+} from '../tracking/tracking';
+
+export function PaginaUnidade({ unidade }) {
+  useEffect(() => {
+    trackPageView();
+    trackViewContent({ content_name: unidade.nome, content_type: 'local' });
+  }, []);
+
+  const onVerMapa  = () => trackFindLocation();
+  const onWhatsApp = async () => { await trackContact('whatsapp'); window.open(unidade.whatsapp); };
+
+  return (/* jsx */);
+}
+```
+
+---
+
+### 🔁 SEQUÊNCIA CORRETA DO FUNIL DE E-COMMERCE (visão geral)
+
+```
+Listagem       → PageView + ViewItemList
+    ↓ clique
+Produto        → PageView + ViewContent
+    ↓ ação
+Carrinho       → PageView + ViewCart + AddToCart (vem do clique anterior)
+    ↓ ação
+Checkout       → PageView + InitiateCheckout + AddShippingInfo + AddPaymentInfo
+    ↓ confirmação
+Obrigado       → PageView + Purchase (com order_id único)
+```
+
+### 🔁 SEQUÊNCIA CORRETA DO FUNIL DE LEAD (visão geral)
+
+```
+Landing Page   → PageView + ViewContent
+    ↓ interação
+                 scrollTracker (micro-conversão de interesse)
+                 onFocus formulário → trackCustom('FormStart')
+    ↓ submit
+                 onSubmit → trackLead() OU trackContact()
+    ↓ redirect
+Obrigado        → PageView (+ Lead apenas se não foi disparado no formulário)
+```
+
+---
+
+## PASSO 5 — Mapeamento de eventos por plataforma
+
+### 📄 Eventos de Navegação
+
+| Função CDP Edge | Meta | GA4 | TikTok | Pinterest | Bing | Reddit |
+|---|---|---|---|---|---|---|
+| `trackPageView()` | PageView | page_view | PageView | pagevisit | pageLoad | PageVisit |
+| `trackViewContent(params)` | ViewContent | view_item | ViewContent | viewcategory | view_content | ViewContent |
+| `trackSearch(query)` | Search | search | Search | — | search | Search |
+| `trackFindLocation()` | FindLocation | find_location | FindLocation | — | find_location | — |
+
+### 🛒 Eventos de E-commerce
+
+| Função CDP Edge | Meta | GA4 | TikTok | Pinterest | Bing | Reddit |
+|---|---|---|---|---|---|---|
+| `trackAddToCart(params)` | AddToCart | add_to_cart | AddToCart | addtocart | add_to_cart | AddToCart |
+| `trackAddToWishlist(params)` | AddToWishlist | add_to_wishlist | AddToWishlist | — | add_to_wishlist | — |
+| `trackRemoveFromCart(params)` | — | remove_from_cart | — | — | remove_from_cart | — |
+| `trackViewCart(params)` | — | view_cart | — | — | view_cart | — |
+| `trackViewItemList(params)` | — | view_item_list | — | — | view_item_list | — |
+| `trackSelectItem(params)` | — | select_item | — | — | select_item | — |
+| `trackInitiateCheckout(params)` | InitiateCheckout | begin_checkout | InitiateCheckout | checkout | initiate_checkout | AddToCart |
+| `trackAddPaymentInfo(params)` | AddPaymentInfo | add_payment_info | AddPaymentInfo | — | add_payment_info | — |
+| `trackAddShippingInfo(params)` | — | add_shipping_info | — | — | add_shipping_info | — |
+| `trackPurchase(params)` | Purchase | purchase | CompletePayment *(+ ttq.identify())* | checkout | purchase | Purchase |
+| `trackCustomizeProduct(params)` | CustomizeProduct | customize_product | CustomizeProduct | — | — | — |
+
+### 🏷️ Eventos de Promoção
+
+| Função CDP Edge | Meta | GA4 | TikTok | Pinterest | Bing | Reddit |
+|---|---|---|---|---|---|---|
+| `trackViewPromotion(params)` | — | view_promotion | — | — | view_promotion | — |
+| `trackSelectPromotion(params)` | — | select_promotion | — | — | select_promotion | — |
+
+### 🎯 Eventos de Conversão / Lead
+
+| Função CDP Edge | Meta | GA4 | TikTok | Pinterest | Bing | Reddit |
+|---|---|---|---|---|---|---|
+| `trackLead(params)` | Lead | generate_lead | Lead *(+ ttq.identify())* | lead | submit_form | Lead |
+| `trackContact(params)` | Contact | generate_lead | Contact | lead | contact | Lead |
+| `trackSchedule(params)` | Schedule | generate_lead | Schedule | lead | schedule | Lead |
+| `trackSignUp(params)` | CompleteRegistration | sign_up | CompleteRegistration | signup | sign_up | SignUp |
+| `trackSubscribe(params)` | Subscribe | — | Subscribe | — | subscribe | Lead |
+| `trackStartTrial(params)` | StartTrial | — | StartTrial | — | start_trial | — |
+| `trackSubmitApplication(params)` | SubmitApplication | — | SubmitForm | — | submit_application | Lead |
+| `trackDonate(params)` | Donate | — | — | — | donate | Purchase |
+| `trackDownload(params)` | — | file_download | Download | — | download | — |
+
+### ⚙️ Utilitários
+
+| Função CDP Edge | Descrição |
+|---|---|
+| `trackCustom(name, params)` | Evento personalizado em todas as plataformas ativas |
+| `scrollTracker(thresholds, cb)` | Dispara callback em % de scroll (ex: 25%, 50%, 75%, 90%) |
+| `getCityFromGeolocation()` | Captura cidade do usuário via GPS + OpenStreetMap (gratuito) |
+| `sendServerEvent(name, params)` | Envia evento direto ao servidor (fire-and-forget, não bloqueia) |
+| `getUTMs()` | Retorna `{ utm_source, utm_medium, utm_campaign, utm_content, utm_term }` da URL — para rastreamento interno e CRM (independente da atribuição das plataformas) |
+| `getUserId()` | Retorna User ID first-party persistente (cookie 365 dias) — identifica o mesmo usuário entre sessões sem depender de cookies de terceiros |
+| `passCheckoutParams(options?)` | Injeta UTMs + User ID nos links de checkout externo (Hotmart, Kiwify, Eduzz, Monetizze, CartPanda). Hotmart: `xcod` + `sck` (UTMs pipe-separados). Kiwify/Eduzz: `src`. Usa MutationObserver para links carregados dinamicamente. Chamar no `useEffect` do layout ou no `<body onload>` |
+| `normalizePhone(tel)` | Remove caracteres não-numéricos e adiciona DDI Brasil `55`. Formato exigido pela Meta: `'5511999998888'`. Retorna `undefined` se vazio |
+| `normalizeCity(city)` | Normaliza cidade para campo `ct` do Meta Advanced Matching: lowercase, remove acentos e caracteres especiais. Ex: `'São Paulo'` → `'saopaulo'`. Deve ser aplicada ANTES do SHA256 no servidor (CAPI) |
+| `splitName(fullName)` | Divide nome completo em `{ firstName, lastName }` — alinha com campos `fn`/`ln` do Meta CAPI e Enhanced Conversions do Google |
+| `isValidEmail(email)` | Valida formato de email — retorna `true/false`. Usar como guarda antes de `trackLead()` |
+| `readField(selector)` | Lê valor de campo de formulário por `id`, `name` ou seletor CSS. Usa fallback automático entre os dois |
+| `fixItems(raw, fieldMap?)` | Converte items MAL FORMATADOS para o padrão GA4. Recebe objeto ou array com qualquer estrutura de campo |
+| `buildItems(params)` | Monta array GA4 a partir de parâmetros SOLTOS (product_id, product_name, price, etc.) |
+| `ga4ItemsToMeta(items)` | Converte GA4 items → `{ content_ids, contents, num_items, value }` do Meta Pixel (Universal Conversion). Cada `contents[i]` inclui `id`, `quantity`, `item_price`, `title`, `category`, `brand` — formato completo exigido pelo Meta para e-commerce |
+| `ga4ItemsToTikTok(items)` | Converte GA4 items → `{ contents, value }` do TikTok Pixel (Universal Conversion) |
+
+### 📋 Parâmetros comuns
+
+| Parâmetro | Tipo | Usado em |
+|---|---|---|
+| `value` | number | Purchase, Lead, Subscribe, Donate, etc. |
+| `currency` | string | Purchase, AddToCart, etc. (ex: `'BRL'`) |
+| `content_ids` | string[] | ViewContent, AddToCart, Purchase |
+| `content_name` | string | ViewContent, AddToCart, etc. |
+| `content_type` | string | ViewContent (`'product'`, `'home_listing'`, etc.) |
+| `order_id` | string | Purchase (único por pedido — evita duplicatas) |
+| `email` | string | Lead, Purchase (será hashed SHA256 no server-side) |
+| `phone` | string | Lead, Purchase (será hashed SHA256 no server-side) |
+| `firstName` | string | Lead, Purchase (será hashed SHA256 no server-side) |
+| `items` | object[] | Eventos GA4 de e-commerce (name, id, price, quantity) |
+| `search_term` | string | trackSearch |
+| `promotion_id` | string | trackViewPromotion, trackSelectPromotion |
+| `item_list_id` | string | trackViewItemList, trackSelectItem |
+
+---
+
+## CHECKLIST ANTI-ERROS
+
+- [ ] `ViewContent` no **carregamento** da página — nunca no scroll
+- [ ] Botão de CTA/orçamento → `trackLead()` ou `trackContact()`, **nunca** AddToWishlist
+- [ ] `trackPageView()` em **toda** página via `useEffect(()=>{}, [])`
+- [ ] `send_page_view: false` no gtag (SPA) — `true` / ausente em HTML puro
+- [ ] `value` + `currency` obrigatórios no `trackPurchase()`
+- [ ] `order_id` único em Purchase (evita duplicata)
+- [ ] Formulários com `trackLead()` no `onSubmit` (não no onClick do botão)
+- [ ] Credenciais null no config → plataforma ignorada sem erros
+- [ ] GA4 com tag ativa além do ID (erro clássico: ID configurado como variável mas sem tag)
+- [ ] `trackLead()` e `trackContact()` são **async** — usar `await` ou não bloquear a UX
+- [ ] Geolocalização é opcional para o usuário — se negar, o evento dispara normalmente sem `city`
+- [ ] Nunca usar geolocalização como **condição de disparo** — sempre disparar o evento, capturar cidade como dado extra
+- [ ] No Modo A (Aplicação Direta): nunca sobrescrever arquivos inteiros — usar `Edit` para inserir blocos cirurgicamente
+- [ ] UTMs são capturados automaticamente na chegada — para rastreamento interno usar `getUTMs()` e incluir no payload enviado ao servidor
+- [ ] UTMs **NÃO** são enviados para as plataformas de anúncio diretamente — servem para rastreamento interno (D1, CRM) independente da janela de atribuição das plataformas
+- [ ] Página SPA: UTMs capturados no primeiro carregamento são preservados mesmo após navegação entre rotas (ficam em `_utms` na memória)
+- [ ] `gclid`, `wbraid`, `gbraid` capturados da URL → atribuição a nível de anúncio do Google Ads
+- [ ] `ttclid` capturado da URL → atribuição a nível de anúncio do TikTok Ads
+- [ ] Enhanced Conversions (Google Ads): passar `email` e `phone` no `trackLead()` e `trackPurchase()` para ativar atribuição a nível de usuário
+- [ ] `allow_enhanced_conversions: true` na config do `gtag('config', 'AW-...')` — obrigatório para Enhanced Conversions funcionar
+- [ ] User ID first-party (`getUserId()`) — incluir em payloads de servidor para identificação cross-session
+
+---
+
+## PASSO 6 — MODO SERVER-SIDE (quando solicitado)
+
+> **Quando usar:** o usuário pede tracking server-side, CAPI, Measurement Protocol, "evitar bloqueio de adblocker", ou quer o endpoint `/api/tracking`.
+
+### Por que server-side existe
+
+Adblockers e o ITP do Safari bloqueiam ou limitam pixels no browser. O server-side envia o mesmo evento direto das APIs das plataformas, sem depender do navegador. As plataformas deduplicam pelo `event_id` — o mesmo ID enviado pelo browser e pelo servidor.
+
+### Arquitetura com server-side
+
+```
+Browser (tracking.js)
+  ├── dispara evento client-side (Meta Pixel, GA4, TikTok...)
+  ├── gera event_id único
+  ├── lê cookies: _fbp, _fbc, _ttp, _ga
+  ├── captura UTMs da URL (utm_source, utm_medium, utm_campaign, utm_content, utm_term)
+  └── POST /api/tracking → { event_name, event_id, cookies, utms, user_data, page_url }
+
+Servidor Node.js (/api/tracking)
+  ├── recebe payload do browser
+  ├── adiciona: IP real, User-Agent do header
+  ├── SHA256 hash: email, phone, nome, cidade, estado, CEP, país
+  └── envia simultaneamente para:
+      ├── Meta CAPI        (graph.facebook.com)
+      ├── GA4 MP           (apenas purchase/refund)
+      └── TikTok Events API
+```
+
+---
+
+### PASSO 6.1 — Atualizar `tracking.config.js` com credenciais server-side
+
+```js
+const TRACKING_CONFIG = {
+  // ... credenciais existentes ...
+
+  // ── SERVER-SIDE (backend) ──────────────────────────────
+  server: {
+    metaCapi: {
+      accessToken: null,           // Meta CAPI Access Token (gerado no Events Manager)
+      testEventCode: null,         // ex: 'TEST12345' — só durante testes
+    },
+    ga4: {
+      apiSecret: null,             // GA4 Measurement Protocol API Secret
+      // measurement_id já usa ga4Id acima
+    },
+    tiktok: {
+      accessToken: null,           // TikTok Events API Access Token
+      testEventCode: null,
+    },
+  },
+};
+```
+
+---
+
+### PASSO 6.2 — Atualizar `tracking.js` para coletar cookies e enviar ao servidor
+
+Adicionar ao `tracking.js` a função `sendServerEvent` que coleta os cookies do browser e faz POST ao endpoint:
+
+```js
+// ── Captura cookies do browser para repassar ao servidor ──
+// Cookies gerados pelas plataformas (identificam usuário e anúncio de origem)
+const getCookies = () => ({
+  // Meta
+  fbp:      document.cookie.match(/_fbp=([^;]+)/)?.[1]    || '',  // ID do browser pelo Meta Pixel
+  fbc:      document.cookie.match(/_fbc=([^;]+)/)?.[1]    || '',  // Click ID Meta (gerado do fbclid)
+  // TikTok
+  ttp:      document.cookie.match(/_ttp=([^;]+)/)?.[1]    || '',  // ID do browser pelo TikTok Pixel
+  // Google Analytics
+  ga:       document.cookie.match(/_ga=([^;]+)/)?.[1]     || '',  // Raw _ga cookie
+  // GA4 sessão — necessário para GA4 Measurement Protocol em webhooks externos (PASSO 2.23)
+  // _ga_PROPERTY: "GS1.1.{session_id}.{session_num}.1.{last}.0.0.0"
+  gaClient: (document.cookie.match(/_ga=([^;]+)/)?.[1] || '').replace(/^GA\d+\.\d+\./, ''), // client_id limpo
+  gaSessionId:  (document.cookie.match(/_ga_[^=]+=([^;]+)/)?.[1] || '').replace(/^GS\d+\.\d+\./, '').split('.')[0] || '',
+  gaSessionNum: (document.cookie.match(/_ga_[^=]+=([^;]+)/)?.[1] || '').replace(/^GS\d+\.\d+\./, '').split('.')[1] || '',
+  // Google Ads
+  gcl_aw:   document.cookie.match(/_gcl_aw=([^;]+)/)?.[1] || '', // Click ID Google Ads (do gclid)
+
+  // Click IDs da URL (capturados no carregamento — não ficam em cookies por padrão)
+  ctwaClid: _ctwaClid,  // Meta Click-to-WhatsApp
+  gclid:    _gclid,     // Google Ads standard
+  wbraid:   _wbraid,    // Google Ads (iOS / privacy preserving)
+  gbraid:   _gbraid,    // Google Ads (app campaigns)
+  ttclid:   _ttclid,    // TikTok Ads
+
+  // User ID first-party (persistente entre sessões, não bloqueado por ad-blockers)
+  userId:   _userId,
+});
+
+// ── Envio server-side (fire and forget — não bloqueia UX) ──
+const sendServerEvent = (eventName, eventId, payload = {}) => {
+  if (!isBrowser) return;
+  // Não usar await — deixar rodar em paralelo com o event client-side
+  fetch('/api/tracking', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      event_name: eventName,
+      event_id:   eventId,
+      page_url:   window.location.href,
+      referrer:   document.referrer,
+      cookies:    getCookies(),
+      utms:       _utms,   // UTMs para rastreamento interno (atribuição própria)
+      ...payload,
+    }),
+  }).catch(() => {}); // silencia erros de rede
+};
+
+// ── Gerador de event_id único (compartilhado browser ↔ servidor) ──
+const genId = () => `${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+```
+
+Atualizar `trackLead`, `trackPurchase` e `trackContact` para gerar `event_id` e chamar `sendServerEvent` em paralelo:
+
+```js
+export const trackLead = async (params = {}) => {
+  const eventId = genId();
+  const cidade  = await getCidade();
+  const base    = { value: 0, currency: 'BRL', ...params, ...(cidade && { city: cidade }) };
+
+  // Client-side (existente)
+  if (active('metaPixelId'))   window.fbq('track', 'Lead', base, { eventID: eventId });
+  // ... demais plataformas ...
+
+  // Server-side (paralelo)
+  sendServerEvent('Lead', eventId, {
+    value: base.value, currency: base.currency,
+    content_name: base.content_name || '',
+    city: cidade || '',
+    // email/phone: se disponíveis no formulário, passar via params
+    email: params.email || '',
+    phone: params.phone || '',
+  });
+};
+```
+
+> **Regra:** `eventID` deve ser passado como 3º argumento do `fbq('track', ...)` para deduplicação Meta. TikTok usa `event_id` nas `properties`.
+
+---
+
+### PASSO 6.3 — Endpoint `/api/tracking` (Node.js / Next.js API Route)
+
+```js
+// Node.js Express: src/api/tracking.js
+// Next.js App Router: app/api/tracking/route.js
+// Next.js Pages Router: pages/api/tracking.js
+
+import crypto from 'crypto';
+import CONFIG from '../tracking/tracking.config.js';  // ajustar path
+
+// SHA256 com lowercase e trim — padrão exigido pela Meta e TikTok
+const sha256 = (val) => val
+  ? crypto.createHash('sha256').update(String(val).toLowerCase().trim()).digest('hex')
+  : '';
+
+// IP real — checka proxies e load balancers
+const getRealIp = (req) =>
+  req.headers['x-forwarded-for']?.split(',')[0].trim() ||
+  req.headers['x-real-ip'] ||
+  req.socket?.remoteAddress ||
+  req.ip || '';
+
+// ── HANDLER PRINCIPAL ──
+export async function POST(req) {                    // Next.js App Router
+// export default async function handler(req, res) { // Express / Pages Router
+
+  const body      = await req.json();               // Next.js App Router
+  // const body   = req.body;                       // Express / Pages Router
+
+  const {
+    event_name, event_id, page_url, referrer,
+    cookies = {},
+    utms = {},            // UTMs para rastreamento interno (atribuição própria)
+    email = '', phone = '', firstName = '', lastName = '',
+    city = '', state = '', zipCode = '', country = 'br',
+    value = 0, currency = 'BRL', content_name = '',
+    content_ids = [], content_type = 'product',
+    ga_client_id = '',    // extraído do cookie _ga no browser
+    method = '',
+  } = body;
+
+  // Click IDs — identificam o anúncio que originou o evento (atribuição a nível de anúncio)
+  const ctwaClid = cookies.ctwaClid || '';   // Meta Click-to-WhatsApp
+  const gclid    = cookies.gclid    || '';   // Google Ads standard click ID → Enhanced Conversions
+  const wbraid   = cookies.wbraid   || '';   // Google Ads (iOS / privacy preserving)
+  const gbraid   = cookies.gbraid   || '';   // Google Ads (app campaigns)
+  const ttclid   = cookies.ttclid   || '';   // TikTok Ads click ID
+  const userId   = cookies.userId   || '';   // User ID first-party (cross-session)
+
+  // UTMs extraídos — disponíveis para salvar em CRM/banco com cada evento
+  // Exemplo: salvar no D1 → { event_name, utm_source, utm_campaign, email, value, page_url }
+  const { utm_source = '', utm_medium = '', utm_campaign = '', utm_content = '', utm_term = '' } = utms;
+
+  const userAgent  = req.headers['user-agent'] || '';
+  const ip         = getRealIp(req);
+  const eventTime  = Math.floor(Date.now() / 1000);
+
+  const results = await Promise.allSettled([
+    sendMetaCapi({ event_name, event_id, page_url, ip, userAgent,
+                   cookies, email, phone, firstName, lastName,
+                   city, state, zipCode, country,
+                   value, currency, content_name, content_ids, content_type,
+                   ctwaClid, userId, eventTime }),
+    sendGA4Mp({ event_name, event_id, page_url,
+                value, currency, content_name, ga_client_id, eventTime }),
+    sendTiktokApi({ event_name, event_id, page_url, ip, userAgent,
+                    cookies, email, phone, userId, value, currency, content_name, eventTime }),
+  ]);
+
+  // Next.js App Router
+  return Response.json({ ok: true });
+  // Express: res.json({ ok: true });
+}
+
+// ══════════════════════════════════════════════════════════
+// META CONVERSIONS API
+// ══════════════════════════════════════════════════════════
+async function sendMetaCapi(p) {
+  if (!CONFIG.metaPixelId || !CONFIG.server?.metaCapi?.accessToken) return;
+
+  // user_data — todos os campos que existirem com SHA256
+  // REGRA META: normalizar ANTES de hashear. Ordem importa:
+  //   email   → lowercase + trim → sha256
+  //   phone   → apenas dígitos (DDI incluído, ex: 5511999998888) → sha256
+  //   fn / ln → lowercase + trim → sha256
+  //   ct      → lowercase, sem acentos, sem espaços, sem caracteres especiais → sha256
+  //             ex: 'São Paulo' → 'saopaulo' → sha256('saopaulo')
+  //   st      → código 2 letras lowercase (ex: 'sp', 'rj') → sha256
+  //   zp      → apenas dígitos (sem hífen) → sha256
+  //   country → código ISO 2 letras lowercase (ex: 'br') → sha256
+  //   fbp / fbc / ctwa_clid / external_id → NÃO hashear
+  //   external_id → sha256 do User ID first-party (_cdp_uid)
+
+  // normaliza cidade: lowercase, remove acentos, remove tudo que não é a-z0-9
+  const normalizeCity = (city = '') =>
+    String(city).normalize('NFD').replace(/[\u0300-\u036f]/g, '').toLowerCase().replace(/[^a-z0-9]/g, '');
+
+  const user_data = {
+    client_ip_address: p.ip,                            // obrigatório quando action_source=website
+    client_user_agent: p.userAgent,                     // obrigatório quando action_source=website
+    ...(p.cookies.fbp  && { fbp:         p.cookies.fbp }),   // cookie _fbp — não hashear
+    ...(p.cookies.fbc  && { fbc:         p.cookies.fbc }),   // cookie _fbc — não hashear
+    // ctwa_clid: Click ID de anúncio Click-to-WhatsApp — não hashear, enviar raw
+    // Permite que a Meta atribua o evento ao anúncio CTWA específico
+    ...(p.ctwaClid     && { ctwa_clid:   p.ctwaClid }),
+    // external_id: User ID first-party — sha256 do _cdp_uid cookie
+    // Permite deduplicação cross-dispositivo e atribuição cross-session
+    ...(p.userId       && { external_id: sha256(p.userId) }),
+    ...(p.email        && { em:          sha256(p.email.toLowerCase().trim()) }),
+    ...(p.phone        && { ph:          sha256(p.phone.replace(/\D/g, '')) }),
+    ...(p.firstName    && { fn:          sha256(p.firstName.toLowerCase().trim()) }),
+    ...(p.lastName     && { ln:          sha256(p.lastName.toLowerCase().trim()) }),
+    ...(p.city         && { ct:          sha256(normalizeCity(p.city)) }),
+    ...(p.state        && { st:          sha256(p.state.toLowerCase().trim()) }),
+    ...(p.zipCode      && { zp:          sha256(p.zipCode.replace(/\D/g, '')) }),
+    ...(p.country      && { country:     sha256(p.country.toLowerCase().trim()) }),
+  };
+
+  const custom_data = {
+    value:        p.value,
+    currency:     p.currency,
+    content_name: p.content_name,
+    content_ids:  p.content_ids,
+    content_type: p.content_type,
+  };
+
+  const serverEvent = {
+    event_name:       p.event_name,
+    event_time:       p.eventTime,
+    event_id:         p.event_id,                      // deduplicação com browser
+    action_source:    'website',                       // obrigatório
+    event_source_url: p.page_url,                     // obrigatório quando action_source=website
+    user_data,
+    custom_data,
+  };
+
+  const url = `https://graph.facebook.com/v22.0/${CONFIG.metaPixelId}/events`;
+  const params = new URLSearchParams({ access_token: CONFIG.server.metaCapi.accessToken });
+  if (CONFIG.server.metaCapi.testEventCode) {
+    serverEvent.test_event_code = CONFIG.server.metaCapi.testEventCode;
+  }
+
+  await fetch(`${url}?${params}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ data: [serverEvent] }),
+  });
+}
+
+// ══════════════════════════════════════════════════════════
+// GA4 MEASUREMENT PROTOCOL
+// Nota: GA4 MP só é confiável para Purchase e eventos com transaction_id.
+// Para outros eventos, o GA4 coleta via gtag no browser é suficiente.
+// ══════════════════════════════════════════════════════════
+async function sendGA4Mp(p) {
+  if (!CONFIG.ga4Id || !CONFIG.server?.ga4?.apiSecret) return;
+  // GA4 MP só para purchase (padrão PYS e recomendação Google)
+  if (p.event_name !== 'purchase') return;
+
+  // client_id vem do cookie _ga: GA1.1.XXXXXXXXXX.YYYYYYYYYY → pegar as partes
+  const clientId = p.ga_client_id
+    ? p.ga_client_id.replace(/^GA\d+\.\d+\./, '')  // remove prefixo GA1.1.
+    : `${Date.now()}.${Math.floor(Math.random()*1e9)}`;
+
+  const url = `https://www.google-analytics.com/mp/collect` +
+    `?measurement_id=${CONFIG.ga4Id}&api_secret=${CONFIG.server.ga4.apiSecret}`;
+
+  await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      client_id: clientId,
+      events: [{
+        name: 'purchase',
+        params: {
+          transaction_id: p.event_id,
+          value:          p.value,
+          currency:       p.currency,
+          engagement_time_msec: 100,
+        }
+      }]
+    }),
+  });
+}
+
+// ══════════════════════════════════════════════════════════
+// TIKTOK EVENTS API
+// ══════════════════════════════════════════════════════════
+async function sendTiktokApi(p) {
+  if (!CONFIG.tiktokPixelId || !CONFIG.server?.tiktok?.accessToken) return;
+
+  // Mapeamento de nomes Meta → TikTok
+  const eventMap = {
+    Lead: 'SubmitForm', Purchase: 'CompletePayment',
+    ViewContent: 'ViewContent', Contact: 'Contact',
+    Schedule: 'Schedule', InitiateCheckout: 'InitiateCheckout',
+    AddToCart: 'AddToCart', CompleteRegistration: 'CompleteRegistration',
+    PageView: 'PageView',
+  };
+
+  const tiktokEvent = {
+    event:     eventMap[p.event_name] || p.event_name,
+    event_id:  p.event_id,                        // deduplicação com browser
+    timestamp: new Date().toISOString(),           // obrigatório ISO 8601
+    context: {
+      ip:         p.ip,
+      user_agent: p.userAgent,
+      page: {
+        url:      p.page_url,
+        referrer: p.referrer || '',
+      },
+      user: {
+        // SHA256 para TikTok
+        // phone: normalizar (apenas dígitos, sem +) → sha256
+        // email: lowercase + trim → sha256
+        ...(p.email     && { email:        sha256(p.email.toLowerCase().trim()) }),
+        ...(p.phone     && { phone_number: sha256(p.phone.replace(/\D/g, '')) }),
+        // external_id: User ID first-party (_cdp_uid) → sha256 — Advanced Matching cross-session
+        ...(p.userId    && { external_id:  sha256(p.userId) }),
+        // cookies — enviar raw, sem hash
+        ...(p.cookies.ttp    && { ttp:     p.cookies.ttp }),    // _ttp cookie → 'ttp' no payload
+        ...(p.cookies.ttclid && { ttclid:  p.cookies.ttclid }), // TikTok click ID
+      },
+    },
+    properties: {
+      value:        p.value,
+      currency:     p.currency,
+      content_name: p.content_name,
+      content_type: 'product',
+    },
+  };
+
+  if (CONFIG.server.tiktok.testEventCode) {
+    tiktokEvent.test_event_code = CONFIG.server.tiktok.testEventCode;
+  }
+
+  await fetch('https://business-api.tiktok.com/open_api/v1.3/event/track/', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Access-Token': CONFIG.server.tiktok.accessToken,
+    },
+    body: JSON.stringify({
+      pixel_code: CONFIG.tiktokPixelId,
+      event:      tiktokEvent,
+    }),
+  });
+}
+
+---
+
+### PASSO 6.4 — Campos SHA256 obrigatórios (padrão Meta e TikTok)
+
+| Campo | Antes de hashear |
+|---|---|
+| `email` | lowercase + trim |
+| `phone` | só dígitos (remover `+`, `-`, `(`, `)`, espaços) |
+| `firstName` | lowercase + trim |
+| `lastName` | lowercase + trim |
+| `city` | lowercase + sem acentos + sem espaços + sem caracteres especiais (`normalizeCity()`) — ex: `'São Paulo'` → `'saopaulo'` |
+| `state` | lowercase + trim (código ISO do estado, ex: `sp`) |
+| `zipCode` | só dígitos |
+| `country` | código ISO 2 letras lowercase (ex: `br`) |
+| `_ttp` (TikTok) | **NÃO hashear** — enviar raw |
+| `_fbp`, `_fbc` | **NÃO hashear** — enviar raw |
+| `ctwa_clid` | **NÃO hashear** — enviar raw (lido da URL `?ctwa_clid=xxx`) |
+
+---
+
+### PASSO 6.5 — Como testar server-side
+
+**Meta:**
+1. Adicionar `test_event_code` nas credenciais (`CONFIG.server.metaCapi.testEventCode`)
+2. Acessar Meta Events Manager → Testar Eventos → filtrar pelo test code
+
+**TikTok:**
+1. Adicionar `test_event_code` nas credenciais TikTok
+2. Acessar TikTok Events Manager → Testar Eventos
+
+**GA4 Measurement Protocol:**
+Trocar URL de coleta para:
+`https://www.google-analytics.com/debug/mp/collect?measurement_id=...&api_secret=...`
+Retorna JSON com `validationMessages` indicando erros.
+
+---
+
+### Checklist server-side
+
+- [ ] `ctwa_clid` capturado de `URLSearchParams` no carregamento da página e enviado no POST ao endpoint — **não hashear, não colocar no cookie**
+- [ ] `ctwa_clid` enviado em `user_data.ctwa_clid` na Meta CAPI — permite atribuição a anúncios Click-to-WhatsApp
+- [ ] `event_id` é o MESMO no browser e no servidor para deduplicação correta
+- [ ] `action_source: 'website'` + `event_source_url` + `client_ip_address` + `client_user_agent` — todos obrigatórios na Meta CAPI
+- [ ] Cookies `_fbp` e `_fbc` coletados no browser e repassados no POST
+- [ ] Cookie `_ttp` coletado e repassado para TikTok (sem hash)
+- [ ] `_ga` cookie extraído e `client_id` parseado corretamente para GA4 MP
+- [ ] SHA256 aplicado em todos os campos de user_data — Meta e TikTok
+- [ ] Telefone normalizado (só dígitos) antes do SHA256
+- [ ] Email em lowercase antes do SHA256
+- [ ] `sendServerEvent` no browser é fire-and-forget (sem await que bloqueie UX)
+- [ ] Em produção: remover `testEventCode` das configurações
+
+---
+
+---
+
+### Arquitetura de Servidor (Cloudflare Workers)
+
+O CDP Edge opera exclusivamente sobre a infraestrutura **Cloudflare Workers (Quantum Tier)**.
+
+O CDP Edge recomenda o uso de **Cloudflare Workers (Quantum Tier)** como endpoint de rastreamento principal. Ele oferece latência global de ~10ms, banco de dados D1 nativo e custo zero para a maioria dos funis ($0 para 100k req/dia).
+
+| Recurso | Cloudflare Workers | Benefício Quantum Tier |
+|---|---|---|
+| Custo | Grátis / $5 pago | Zero barreira de entrada |
+| Banco de Dados | D1 SQLite ✅ | Persistência de leads e match |
+| SHA256 | WebCrypto Native | Segurança Enterprise |
+| Resiliência | Edge Global | Escala infinita |
+
+---
+
+## PASSO 6.6 — Cloudflare Workers + D1 (Full Core Tracking)
+
+> **Quando usar:** O padrão ouro do CDP Edge. Roda o endpoint `/api/tracking` no Cloudflare Workers e salva todos os eventos e perfis no banco D1 para atribuição precisa.
+
+### Vantagens da Infraestrutura Cloudflare Native
+
+| Recurso | Workers (free) |
+|---|---|
+| Custo | Grátis até 100k req/dia |
+| SHA256 | WebCrypto API (nativa) |
+| IP do usuário | Header `CF-Connecting-IP` (automático) |
+| Banco de dados | D1 SQLite (grátis até 5M reads/dia) |
+| Deploy | `wrangler deploy` (30s) |
+| Manutenção | Zero |
+| SSL | Automático |
+
+> ⚠️ **Diferença crítica de código:** Workers usa **WebCrypto API** (assíncrona) para SHA256 em vez do módulo `crypto` do Node. Tudo mais é quase idêntico — `fetch()` é nativo, `Request`/`Response` são padrão Web API.
+
+---
+
+### 1. Estrutura do projeto Workers
+
+```
+cdp-edge-worker/
+├── src/
+│   └── worker.js          ← endpoint principal
+├── wrangler.toml           ← configuração Cloudflare
+└── schema.sql              ← schema do banco D1
+```
+
+---
+
+### 2. `wrangler.toml` — configuração completa
+
+```toml
+name = "cdp-edge-tracking"
+main = "src/worker.js"
+compatibility_date = "2024-01-01"
+
+# ── D1 Database ──────────────────────────────────────────────
+[[d1_databases]]
+binding = "DB"
+database_name = "cdp-edge"
+database_id = "COLE_AQUI_O_ID_DO_D1"   # gerado após: wrangler d1 create cdp-edge
+
+# ── Variáveis públicas (não sensíveis) ───────────────────────
+[vars]
+META_PIXEL_ID    = "SEU_META_PIXEL_ID"
+GA4_ID           = "G-XXXXXXXXXX"
+TIKTOK_PIXEL_ID  = "SEU_TIKTOK_PIXEL_ID"
+
+# Secrets (nunca colocar aqui — usar: wrangler secret put NOME):
+# META_ACCESS_TOKEN
+# GA4_API_SECRET
+# TIKTOK_ACCESS_TOKEN
+```
+
+**Criar D1 e adicionar ID ao wrangler.toml:**
+```bash
+wrangler d1 create cdp-edge
+# Saída: database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+# Copiar esse ID para o wrangler.toml
+```
+
+wrangler secret put META_ACCESS_TOKEN
+wrangler secret put TIKTOK_ACCESS_TOKEN
+wrangler secret put GA4_API_SECRET
+
+---
+
+### 3. `schema.sql` — banco D1 para leads
+
+```sql
+CREATE TABLE IF NOT EXISTS leads (
+  id           INTEGER PRIMARY KEY AUTOINCREMENT,
+  event_id     TEXT NOT NULL,
+  event_name   TEXT NOT NULL,
+  email        TEXT DEFAULT '',
+  phone        TEXT DEFAULT '',
+  first_name   TEXT DEFAULT '',
+  last_name    TEXT DEFAULT '',
+  city         TEXT DEFAULT '',
+  value        REAL DEFAULT 0,
+  currency     TEXT DEFAULT 'BRL',
+  utm_source   TEXT DEFAULT '',
+  utm_medium   TEXT DEFAULT '',
+  utm_campaign TEXT DEFAULT '',
+  utm_content  TEXT DEFAULT '',
+  utm_term     TEXT DEFAULT '',
+  page_url     TEXT DEFAULT '',
+  user_id      TEXT DEFAULT '',
+  ip           TEXT DEFAULT '',
+  created_at   TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_leads_email      ON leads(email);
+CREATE INDEX IF NOT EXISTS idx_leads_created_at ON leads(created_at);
+CREATE INDEX IF NOT EXISTS idx_leads_event_name ON leads(event_name);
+
+-- ── Perfis de usuário (enriquecimento de webhooks) ──────────
+-- Salva cookies do browser quando o usuário está no site.
+-- Permite recuperar fbp/fbc/gclid ao receber webhooks externos (Hotmart, Kiwify etc.)
+CREATE TABLE IF NOT EXISTS user_profiles (
+  email       TEXT PRIMARY KEY,
+  fbp         TEXT DEFAULT '',
+  fbc         TEXT DEFAULT '',
+  ttp         TEXT DEFAULT '',
+  gclid       TEXT DEFAULT '',
+  user_id     TEXT DEFAULT '',
+  city        TEXT DEFAULT '',
+  state       TEXT DEFAULT '',
+  country     TEXT DEFAULT 'br',
+  user_agent  TEXT DEFAULT '',
+  ga_client   TEXT DEFAULT '',
+  updated_at  TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_profiles_user_id ON user_profiles(user_id);
+```
+
+**Criar as tabelas:**
+```bash
+wrangler d1 execute cdp-edge --file=schema.sql
+```
+
+---
+
+### 4. `src/worker.js` — endpoint completo para Cloudflare Workers
+
+```js
+// ============================================================
+// Recebe eventos do browser → Meta CAPI + TikTok Events API + D1 Database
+// ============================================================
+
+// SHA256 com WebCrypto API (nativa no Workers — não usar node:crypto)
+const sha256 = async (val) => {
+  if (!val) return '';
+  const data   = new TextEncoder().encode(String(val).toLowerCase().trim());
+  const buf    = await crypto.subtle.digest('SHA-256', data);
+  return Array.from(new Uint8Array(buf)).map(b => b.toString(16).padStart(2, '0')).join('');
+};
+
+// SHA256 SEM lowercase (para campos que já chegam normalizados)
+const sha256Raw = async (val) => {
+  if (!val) return '';
+  const data = new TextEncoder().encode(String(val));
+  const buf  = await crypto.subtle.digest('SHA-256', data);
+  return Array.from(new Uint8Array(buf)).map(b => b.toString(16).padStart(2, '0')).join('');
+};
+
+// Normaliza cidade: 'São Paulo' → 'saopaulo'
+const normalizeCity = (city = '') =>
+  String(city).normalize('NFD').replace(/[\u0300-\u036f]/g, '').toLowerCase().replace(/[^a-z0-9]/g, '');
+
+// IP real — Cloudflare injeta CF-Connecting-IP automaticamente
+const getRealIp = (request) =>
+  request.headers.get('CF-Connecting-IP') ||
+  request.headers.get('X-Forwarded-For')?.split(',')[0].trim() || '';
+
+// ── HANDLER PRINCIPAL ────────────────────────────────────────
+export default {
+  async fetch(request, env, ctx) {
+    // CORS para o site poder chamar este Worker
+    if (request.method === 'OPTIONS') {
+      return new Response(null, {
+        headers: {
+          'Access-Control-Allow-Origin':  '*',
+          'Access-Control-Allow-Methods': 'POST, OPTIONS',
+          'Access-Control-Allow-Headers': 'Content-Type',
+        },
+      });
+    }
+
+    if (request.method !== 'POST') {
+      return new Response('Method Not Allowed', { status: 405 });
+    }
+
+    const body = await request.json().catch(() => ({}));
+
+    const {
+      event_name, event_id, page_url, referrer,
+      cookies  = {},
+      utms     = {},
+      email    = '', phone     = '', firstName = '', lastName = '',
+      city     = '', state     = '', zipCode   = '', country  = 'br',
+      value    = 0,  currency  = 'BRL', content_name = '',
+      content_ids = [], content_type = 'product',
+      method   = '',
+    } = body;
+
+    const ip        = getRealIp(request);
+    const userAgent = request.headers.get('User-Agent') || '';
+    const eventTime = Math.floor(Date.now() / 1000);
+
+    const { utm_source = '', utm_medium = '', utm_campaign = '',
+            utm_content = '', utm_term = '' } = utms;
+
+    // ── Geo: browser tem prioridade (GPS real via getCidade())
+    // request.cf.country disponível grátis em todos os planos
+    // request.cf.city/region só no plano Business ($200/mês) — não usar no free/paid
+    const geoCountry = country || request.cf?.country?.toLowerCase() || 'br';
+    // Fallback por IP somente se browser não enviou cidade (usuário negou geolocalização)
+    let geoCity  = city;
+    let geoState = state;
+    if (!geoCity && ip && ip !== '127.0.0.1') {
+      try {
+        const geoRes  = await fetch(`https://ipapi.co/${ip}/json/`, { headers: { 'User-Agent': 'CDP Edge/1.0' } });
+        const geoData = await geoRes.json();
+        geoCity  = geoData.city         || '';
+        geoState = geoData.region_code?.toLowerCase() || '';
+      } catch { /* silencia falha no lookup */ }
+    }
+
+    // Disparar tudo em paralelo (não bloquear a resposta)
+    const tasks = [
+      sendMetaCapi({ event_name, event_id, page_url, referrer,
+                     ip, userAgent, cookies, email, phone, firstName, lastName,
+                     city: geoCity, state: geoState, zipCode, country: geoCountry,
+                     value, currency, content_name, content_ids, content_type,
+                     ctwaClid: cookies.ctwaClid || '',
+                     userId:   cookies.userId   || '',
+                     eventTime }, env),
+
+      sendTiktokApi({ event_name, event_id, page_url, referrer,
+                      ip, userAgent, cookies, email, phone,
+                      userId: cookies.userId || '',
+                      value, currency, content_name, eventTime }, env),
+
+      sendGA4Mp({ event_name, event_id, page_url,
+                  value, currency, content_name,
+                  ga_client_id:  cookies.gaClient     || '',
+                  ga_session_id: cookies.gaSessionId  || '',
+                  ga_session_num:cookies.gaSessionNum || '',
+                  eventTime }, env),
+    ];
+
+    // D1: salvar lead (fire-and-forget — não bloqueia resposta)
+    if (env.DB && event_name) {
+      tasks.push(
+        env.DB.prepare(
+          `INSERT INTO leads
+           (event_id, event_name, email, phone, first_name, last_name, city,
+            value, currency, utm_source, utm_medium, utm_campaign,
+            utm_content, utm_term, page_url, user_id, ip, created_at)
+           VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`
+        ).bind(
+          event_id, event_name, email, phone, firstName, lastName, city,
+          value, currency, utm_source, utm_medium, utm_campaign,
+          utm_content, utm_term, page_url,
+          cookies.userId || '', ip, new Date().toISOString()
+        ).run().catch(() => {})
+      );
+    }
+
+    // D1: salvar/enriquecer perfil do usuário (UPSERT preservando campos não-vazios)
+    // Garante que fbp/fbc/ga_session salvos aqui podem ser recuperados em webhooks futuros (Hotmart etc.)
+    if (env.DB && email) {
+      tasks.push(
+        env.DB.prepare(`
+          INSERT INTO user_profiles
+            (email, fbp, fbc, ttp, gclid, user_id, city, state, country, user_agent,
+             ga_client, ga_session_id, ga_session_num, page_location, timestamp_ms, updated_at)
+          VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+          ON CONFLICT(email) DO UPDATE SET
+            fbp           = CASE WHEN excluded.fbp           != '' THEN excluded.fbp           ELSE fbp           END,
+            fbc           = CASE WHEN excluded.fbc           != '' THEN excluded.fbc           ELSE fbc           END,
+            ttp           = CASE WHEN excluded.ttp           != '' THEN excluded.ttp           ELSE ttp           END,
+            gclid         = CASE WHEN excluded.gclid         != '' THEN excluded.gclid         ELSE gclid         END,
+            user_id       = CASE WHEN excluded.user_id       != '' THEN excluded.user_id       ELSE user_id       END,
+            city          = CASE WHEN excluded.city          != '' THEN excluded.city          ELSE city          END,
+            state         = CASE WHEN excluded.state         != '' THEN excluded.state         ELSE state         END,
+            ga_client     = CASE WHEN excluded.ga_client     != '' THEN excluded.ga_client     ELSE ga_client     END,
+            ga_session_id = CASE WHEN excluded.ga_session_id != '' THEN excluded.ga_session_id ELSE ga_session_id END,
+            ga_session_num= CASE WHEN excluded.ga_session_num!= '' THEN excluded.ga_session_num ELSE ga_session_num END,
+            page_location = excluded.page_location,
+            timestamp_ms  = excluded.timestamp_ms,
+            updated_at    = excluded.updated_at
+        `).bind(
+          email,
+          cookies.fbp || '', cookies.fbc || '', cookies.ttp || '',
+          cookies.gclid || '', cookies.userId || '',
+          geoCity || '', geoState || '', geoCountry || 'br',
+          userAgent,
+          cookies.gaClient     || '',
+          cookies.gaSessionId  || '',
+          cookies.gaSessionNum || '',
+          page_url || '',
+          String(Date.now()),
+          new Date().toISOString()
+        ).run().catch(() => {})
+      );
+    }
+
+    // ctx.waitUntil: permite que as tasks terminem após a resposta ser enviada
+    ctx.waitUntil(Promise.allSettled(tasks));
+
+    return Response.json({ ok: true }, {
+      headers: { 'Access-Control-Allow-Origin': '*' },
+    });
+  },
+};
+
+// ══════════════════════════════════════════════════════════
+// META CONVERSIONS API
+// ══════════════════════════════════════════════════════════
+async function sendMetaCapi(p, env) {
+  if (!env.META_PIXEL_ID || !env.META_ACCESS_TOKEN) return;
+
+  const user_data = {
+    client_ip_address: p.ip,
+    client_user_agent: p.userAgent,
+    ...(p.cookies.fbp  && { fbp:         p.cookies.fbp }),
+    ...(p.cookies.fbc  && { fbc:         p.cookies.fbc }),
+    ...(p.ctwaClid     && { ctwa_clid:   p.ctwaClid }),
+    ...(p.userId       && { external_id: await sha256Raw(p.userId) }),
+    ...(p.email        && { em:          await sha256(p.email) }),
+    ...(p.phone        && { ph:          await sha256Raw(p.phone.replace(/\D/g, '')) }),
+    ...(p.firstName    && { fn:          await sha256(p.firstName) }),
+    ...(p.lastName     && { ln:          await sha256(p.lastName) }),
+    ...(p.city         && { ct:          await sha256Raw(normalizeCity(p.city)) }),
+    ...(p.state        && { st:          await sha256(p.state) }),
+    ...(p.zipCode      && { zp:          await sha256Raw(p.zipCode.replace(/\D/g, '')) }),
+    ...(p.country      && { country:     await sha256(p.country) }),
+  };
+
+  const serverEvent = {
+    event_name:       p.event_name,
+    event_time:       p.eventTime,
+    event_id:         p.event_id,
+    action_source:    'website',
+    event_source_url: p.page_url,
+    user_data,
+    custom_data: {
+      value:        p.value,
+      currency:     p.currency,
+      content_name: p.content_name,
+      content_ids:  p.content_ids,
+      content_type: p.content_type,
+    },
+  };
+
+  if (env.META_TEST_EVENT_CODE) serverEvent.test_event_code = env.META_TEST_EVENT_CODE;
+
+  await fetch(
+    `https://graph.facebook.com/v22.0/${env.META_PIXEL_ID}/events?access_token=${env.META_ACCESS_TOKEN}`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ data: [serverEvent] }),
+    }
+  );
+}
+
+// ══════════════════════════════════════════════════════════
+// GA4 MEASUREMENT PROTOCOL (somente purchase)
+// ══════════════════════════════════════════════════════════
+async function sendGA4Mp(p, env) {
+  if (!env.GA4_ID || !env.GA4_API_SECRET) return;
+  if (p.event_name !== 'purchase') return;
+
+  // client_id vem do cookie _ga (sem prefixo GA1.1.)
+  const clientId = p.ga_client_id
+    ? p.ga_client_id.replace(/^GA\d+\.\d+\./, '')
+    : `${Date.now()}.${Math.floor(Math.random() * 1e9)}`;
+
+  // session_id e session_number vêm do cookie _ga_PROPERTY (sem prefixo GS1.1.)
+  const sessionId  = p.ga_session_id  || '';
+  const sessionNum = p.ga_session_num || '1';
+
+  const payload = {
+    client_id: clientId,
+    // timestamp_micros: vincula o evento à sessão correta (obrigatório para MP)
+    ...(p.eventTime && { timestamp_micros: String(p.eventTime * 1_000_000) }),
+    events: [{
+      name: 'purchase',
+      params: {
+        transaction_id:       p.event_id,
+        value:                p.value,
+        currency:             p.currency,
+        engagement_time_msec: 100,
+        // session_id e session_number conectam ao relatório de GA4 correto
+        ...(sessionId  && { session_id:     sessionId }),
+        ...(sessionNum && { session_number: Number(sessionNum) }),
+      },
+    }],
+  };
+
+  await fetch(
+    `https://www.google-analytics.com/mp/collect?measurement_id=${env.GA4_ID}&api_secret=${env.GA4_API_SECRET}`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    }
+  );
+}
+
+// ══════════════════════════════════════════════════════════
+// TIKTOK EVENTS API
+// ══════════════════════════════════════════════════════════
+async function sendTiktokApi(p, env) {
+  if (!env.TIKTOK_PIXEL_ID || !env.TIKTOK_ACCESS_TOKEN) return;
+
+  const eventMap = {
+    Lead: 'SubmitForm', Purchase: 'CompletePayment',
+    ViewContent: 'ViewContent', Contact: 'Contact',
+    Schedule: 'Schedule', InitiateCheckout: 'InitiateCheckout',
+    AddToCart: 'AddToCart', CompleteRegistration: 'CompleteRegistration',
+    PageView: 'PageView',
+  };
+
+  const tiktokEvent = {
+    event:     eventMap[p.event_name] || p.event_name,
+    event_id:  p.event_id,
+    timestamp: new Date().toISOString(),
+    context: {
+      ip:         p.ip,
+      user_agent: p.userAgent,
+      page:       { url: p.page_url, referrer: p.referrer || '' },
+      user: {
+        ...(p.email  && { email:        await sha256(p.email) }),
+        ...(p.phone  && { phone_number: await sha256Raw(p.phone.replace(/\D/g, '')) }),
+        ...(p.userId && { external_id:  await sha256Raw(p.userId) }),
+        ...(p.cookies.ttp    && { ttp:    p.cookies.ttp }),
+        ...(p.cookies.ttclid && { ttclid: p.cookies.ttclid }),
+      },
+    },
+    properties: {
+      value:        p.value,
+      currency:     p.currency,
+      content_name: p.content_name,
+      content_type: 'product',
+    },
+  };
+
+  if (env.TIKTOK_TEST_EVENT_CODE) tiktokEvent.test_event_code = env.TIKTOK_TEST_EVENT_CODE;
+
+  await fetch('https://business-api.tiktok.com/open_api/v1.3/event/track/', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Access-Token':  env.TIKTOK_ACCESS_TOKEN,
+    },
+    body: JSON.stringify({
+      pixel_code: env.TIKTOK_PIXEL_ID,
+      event:      tiktokEvent,
+    }),
+  });
+}
+```
+
+---
+
+
+---
+
+### 6. Deploy do Worker
+
+```bash
+# Instalar Wrangler (CLI Cloudflare)
+npm install -g wrangler
+
+# Login (abre browser)
+wrangler login
+
+# Criar banco D1
+wrangler d1 create cdp-edge
+# Copiar o database_id gerado → colar em wrangler.toml
+
+# Criar tabelas
+wrangler d1 execute cdp-edge --file=schema.sql
+
+# Adicionar secrets
+wrangler secret put META_ACCESS_TOKEN
+wrangler secret put TIKTOK_ACCESS_TOKEN
+wrangler secret put GA4_API_SECRET
+
+# Deploy
+wrangler deploy
+
+# URL gerada: https://cdp-edge-tracking.SEU_USUARIO.workers.dev
+```
+
+> Após o deploy, o Worker fica disponível em `https://cdp-edge-tracking.SEU_USUARIO.workers.dev`. Para usar `/api/tracking` no site, criar um **Custom Domain** nas configurações do Worker ou usar a URL completa.
+
+---
+
+### 7. Adaptar `sendServerEvent` no browser para apontar ao Worker
+
+Se o site e o Worker estão em domínios diferentes, mudar a URL no `tracking.js`:
+
+```js
+// Em vez de '/api/tracking' (mesmo domínio — Next.js / Vite server)
+// usar a URL do Worker:
+const TRACKING_ENDPOINT = 'https://cdp-edge-tracking.SEU_USUARIO.workers.dev';
+
+const sendServerEvent = (eventName, eventId, payload = {}) => {
+  if (!isBrowser) return;
+  fetch(TRACKING_ENDPOINT, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      event_name: eventName,
+      event_id:   eventId,
+      page_url:   window.location.href,
+      referrer:   document.referrer,
+      cookies:    getCookies(),
+      utms:       _utms,
+      ...payload,
+    }),
+  }).catch(() => {});
+};
+```
+
+> Se o site rodar em **Cloudflare Pages**, usar `functions/api/tracking.js` — o código do Worker é idêntico, só muda o handler para `export async function onRequestPost({ request, env, waitUntil })`.
+
+---
+
+### 8. Checklist deploy Cloudflare Workers
+
+```
+☐ wrangler.toml criado com name, main, d1_databases
+☐ D1 criado: wrangler d1 create cdp-edge → ID copiado para wrangler.toml
+☐ Schema criado: wrangler d1 execute cdp-edge --file=schema.sql
+☐ Secrets adicionados via wrangler secret put
+☐ wrangler deploy executado com sucesso
+☐ URL do Worker testada com curl ou Postman
+☐ Meta Events Manager → Testar Eventos → evento chegando
+☐ TikTok Events Manager → evento chegando
+☐ Em produção: remover META_TEST_EVENT_CODE e TIKTOK_TEST_EVENT_CODE
+```
+
+---
+
+## PASSO 7 — CTWA SEM LANDING PAGE (Cloudflare Worker + WhatsApp Business API)
+
+> **Quando usar:** usuário roda anúncios Click-to-WhatsApp que vão direto para o WhatsApp, sem passar por nenhuma página do site. Não existe pixel no browser — o rastreamento é 100% server-side via webhook.
+
+### Arquitetura
+
+```
+Anúncio Meta (Instagram / Facebook)
+    ↓ clique em "Enviar Mensagem"
+WhatsApp abre com conversa iniciada
+    ↓ usuário manda primeira mensagem
+Meta Cloud API (webhook oficial)
+    ↓ POST para Cloudflare Worker
+Worker (edge, ~5ms)
+    ├── Meta CAPI  (action_source: 'business_messaging')
+    └── Cloudflare D1 (Identity Graph)
+```
+
+### Diferença crítica de action_source
+
+| Cenário | action_source | ctwa_clid vem de |
+|---|---|---|
+| Botão WhatsApp no site | `website` | `?ctwa_clid=` na URL (JavaScript) |
+| CTWA → site → WhatsApp | `website` | `?ctwa_clid=` na URL (JavaScript) |
+| CTWA → WhatsApp direto | `business_messaging` | `message.referral.ctwa_clid` (webhook) |
+
+### PASSO 7.1 — Cloudflare Worker completo
+
+```js
+// worker.js — Cloudflare Worker
+// Deploy: wrangler deploy
+// Variáveis de ambiente: META_PIXEL_ID, META_CAPI_TOKEN, VERIFY_TOKEN, SHEET_WEBHOOK_URL
+
+const sha256 = async (val) => {
+  const data = new TextEncoder().encode(String(val).toLowerCase().trim());
+  const hash = await crypto.subtle.digest('SHA-256', data);
+  return Array.from(new Uint8Array(hash)).map(b => b.toString(16).padStart(2,'0')).join('');
+};
+
+export default {
+  async fetch(request, env) {
+
+    // ── Verificação do webhook (GET — Meta envia uma vez ao configurar) ──
+    if (request.method === 'GET') {
+      const url       = new URL(request.url);
+      const mode      = url.searchParams.get('hub.mode');
+      const token     = url.searchParams.get('hub.verify_token');
+      const challenge = url.searchParams.get('hub.challenge');
+
+      if (mode === 'subscribe' && token === env.VERIFY_TOKEN) {
+        return new Response(challenge, { status: 200 });
+      }
+      return new Response('Forbidden', { status: 403 });
+    }
+
+    // ── Receber mensagem do WhatsApp (POST) ──
+    if (request.method === 'POST') {
+      const body    = await request.json();
+      const change  = body.entry?.[0]?.changes?.[0]?.value;
+      const message = change?.messages?.[0];
+
+      // Responde 200 imediatamente — Meta exige resposta em < 20s
+      if (!message || message.type === 'status') {
+        return new Response('ok', { status: 200 });
+      }
+
+      // ── Extrair dados da conversa ──
+      const phone     = message.from;                          // ex: '5511999999999'
+      const name      = change?.contacts?.[0]?.profile?.name || '';
+      const ctwaClid  = message.referral?.ctwa_clid  || '';   // só existe se veio de anúncio CTWA
+      const adId      = message.referral?.source_id  || '';
+      const adUrl     = message.referral?.source_url || '';
+      const timestamp = Math.floor(Date.now() / 1000);
+      const eventId   = `wa_${phone}_${timestamp}`;
+
+      const lead = {
+        phone,
+        name,
+        ctwa_clid:  ctwaClid,
+        ad_id:      adId,
+        ad_url:     adUrl,
+        event_id:   eventId,
+        timestamp:  new Date().toISOString(),
+        source:     ctwaClid ? 'ctwa_ad' : 'organico',
+      };
+
+      // Rodar em paralelo sem bloquear a resposta ao WhatsApp
+      // (usar waitUntil para não cancelar após o return)
+      const ctx = { waitUntil: (p) => p }; // fallback se não tiver ExecutionContext
+      await Promise.allSettled([
+        sendMetaCapi(lead, env, await sha256(phone.replace(/\D/g, ''))),
+      ]);
+
+      return new Response('ok', { status: 200 });
+    }
+
+    return new Response('Method Not Allowed', { status: 405 });
+  }
+};
+
+// ── META CAPI (action_source: business_messaging) ─────────
+async function sendMetaCapi(lead, env, hashedPhone) {
+  if (!env.META_PIXEL_ID || !env.META_CAPI_TOKEN) return;
+
+  const user_data = {
+    ph: hashedPhone,
+    ...(lead.ctwa_clid && { ctwa_clid: lead.ctwa_clid }),  // não hashear
+  };
+
+  await fetch(
+    `https://graph.facebook.com/v22.0/${env.META_PIXEL_ID}/events?access_token=${env.META_CAPI_TOKEN}`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        data: [{
+          event_name:        'Contact',
+          event_time:        Math.floor(Date.now() / 1000),
+          event_id:          lead.event_id,
+          action_source:     'business_messaging',  // ← não é 'website'
+          messaging_channel: 'whatsapp',            // ← obrigatório
+          user_data,
+        }]
+      }),
+    }
+  );
+}
+```
+
+### PASSO 7.3 — Variáveis de ambiente no Cloudflare
+
+No painel: Workers & Pages → seu Worker → Settings → Variables and Secrets
+
+```
+META_PIXEL_ID       = 1234567890123456
+META_CAPI_TOKEN     = seu_token_capi_do_events_manager
+VERIFY_TOKEN        = qualquer_palavra_secreta (ex: cdp-edge2025)
+SHEET_WEBHOOK_URL   = https://script.google.com/macros/s/SEU_ID/exec
+```
+
+### PASSO 7.4 — Conectar o Worker ao WhatsApp Business API
+
+**Meta Cloud API (gratuita):**
+1. [developers.facebook.com](https://developers.facebook.com) → App → WhatsApp → Configuração
+2. Webhook URL: `https://seu-worker.workers.dev`
+3. Verify Token: mesmo valor de `VERIFY_TOKEN`
+4. Assinar campo: `messages`
+
+**Meta Cloud API (única opção suportada):**
+developers.facebook.com → App → WhatsApp → Configuração → Webhook URL: `https://seu-worker.workers.dev` → Assinar campo: `messages`
+
+### Checklist CTWA sem landing page
+
+- [ ] Worker responde `200 OK` imediatamente — Meta cancela webhook se demorar mais de 20s
+- [ ] Verificar se `message.referral` existe antes de ler `ctwa_clid` — nem toda mensagem vem de anúncio
+- [ ] `action_source: 'business_messaging'` + `messaging_channel: 'whatsapp'` — obrigatórios juntos
+- [ ] `ctwa_clid` enviado raw em `user_data.ctwa_clid` — não hashear
+- [ ] Telefone normalizado (só dígitos) antes do SHA256
+- [ ] `event_id` único por mensagem para evitar duplicatas (ex: `wa_{phone}_{timestamp}`)
+- [ ] Eventos chegando no Meta Events Manager
+- [ ] `VERIFY_TOKEN` configurado no Worker antes de cadastrar o webhook na Meta
+- [ ] Testar com Meta Events Manager → Testar Eventos usando `testEventCode`
+
+---
+
+## PASSO 8.4 — Pixel de Mensagens Meta (WhatsApp)
+
+#### 1. Criar App no Meta Developers
+
+1. Acessar https://developers.facebook.com
+2. Login (se pedir conta: conectar com telefone; se der erro: adicionar cartão como método de pagamento)
+3. Meus Apps → Criar App:
+
+| Campo | Valor |
+|---|---|
+| Nome | qualquer nome descritivo |
+| Caso de uso | Outro |
+| Tipo | Business (Empresa) |
+| Portfólio | selecionar o BM que contém a conta de anúncios |
+
+#### 2. Configurar API de Marketing
+
+API DE MARKETING → Configurar → Ferramentas → Obter token de acesso
+
+Permissões obrigatórias:
+- `ads_management`
+- `ads_read`
+- `read_insights`
+
+Gerar token → **salvar imediatamente** (não é exibido novamente)
+
+#### 3. Criar Pixel de Mensagens
+
+No Gerenciador de Eventos:
+1. Criar pixel de mensagens
+2. Vincular a: uma Página do Facebook **ou** um perfil do Instagram
+3. Se não aparecer páginas → desvincular a página de pixels antigos antes de tentar
+
+#### 4. Criar Usuário do Sistema (BM)
+
+URL: https://business.facebook.com/latest/settings/system_users
+
+1. Usuários → Usuários do sistema → Adicionar
+2. Definir nome, System user role = `admin`
+3. Atribuir todos os ativos
+4. Gerar token com expiração **nunca** → Copiar token
+
+#### 5. Salvar token no Cloudflare Secrets
+
+Use o Wrangler para persistir o token de forma segura no ambiente do Worker:
+
+```bash
+wrangler secret put META_MESSAGING_TOKEN
+# Cole o token gerado no passo anterior
+```
+
+---
+
+### PASSO 8.6 — Arquitetura Cloudflare Native (Quantum Tier) 🛡️⚓🚀
+
+```
+                     ┌─────────────────────────────────────┐
+                     │         CLOUDFLARE ECOSYSTEM        │
+                     │   Tudo num único Domínio Raiz       │
+                     └──────────────┬──────────────────────┘
+                                    │
+                     ┌──────────────▼──────────────────────┐
+                     │         Cloudflare Edge              │
+                     │  (Workers + D1 + R2 + Queues)        │
+                     │                                      │
+                     │  ┌──────────┐  ┌──────────┐  ┌─────┐ │
+                     │  │ Payments │  │ Messaging│  │ CRM │ │
+                     │  │ (Ticto)  │  │ (Resend) │  │ (D1)│ │
+                     │  └─────┬────┘  └─────┬────┘  └──┬──┘ │
+                     │        │             │          │    │
+                     │  ┌─────▼─────────────▼──────────▼──┐ │
+                     │  │       Identity Graph (D1)       │ │
+                     │  │   (FBP / FBC / GCLID / UTMs)    │ │
+                     │  └─────────────────────────────────┘ │
+                     └─────────────────────────────────────┘
+                               │
+               ┌───────────────┼──────────────────┐
+               │               │                  │
+    ┌──────────▼──┐   ┌────────▼────────┐   ┌─────▼──────────┐
+    │  WhatsApp   │   │   Meta CAPI     │   │   A/B Edge     │
+    │ (Cloud API) │   │     v22.0       │   │   Routing      │
+    └─────────────┘   └─────────────────┘   └────────────────┘
+```
+
+**Fluxo de Dados Autônomo:**
+1. **Inbound**: O Worker intercepta Webhooks (Ticto) ou Cliques no Site.
+2. **Process**: IA Preditiva (LTV) e Fingerprinting cruzam dados no D1.
+3. **Outbound**: Disparos simultâneos via Queues para Meta CAPI, Google Ads, TikTok e Mensageria (WhatsApp/Resend).
+4. **Resgate**: UTMs perdidas são resgatadas via Identity Graph persistente no domínio.
+
+---
+
+### PASSO 8.7 — Excelência em Infraestrutura (Quantum Tier)
+
+A arquitetura CDP Edge Quantum Tier é otimizada para máxima performance com redundância global, operando exclusivamente na borda (Edge).
+
+---
+
+**Cloudflare DNS:**
+- [ ] Nameservers apontados para Cloudflare
+- [ ] Proxy ☁️ ativado para o domínio principal (Segurança & Performance)
+- [ ] Registros CNAME configurados para os subdomínios de tracking
+- [ ] SSL configurado como "Full (Strict)"
+
+---
+
+## PASSO 2.21 — Webhooks Externos: Ticto (v2.0)
+
+> Use esta seção para orientar o usuário na configuração da Ticto como gateway principal de conversões offline e ROI.
+
+### Configuração na Ticto
+1. Acesse **Tictools > Webhooks** no menu lateral esquerdo.
+2. Clique em **+ Nova Pasta** (opcional para organização).
+3. Clique em **+ Criar Webhook**.
+4. **Endpoint URL:** `https://seu-worker.workers.dev/api/wh/ticto`
+5. **Versão:** Selecione **2.0** (Recomendado).
+6. **Formato:** Selecione **JSON**.
+7. **Eventos Críticos (Mapeamento CDP Edge):**
+   - `15. Venda Realizada` -> `Purchase`
+   - `1. Abandono de Carrinho` -> `AddToCart` / CRM
+   - `4. Pix Gerado` / `2. Boleto Impresso` -> `InitiateCheckout`
+8. **Token:** Copie o Token gerado e configure no Worker via `wrangler secret put TICTO_TOKEN`.
+
+### Validação Automática
+A Ticto enviará um POST de teste imediatamente. O Worker **DEVE** retornar status `200 OK` para que a integração seja salva com sucesso.
+
+### Payload de Referência (v2.0)
+```json
+{
+  "event_id": 15,
+  "event_name": "Venda Realizada",
+  "customer": {
+    "email": "cliente@email.com",
+    "phone": "5511999999999"
+  },
+  "transaction": {
+    "total_amount": 197.00,
+    "currency": "BRL"
+  }
+}
+```
+
+---
+
+## PASSO 2.22 — E-mail Transacional: Resend API
+
+> Use esta seção para configurar o envio de e-mails automáticos (Venda, Abandono, Bônus) diretamente do Cloudflare Worker.
+
+### Configuração no Resend
+1. Acesse **Resend > Domains** e adicione seu domínio.
+2. No Cloudflare, adicione os registros **MX, TXT (SPF/DKIM)** que o Resend fornecerá.
+3. Gere uma **API Key** e salve via `wrangler secret put RESEND_API_KEY`.
+4. Envie e-mails via `POST https://api.resend.com/emails`.
+
+---
+
+## PASSO 2.23 — Spotify Ads: Pixel + Conversions API (v1)
+
+> O Spotify Ads é a peça final do Quantum Tier. Permite rastrear conversões originadas de áudio e display no Spotify.
+
+### Especificações Técnicas
+- **Endpoint**: `https://advertising-api.spotify.com/conversion/v1/accounts/{ACCOUNT_ID}/events`
+- **Autenticação**: Bearer Token (`SPOTIFY_ACCESS_TOKEN`)
+- **Deduplicação**: `event_id` obrigatório entre Browser e Server
+- **PII Hashing**: SHA-256 obrigatório para E-mail e Telefone (Advanced Matching)
+
+### Eventos Principais
+| Evento | Conversão | Descrição |
+|---|---|---|
+| `ViewContent` | Milestone | Visualização de página de produto/serviço |
+| `AddToCart` | Intenção | Adicionado ao carrinho |
+| `Purchase` | Conversão | Compra realizada via Spotify Ads |
+| `Lead` | Conversão | Captação de lead via áudio/display |
+
+### Implementação de Borda (Worker)
+Sempre use `ctx.waitUntil` para despachar o evento para o Spotify sem atrasar a resposta ao usuário.
+
+---
+
+### 2.3 Segurança e Hashing (WebCrypto API)
+O hashing de PII (e-mail, telefone, nome) deve ser feito obrigatoriamente no servidor usando a API nativa do Cloudflare Workers:
+```javascript
+async function sha256(data) {
+  const msgBuffer = new TextEncoder().encode(data.toLowerCase().trim());
+  const hashBuffer = await crypto.subtle.digest('SHA-256', msgBuffer);
+  return Array.from(new Uint8Array(hashBuffer))
+    .map(b => b.toString(16).padStart(2, '0')).join('');
+}
+```
+
+---
+
+## 📋 3. MAPEAMENTO DE APIs
+
+| Plataforma | Versão | Endpoint Principal |
+|---|---|---|
+| **Meta (CAPI)** | v22.0 | `https://graph.facebook.com/v22.0/{PIXEL_ID}/events` |
+| **TikTok (Events)** | v1.3 | `https://business-api.tiktok.com/open_api/v1.3/event/track/` |
+| **Google (GA4)** | MP | `https://www.google-analytics.com/mp/collect` |
+| **Spotify (Ads)** | v1 | `https://advertising-api.spotify.com/conversion/v1/accounts/{ACC_ID}/events` |
+
+---
+
+## 🔄 4. PROCESSO DE CONFIGURAÇÃO
+
+1.  **Setup Worker**: Criar Worker no Cloudflare e vincular banco D1.
+2.  **Schema D1**: Executar `schema.sql` para criar as tabelas de identidade e logs.
+3.  **Wrangler Config**: Configurar `wrangler.toml` com os bindings e secrets (tokens de API).
+4.  **SDK Site**: Inserir `cdpTrack.js` e `tracking.config.js` no site.
+5.  **Event Mapping**: Configurar gatilhos de clique e formulário no site.
+6.  **Webhooks**: Configurar o endpoint de webhook na plataforma de vendas (Ticto/Hotmart).