cdp-edge 1.2.2 → 1.3.0

package/extracted-skill/tracking-events-generator/agents/whatsapp-ctwa-setup-agent.md

@@ -5,6 +5,14 @@ Sua missão: configurar o rastreamento completo de anúncios Click to WhatsApp d
 
 ---
 
+## ✅ REGRAS CRÍTICAS
+
+0. **CONSULTA OBRIGATÓRIA À MEMÓRIA**: Extraia o ID de Número WhatsApp, Token de API e Token de Verificação (`WHATSAPP_PHONE_NUMBER_ID`, `WHATSAPP_ACCESS_TOKEN`, `WA_WEBHOOK_VERIFY_TOKEN`) consultando ativamente o "memory-agent.json". Solicite ao Orquestrador tudo o que faltar. Execute configurações de WhatsApp exclusivamente com os dados oficiais guardados na Memória para garantir alinhamento sistêmico.
+1. Cloudflare-Only: Sem dependências externas.
+2. Same-Domain: Worker no domínio do site (anti-adblock).
+
+---
+
 ## PARTE 1 — FUNDAMENTOS: O QUE É CTWA E COMO OS DADOS FLUEM
 
 ### O que é Click to WhatsApp (CTWA)
@@ -164,8 +172,8 @@ message_body | Olá, vi o anúncio e tenho interesse
 [ ] META_APP_ID             — ID do app no Meta for Developers                ← usuário fornece
 [ ] META_APP_SECRET         — App Secret (developers.facebook.com → Básico)   ← usuário fornece
 [ ] WA_WEBHOOK_VERIFY_TOKEN — gerado pelo agente (crypto.randomUUID)           ← agente cria
-[ ] WA_PHONE_ID             — descoberto automaticamente via API               ← agente descobre
-[ ] WA_ACCESS_TOKEN         — mesmo que META_ACCESS_TOKEN                      ← agente reutiliza
+[ ] WHATSAPP_PHONE_NUMBER_ID             — descoberto automaticamente via API               ← agente descobre
+[ ] WHATSAPP_ACCESS_TOKEN         — mesmo que META_ACCESS_TOKEN                      ← agente reutiliza
 [ ] WHATSAPP_BUSINESS_ACCOUNT_ID — descoberto automaticamente via API          ← agente descobre
 ```
 
@@ -175,7 +183,7 @@ message_body | Olá, vi o anúncio e tenho interesse
 3. `META_APP_SECRET`
 
 **O agente gera/descobre o restante automaticamente:**
-```javascript
+```typescript
 // WA_WEBHOOK_VERIFY_TOKEN — gerado pelo agente antes de registrar o webhook
 const WA_WEBHOOK_VERIFY_TOKEN = crypto.randomUUID().replace(/-/g, '') + crypto.randomUUID().replace(/-/g, '');
 // Exemplo: "a3f8c1d2e4b5a6f7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1"
@@ -490,16 +498,16 @@ Deve mostrar o app com `override_callback_uri` (se não-SMB) ou apenas o app sub
 
 ```bash
 echo "{WABA_ID}"           | wrangler secret put WHATSAPP_BUSINESS_ACCOUNT_ID
-echo "{PHONE_ID}"          | wrangler secret put WA_PHONE_ID
-echo "{META_ACCESS_TOKEN}" | wrangler secret put WA_ACCESS_TOKEN
+echo "{PHONE_ID}"          | wrangler secret put WHATSAPP_PHONE_NUMBER_ID
+echo "{META_ACCESS_TOKEN}" | wrangler secret put WHATSAPP_ACCESS_TOKEN
 echo "{META_APP_SECRET}"   | wrangler secret put META_APP_SECRET
 echo "{META_ACCESS_TOKEN}" | wrangler secret put META_ACCESS_TOKEN
 
 # ── Secrets para Auto-Resposta WhatsApp (enviar mensagens de saída) ─────────
-# Necessários para: worker.js → auto-resposta após Lead/Purchase
-# WHATSAPP_TOKEN      = mesmo token Meta (Cloud API) — pode reutilizar META_ACCESS_TOKEN
+# Necessários para: index.ts → auto-resposta após Lead/Purchase
+# WHATSAPP_ACCESS_TOKEN      = mesmo token Meta (Cloud API) — pode reutilizar META_ACCESS_TOKEN
 # WHATSAPP_PHONE_NUMBER_ID = mesmo {PHONE_ID} descoberto acima
-echo "{META_ACCESS_TOKEN}" | wrangler secret put WHATSAPP_TOKEN
+echo "{META_ACCESS_TOKEN}" | wrangler secret put WHATSAPP_ACCESS_TOKEN
 echo "{PHONE_ID}"          | wrangler secret put WHATSAPP_PHONE_NUMBER_ID
 
 # Confirmar todos
@@ -510,15 +518,15 @@ Secrets esperados no worker ao final:
 ```
 META_ACCESS_TOKEN
 META_APP_SECRET
-WA_ACCESS_TOKEN
-WA_PHONE_ID
+WHATSAPP_ACCESS_TOKEN
+WHATSAPP_PHONE_NUMBER_ID
 WA_WEBHOOK_VERIFY_TOKEN
 WHATSAPP_BUSINESS_ACCOUNT_ID
-WHATSAPP_TOKEN              ← auto-resposta outbound (mesmo valor de META_ACCESS_TOKEN)
-WHATSAPP_PHONE_NUMBER_ID    ← auto-resposta outbound (mesmo valor de WA_PHONE_ID)
+WHATSAPP_ACCESS_TOKEN              ← auto-resposta outbound (mesmo valor de META_ACCESS_TOKEN)
+WHATSAPP_PHONE_NUMBER_ID    ← auto-resposta outbound (mesmo valor de WHATSAPP_PHONE_NUMBER_ID)
 ```
 
-> **Nota:** `WHATSAPP_TOKEN` e `WHATSAPP_PHONE_NUMBER_ID` são usados pela função de auto-resposta no worker (envio de mensagens de saída para o lead após eventos de conversão). São o mesmo token/phone_id da CTWA — apenas referenciados por nomes distintos no código.
+> **Nota:** `WHATSAPP_ACCESS_TOKEN` e `WHATSAPP_PHONE_NUMBER_ID` são usados pela função de auto-resposta no worker (envio de mensagens de saída para o lead após eventos de conversão). São o mesmo token/phone_id da CTWA — apenas referenciados por nomes distintos no código.
 
 ---
 
@@ -603,13 +611,13 @@ App:     {META_APP_ID} — subscriptions: messages ✅
 
 SECRETS NO WORKER:
   ✅ META_ACCESS_TOKEN
-  ✅ WA_ACCESS_TOKEN
-  ✅ WA_PHONE_ID             → {PHONE_ID}
+  ✅ WHATSAPP_ACCESS_TOKEN
+  ✅ WHATSAPP_PHONE_NUMBER_ID             → {PHONE_ID}
   ✅ WA_WEBHOOK_VERIFY_TOKEN
   ✅ WHATSAPP_BUSINESS_ACCOUNT_ID → {WABA_ID}
   ✅ META_APP_SECRET
-  ✅ WHATSAPP_TOKEN          → mesmo valor de META_ACCESS_TOKEN (auto-resposta)
-  ✅ WHATSAPP_PHONE_NUMBER_ID → mesmo valor de WA_PHONE_ID (auto-resposta)
+  ✅ WHATSAPP_ACCESS_TOKEN          → mesmo valor de META_ACCESS_TOKEN (auto-resposta)
+  ✅ WHATSAPP_PHONE_NUMBER_ID → mesmo valor de WHATSAPP_PHONE_NUMBER_ID (auto-resposta)
 
 TESTE E2E:
   ✅ GET verificação → challenge retornado
@@ -674,7 +682,7 @@ PRÓXIMO PASSO:
 
 | Arquivo | Função |
 |---------|--------|
-| `server-edge-tracker/worker.js` | `processWhatsAppWebhook()` (linha ~943) + rotas `GET/POST /webhook/whatsapp` (linha ~2182) |
+| `server-edge-tracker/index.ts` | `processWhatsAppWebhook()` + rotas `GET/POST /webhook/whatsapp` |
 | `server-edge-tracker/migrate-v6.sql` | Criação da tabela `whatsapp_contacts` com índices |
 | `server-edge-tracker/wrangler.toml` | Configuração do worker + lista de secrets documentados |
 | `docs/whatsapp-ctwa.md` | Documentação técnica completa do módulo CTWA |

package/extracted-skill/tracking-events-generator/agents/youtube-agent.md

@@ -33,7 +33,7 @@ YouTube Ad (TrueView / Bumper / Non-skip)
 
 ### PASSO 0 — Ler Versões Atuais
 
-```javascript
+```typescript
 const apiVersions = await readJSON('contracts/api-versions.json');
 const googleVersions = apiVersions.google;
 
@@ -53,7 +53,7 @@ if (consentModeVersion !== 'v2') {
 
 ### TrueView In-Stream (pulável após 5s)
 - **Evento de billing**: view confirmada após 30s ou clique
-- **Rastrear**: `video_start`, `video_progress_30s`, `video_complete`, clique no CTA
+- **Rastrear**: `video_start`, `video_complete`, clique no CTA
 - **Conversão Google Ads**: `engaged_view` (30s assistidos = 1 conversão de vídeo)
 
 ### Bumper Ads (6s não-puláveis)
@@ -89,39 +89,152 @@ const _gbraid = _urlParams.get('gbraid') || '';  // App campaigns (privacy)
 **ATENÇÃO wbraid/gbraid**: São os click IDs para campanhas YouTube em iOS (pós ATT).
 Nunca hashear — enviar como texto plano para Google Ads API.
 
-### 2. Rastreamento de vídeo YouTube na página
+### 2. Rastreamento de vídeo YouTube na página — YouTube IFrame API
 
-O `behavior-engine.js` já implementa rastreamento de vídeos via YouTube IFrame API.
 Para usar, o iframe deve ter `enablejsapi=1`:
 
 ```html
-<!-- Embed YouTube com JS API habilitada -->
+<!-- Embed YouTube com JS API habilitada (obrigatório) -->
 <iframe
   id="video-tour-imovel"
-  src="https://www.youtube.com/embed/VIDEO_ID?enablejsapi=1"
+  src="https://www.youtube.com/embed/VIDEO_ID?enablejsapi=1&origin=https://seudominio.com.br"
   allow="autoplay"
 ></iframe>
 ```
 
-O BehaviorEngine detecta automaticamente e dispara via `cdpTrack.track()`:
-- `video_milestone` com `percent: 25, 50, 75, 100`
-- Score: +10 (25%), +15 (50%), +25 (75%/100%)
+#### Implementação real do YouTube IFrame API listener
+
+```javascript
+/**
+ * YouTube IFrame API Listener — injeta no behavior-engine.js ou tracking.js
+ * Rastreia: video_start, video_25, video_50, video_75, video_complete
+ * Dispara via cdpTrack.track() para o Worker → GA4 MP + demais plataformas
+ */
+
+// Carregar YouTube IFrame API (uma vez por página)
+(function initYouTubeTracking() {
+  if (window._ytTrackingInitialized) return;
+  window._ytTrackingInitialized = true;
+
+  // Mapa de iframes já trackeados
+  const trackedPlayers = new Map();
+
+  // Injetar API script do YouTube (não carrega 2x se já existe)
+  if (!document.getElementById('youtube-iframe-api')) {
+    const tag = document.createElement('script');
+    tag.id  = 'youtube-iframe-api';
+    tag.src = 'https://www.youtube.com/iframe_api';
+    document.head.appendChild(tag);
+  }
+
+  // Callback global chamado pelo YouTube quando API estiver pronta
+  window.onYouTubeIframeAPIReady = function() {
+    // Auto-detectar todos os iframes com enablejsapi=1
+    document.querySelectorAll('iframe[src*="youtube.com/embed"]').forEach(iframe => {
+      if (trackedPlayers.has(iframe.id)) return;
+
+      const videoTitle = iframe.title || iframe.id || 'YouTube Video';
+
+      const player = new YT.Player(iframe.id, {
+        events: {
+          onStateChange: (event) => handlePlayerStateChange(event, player, videoTitle),
+          onReady:       (event) => handlePlayerReady(event, player, videoTitle)
+        }
+      });
+
+      trackedPlayers.set(iframe.id, { player, milestone: new Set() });
+    });
+  };
+
+  // Se API já carregada (SPA reload), inicializar diretamente
+  if (typeof YT !== 'undefined' && YT.Player) {
+    window.onYouTubeIframeAPIReady();
+  }
+
+  function handlePlayerReady(event, player, videoTitle) {
+    // Iniciar polling de progresso
+    const iframeId = player.getIframe().id;
+    const state = trackedPlayers.get(iframeId);
+
+    const interval = setInterval(() => {
+      if (!player.getDuration) return;
+      const duration = player.getDuration();
+      const current  = player.getCurrentTime();
+      if (duration <= 0) return;
+
+      const percent = Math.floor((current / duration) * 100);
+
+      // Disparar milestones: 25, 50, 75 (100% é coberto pelo estado ENDED)
+      const milestoneEvents = { 25: 'video_25', 50: 'video_50', 75: 'video_75' };
+      [25, 50, 75].forEach(milestone => {
+        if (percent >= milestone && !state.milestone.has(milestone)) {
+          state.milestone.add(milestone);
+
+          window.cdpTrack?.track(milestoneEvents[milestone], {
+            content_name:   videoTitle,
+            video_percent:  milestone,
+            video_duration: Math.round(duration),
+            video_provider: 'youtube',
+            value:          0,
+            currency:       'BRL'
+          });
+        }
+      });
+    }, 1000); // checar a cada 1s
+
+    state.progressInterval = interval;
+  }
+
+  function handlePlayerStateChange(event, player, videoTitle) {
+    const iframeId = player.getIframe().id;
+    const state    = trackedPlayers.get(iframeId);
+
+    // YT.PlayerState: PLAYING=1, PAUSED=2, ENDED=0, BUFFERING=3
+    switch (event.data) {
+      case YT.PlayerState.PLAYING:
+        if (!state.started) {
+          state.started = true;
+          window.cdpTrack?.track('video_start', {
+            content_name:   videoTitle,
+            video_duration: Math.round(player.getDuration() || 0),
+            video_provider: 'youtube'
+          });
+        }
+        break;
+
+      case YT.PlayerState.ENDED:
+        clearInterval(state.progressInterval);
+        window.cdpTrack?.track('video_complete', {
+          content_name:   videoTitle,
+          video_duration: Math.round(player.getDuration() || 0),
+          video_provider: 'youtube'
+        });
+        break;
+    }
+  }
+})();
+```
+
+O listener dispara via `cdpTrack.track()`:
+- `video_start` — primeiros 2s de play
+- `video_25`, `video_50`, `video_75` — marcos de progresso (25/50/75%)
+- `video_complete` — 100% assistido
 
 ### 3. Evento de Lead após assistir vídeo (imóveis)
 
 ```javascript
 // Disparar Lead qualificado quando usuário assiste 75%+ do tour
-document.addEventListener('pb:video_milestone', (e) => {
-  if (e.detail.percent >= 75) {
-    cdpTrack.track('InitiateCheckout', {
-      content_name: 'Tour_Virtual_Empreendimento',
-      value: 0,
-      currency: 'BRL',
-      // Sinaliza alta intenção para Meta + Google
-      meta_intensity: 'high',
-    });
-  }
-});
+// Adicionar dentro do callback de milestoneEvents no IFrame API listener:
+// milestoneEvents[75] → 'video_75' — adicionar lógica abaixo no bloco forEach
+if (milestone === 75) {
+  window.cdpTrack?.track('InitiateCheckout', {
+    content_name: 'Tour_Virtual_Empreendimento',
+    value: 0,
+    currency: 'BRL',
+    // Sinaliza alta intenção para Meta + Google
+    meta_intensity: 'high',
+  });
+}
 ```
 
 ### 4. Consent Mode v2 — OBRIGATÓRIO para YouTube/Google Ads
@@ -140,7 +253,7 @@ cdpTrack.updateConsent({ analytics: true, ads: true });
 
 ---
 
-## 🛠️ IMPLEMENTAÇÃO SERVER — worker.js
+## 🛠️ IMPLEMENTAÇÃO SERVER — index.ts
 
 ### 1. Extrair e persistir Click IDs do YouTube
 
@@ -149,7 +262,7 @@ O `upsertProfile()` já persiste `gclid`, `wbraid`, `gbraid` no D1.
 
 Para verificar persistência correta:
 
-```javascript
+```typescript
 // D1: user_profiles — colunas já existentes
 // gclid   TEXT  — Google Ads standard click ID
 // wbraid  TEXT  — iOS privacy-preserving (YouTube)
@@ -158,12 +271,14 @@ Para verificar persistência correta:
 
 ### 2. GA4 Measurement Protocol — Eventos de Vídeo
 
-```javascript
+```typescript
 // No sendGA4Mp() — adicionar mapeamento de eventos YouTube
 const VIDEO_GA4_MAP = {
-  video_start:     'video_start',
-  video_milestone: 'video_progress',   // GA4 usa video_progress com percent
-  video_complete:  'video_complete',
+  video_start:    'video_start',
+  video_25:       'video_progress',   // GA4 usa video_progress com percent
+  video_50:       'video_progress',
+  video_75:       'video_progress',
+  video_complete: 'video_complete',
 };
 
 // Params obrigatórios para video_progress (GA4)
@@ -178,7 +293,7 @@ const videoParams = {
 
 ### 3. Google Ads Enhanced Conversions — Lead de Vídeo
 
-```javascript
+```typescript
 // Conversão de Lead gerada por campanha YouTube
 // Envia para GA4 MP com user_data para Enhanced Conversions
 const enhancedConversionPayload = {
@@ -211,7 +326,7 @@ const enhancedConversionPayload = {
 Para campanhas Bumper/Non-skip, o usuário converte DEPOIS sem clicar.
 O Worker detecta isso quando um Lead chega SEM gclid mas com histórico de impressão YouTube:
 
-```javascript
+```typescript
 // No upsertProfile() — verificar se perfil tem impressão YouTube recente
 // (requer webhook do Google Ads — avançado, Fase 5)
 // Por ora: registrar ausência de gclid + utm_source=youtube como view-through candidate
@@ -228,9 +343,9 @@ if (!payload.gclid && payload.utmSource === 'youtube') {
 | Evento cdpTrack | Mapeamento GA4 | Mapeamento Google Ads | Quando Disparar |
 |---|---|---|---|
 | `video_start` | `video_start` | — | Primeiros 2s de reprodução |
-| `video_milestone` (25%) | `video_progress` | — | 25% assistido |
-| `video_milestone` (50%) | `video_progress` | `engaged_view` candidate | 50% assistido |
-| `video_milestone` (75%) | `video_progress` | `engaged_view` | 75% assistido — alta intenção |
+| `video_25` | `video_progress` | — | 25% assistido |
+| `video_50` | `video_progress` | `engaged_view` candidate | 50% assistido |
+| `video_75` | `video_progress` | `engaged_view` | 75% assistido — alta intenção |
 | `video_complete` | `video_complete` | `video_view_complete` | 100% assistido |
 | `Lead` (após vídeo) | `generate_lead` | Conversão primária | Formulário submetido |
 | `InitiateCheckout` | `begin_checkout` | Conversão micro | Clique em "Quero saber mais" |
@@ -244,7 +359,7 @@ if (!payload.gclid && payload.utmSource === 'youtube') {
 ```
 FASE 1: AWARENESS (YouTube TrueView 30s)
   ↓ Tour aéreo do empreendimento / lifestyle do bairro
-  ↓ Rastrear: video_milestone 50% + 75% → score alto no LTV
+  ↓ Rastrear: video_50 + video_75 → score alto no LTV
   ↓ Remarketing: quem assistiu 50%+ vira audiência no Google Ads
 
 FASE 2: CONSIDERAÇÃO (YouTube Non-skip 15s + Display)
@@ -303,7 +418,7 @@ const YOUTUBE_AUDIENCES_IMOVEIS = {
 
 ### Customer Match — Exportar leads do D1 para Google Ads
 
-```javascript
+```typescript
 // Endpoint no Worker: GET /export/customer-match
 // Gera CSV criptografado para upload no Google Ads
 
@@ -334,7 +449,7 @@ async function exportCustomerMatchList(env) {
 
 O Intelligence Agent (cron semanal) deve incluir check de YouTube:
 
-```javascript
+```typescript
 // Adicionar ao checkApiVersionsIntelligence():
 // Verificar se wbraid/gbraid estão chegando nos leads
 // (indica que campanhas YouTube iOS estão funcionando)
@@ -390,7 +505,7 @@ if (youtubeMobileLeads.count === 0) {
 
 ## RESPONSABILIDADE
 
-- Gerar eventos de progresso de vídeo (`video_start`, `video_progress_25/50/75/90`, `video_complete`) via GA4
+- Gerar eventos de progresso de vídeo (`video_start`, `video_25`, `video_50`, `video_75`, `video_complete`) via GA4
 - Implementar YouTube IFrame API listener para rastreamento de VSL no browser
 - Garantir `gclid`, `wbraid`, `gbraid` chegando ao Worker (nunca hashear estes campos)
 - Persistir `ga_client_id` no D1 para cruzamento com conversões YouTube Ads
@@ -403,11 +518,11 @@ if (youtubeMobileLeads.count === 0) {
 {
   "arquivos_gerados": {
     "browser": "cdpTrack.js (eventos YouTube + IFrame API listener)",
-    "server": "cloudflare/google-mp.js (já inclui YouTube via GA4)"
+    "server": "modules/dispatch/ga4.ts (já inclui YouTube via GA4)"
   },
   "eventos_implementados": [
     "video_start",
-    "video_progress_25", "video_progress_50", "video_progress_75", "video_progress_90",
+    "video_25", "video_50", "video_75",
     "video_complete",
     "generate_lead",
     "purchase"