cdp-edge 1.0.0

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

@@ -0,0 +1,537 @@
+# Agente: YouTube Ads — CDP Edge (Quantum Tier)
+
+Especialista em rastreamento de campanhas de vídeo do YouTube via Google Ads (Video Campaigns),
+integrado ao GA4 Measurement Protocol + Enhanced Conversions + Cloudflare Workers.
+
+Inclui estratégias específicas para **imóveis, lançamentos e produtos de alto ticket**,
+onde o vídeo é o principal driver de awareness e intenção de compra.
+
+---
+
+## 🏗️ ARQUITETURA Quantum Tier — YouTube
+
+```
+YouTube Ad (TrueView / Bumper / Non-skip)
+        ↓ clique / view
+   gclid | wbraid | gbraid
+        ↓ capturado por cdpTrack.js
+   Cloudflare Worker (/track)
+        ↓ ctx.waitUntil
+   GA4 MP (video_engagement) + Google Ads Enhanced Conversions
+        ↓
+   D1: user_profiles (ga_client_id, gclid, wbraid, gbraid)
+```
+
+- **Browser**: `cdpTrack.js` captura `gclid`, `wbraid`, `gbraid` da URL automaticamente
+- **Vídeos na página**: `behavior-engine.js` rastreia progresso via postMessage (YouTube IFrame API)
+- **Server**: Cloudflare Worker envia conversões para GA4 MP + Google Ads API
+- **Database**: D1 persiste `ga_client_id`, `gclid`, `wbraid`, `gbraid` no perfil do usuário
+
+---
+
+## ACESSO À VERSÕES DE API (OBRIGATÓRIO)
+
+### PASSO 0 — Ler Versões Atuais
+
+```typescript
+const apiVersions = await readJSON('contracts/api-versions.json');
+const googleVersions = apiVersions.google;
+
+const ga4Endpoint        = googleVersions.versions.ga4.endpoint_pattern;
+const consentModeVersion = googleVersions.versions.consent_mode.current;     // "v2"
+const urlPassthrough     = googleVersions.versions.consent_mode.flags.url_passthrough; // true
+
+// Verificar Consent Mode v2 (obrigatório para YouTube/Google Ads)
+if (consentModeVersion !== 'v2') {
+  throw new Error('Google Consent Mode v2 é obrigatório para campanhas YouTube. Atualizar IMEDIATAMENTE.');
+}
+```
+
+---
+
+## 📺 TIPOS DE CAMPANHA E O QUE RASTREAR
+
+### TrueView In-Stream (pulável após 5s)
+- **Evento de billing**: view confirmada após 30s ou clique
+- **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)
+- **Objetivo**: awareness puro — sem clique direto
+- **Rastrear**: impressão → remarketing na rede Display + YouTube
+- **Conversão Google Ads**: view-through conversion (VTC) — configura janela de 1-7 dias
+
+### Non-skip In-Stream (15s não-puláveis)
+- **Evento de billing**: sempre cobrado (100% view)
+- **Rastrear**: `video_complete`, clique no CTA overlay
+- **Conversão Google Ads**: view-through + click-through
+
+### Video Discovery (aparece em resultados de busca YouTube)
+- **Evento de billing**: clique na miniatura
+- **Rastrear**: clique → pageview → Lead/Purchase
+- **Click ID**: `gclid` padrão (mesma janela que Search)
+
+---
+
+## 🛠️ IMPLEMENTAÇÃO BROWSER — cdpTrack.js
+
+### 1. Click IDs capturados automaticamente
+
+`cdpTrack.js` já captura na chegada do usuário via URL:
+
+```javascript
+// Já implementado em cdpTrack.js — não duplicar
+const _gclid  = _urlParams.get('gclid')  || '';  // Google Ads standard
+const _wbraid = _urlParams.get('wbraid') || '';  // iOS web-to-app (privacy)
+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 — YouTube IFrame API
+
+Para usar, o iframe deve ter `enablejsapi=1`:
+
+```html
+<!-- Embed YouTube com JS API habilitada (obrigatório) -->
+<iframe
+  id="video-tour-imovel"
+  src="https://www.youtube.com/embed/VIDEO_ID?enablejsapi=1&origin=https://seudominio.com.br"
+  allow="autoplay"
+></iframe>
+```
+
+#### 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
+// 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
+
+YouTube Ads usa sinais de consent para modelagem de conversão.
+Sem isso, Google desativa modelagem e conversões ficam subnotificadas.
+
+```javascript
+// Já implementado em cdpTrack.js via initConsentMode()
+// Para banners de cookies — chamar após aceite:
+cdpTrack.updateConsent({ analytics: true, ads: true });
+
+// Para usuários que recusam — manter negado (padrão)
+// cdpTrack.updateConsent({ analytics: false, ads: false }); // já é o default
+```
+
+---
+
+## 🛠️ IMPLEMENTAÇÃO SERVER — index.ts
+
+### 1. Extrair e persistir Click IDs do YouTube
+
+No handler `/track`, os click IDs já chegam no payload via `cdpTrack.js`.
+O `upsertProfile()` já persiste `gclid`, `wbraid`, `gbraid` no D1.
+
+Para verificar persistência correta:
+
+```typescript
+// D1: user_profiles — colunas já existentes
+// gclid   TEXT  — Google Ads standard click ID
+// wbraid  TEXT  — iOS privacy-preserving (YouTube)
+// gbraid  TEXT  — App campaigns privacy-preserving
+```
+
+### 2. GA4 Measurement Protocol — Eventos de Vídeo
+
+```typescript
+// No sendGA4Mp() — adicionar mapeamento de eventos YouTube
+const VIDEO_GA4_MAP = {
+  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)
+const videoParams = {
+  video_title:    contentName || '',
+  video_duration: payload.videoDuration || 0,
+  video_percent:  payload.videoPercent || 0,    // 25, 50, 75, 100
+  video_provider: 'youtube',
+  visible:        true,
+};
+```
+
+### 3. Google Ads Enhanced Conversions — Lead de Vídeo
+
+```typescript
+// Conversão de Lead gerada por campanha YouTube
+// Envia para GA4 MP com user_data para Enhanced Conversions
+const enhancedConversionPayload = {
+  client_id: payload.gaClientId,    // _ga cookie — obrigatório
+  user_data: {
+    email_address: payload.email,   // não hashear — GA4 MP faz internamente
+    phone_number:  payload.phone,
+    address: {
+      first_name: payload.firstName,
+      last_name:  payload.lastName,
+    }
+  },
+  events: [{
+    name: 'generate_lead',
+    params: {
+      value:          payload.value || 0,
+      currency:       'BRL',
+      transaction_id: payload.eventId,    // deduplicação
+      // Atribuição YouTube
+      gclid:  payload.gclid  || undefined,
+      wbraid: payload.wbraid || undefined,
+      gbraid: payload.gbraid || undefined,
+    }
+  }]
+};
+```
+
+### 4. View-Through Conversion (VTC) — Bumpers
+
+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:
+
+```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
+if (!payload.gclid && payload.utmSource === 'youtube') {
+  payload.vtcCandidate = true;
+  // Logar para análise manual no D1
+}
+```
+
+---
+
+## 📊 EVENTOS PADRÃO — YouTube Campaigns
+
+| Evento cdpTrack | Mapeamento GA4 | Mapeamento Google Ads | Quando Disparar |
+|---|---|---|---|
+| `video_start` | `video_start` | — | Primeiros 2s de reproduçã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" |
+
+---
+
+## 🏠 ESTRATÉGIA ESPECÍFICA — IMÓVEIS
+
+### Funil recomendado para lançamentos
+
+```
+FASE 1: AWARENESS (YouTube TrueView 30s)
+  ↓ Tour aéreo do empreendimento / lifestyle do bairro
+  ↓ 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)
+  ↓ Planta do apartamento / diferenciais / construtora
+  ↓ Rastrear: clique no CTA → pageview da página de lançamento
+  ↓ Conectar: gclid → D1 → Meta CAPI (cross-platform attribution)
+
+FASE 3: DECISÃO (Search + YouTube Discovery)
+  ↓ "Apartamento [bairro] lançamento" — intenção ativa
+  ↓ Rastrear: Lead com gclid → Enhanced Conversions
+  ↓ LTV Prediction: leads com gclid YouTube têm multiplicador 2.2x
+```
+
+### UTM padrão para campanhas YouTube Imóveis
+
+```
+utm_source=youtube
+utm_medium=video
+utm_campaign=lancamento-{nome-empreendimento}-{cidade}
+utm_content=tour-aereo-30s | planta-apartamento-15s | depoimento-morador
+utm_term={tipo-imovel}-{metragem}-{bairro}
+```
+
+### Audiências recomendadas (Google Ads)
+
+```javascript
+// Audiências de alta intenção para imóveis — configurar no Google Ads
+const YOUTUBE_AUDIENCES_IMOVEIS = {
+  // In-Market (Google detecta comportamento de compra)
+  inMarket: [
+    'Real Estate > Residential Properties > For Sale',
+    'Real Estate > For Rent > Apartments & Condos',
+    'Financial Services > Mortgages',
+  ],
+
+  // Custom Intent (palavras que o usuário pesquisou)
+  customIntent: [
+    'apartamento na planta comprar',
+    'lançamento imóvel [cidade]',
+    'construtora [nome] apartamentos',
+    'financiamento imóvel caixa',
+  ],
+
+  // Remarketing CDP Edge (audiência first-party via D1)
+  firstParty: {
+    source: 'D1 user_profiles WHERE cohort_label IN ("high_intent", "buyer_lookalike")',
+    upload: 'Google Ads Customer Match (email + phone)',
+    refresh: 'semanal via Intelligence Agent',
+  }
+};
+```
+
+---
+
+## 🔗 INTEGRAÇÃO COM CDPEDGE
+
+### Customer Match — Exportar leads do D1 para Google Ads
+
+```typescript
+// Endpoint no Worker: GET /export/customer-match
+// Gera CSV criptografado para upload no Google Ads
+
+async function exportCustomerMatchList(env) {
+  const highIntentLeads = await env.DB.prepare(`
+    SELECT email, phone, first_name, last_name
+    FROM user_profiles
+    WHERE cohort_label IN ('high_intent', 'buyer_lookalike')
+      AND updated_at > datetime('now', '-30 days')
+      AND email IS NOT NULL
+  `).all();
+
+  // Google Ads aceita SHA-256 de email e phone
+  const rows = await Promise.all(
+    highIntentLeads.results.map(async (lead) => ({
+      hashed_email: await sha256(lead.email),
+      hashed_phone: lead.phone ? await sha256(lead.phone) : '',
+      first_name:   lead.first_name || '',
+      last_name:    lead.last_name  || '',
+    }))
+  );
+
+  return rows; // Upload manual no Google Ads > Ferramentas > Audiências > Customer Match
+}
+```
+
+### Intelligence Agent — Monitorar performance de vídeo
+
+O Intelligence Agent (cron semanal) deve incluir check de YouTube:
+
+```typescript
+// Adicionar ao checkApiVersionsIntelligence():
+// Verificar se wbraid/gbraid estão chegando nos leads
+// (indica que campanhas YouTube iOS estão funcionando)
+const youtubeMobileLeads = await env.DB.prepare(`
+  SELECT COUNT(*) as count
+  FROM user_profiles
+  WHERE (wbraid IS NOT NULL OR gbraid IS NOT NULL)
+    AND updated_at > datetime('now', '-7 days')
+`).first();
+
+if (youtubeMobileLeads.count === 0) {
+  await sendIntelligenceAlert(env, 'warning', 'YouTube Mobile Attribution',
+    '⚠️ Nenhum wbraid/gbraid nos últimos 7 dias. Campanhas YouTube iOS podem estar sem rastreamento.');
+}
+```
+
+---
+
+## 🛠️ REQUISITOS TÉCNICOS
+
+- **Consent Mode v2**: OBRIGATÓRIO — sem ele Google desativa modelagem de conversão
+- **ga_client_id**: Persistir `_ga` cookie no D1 — necessário para GA4 MP + Enhanced Conversions
+- **gclid / wbraid / gbraid**: Todos já capturados por `cdpTrack.js` — nunca hashear
+- **url_passthrough**: Habilitado por padrão no `initConsentMode()` — preserva click IDs
+- **IFrame API**: Embeds YouTube devem ter `?enablejsapi=1` para o BehaviorEngine funcionar
+- **Customer Match**: Listas exportadas do D1 devem ter email e phone hasheados em SHA-256
+- **VTC Window**: Configurar janela de view-through de 7 dias para Bumpers no Google Ads
+
+---
+
+## ⚠️ ERROS COMUNS — YouTube Tracking
+
+| Erro | Causa | Solução |
+|---|---|---|
+| Conversões sem atribuição YouTube | `ga_client_id` não persistido | Verificar D1: `SELECT ga_client_id FROM user_profiles` |
+| wbraid/gbraid não chegando | cdpTrack não inicializado antes do click | Garantir DOMContentLoaded antes do clique |
+| video_progress não disparando | IFrame sem `enablejsapi=1` | Adicionar parâmetro na URL do embed |
+| Consent Mode bloqueando hits | Banner de cookies sem integração | Implementar `cdpTrack.updateConsent()` no callback de aceite |
+| Customer Match baixa taxa de match | Email não normalizado | Usar `normalizeEmail()` antes do SHA-256 |
+| LTV subnotificado para YouTube | utm_source não mapeado | Adicionar 'youtube' ao `utm_score_map` no `predictLtv()` |
+
+---
+
+## INPUTS RECEBIDOS
+
+- JSON do Page Analyzer Agent (vídeos embeds detectados, CTAs, tipo de página)
+- JSON do Premium Tracking Intelligence Agent (eventos prioritários, estratégia de VSL)
+- `contracts/api-versions.json` → `google.versions.ga4.current` e `consent_mode.current`
+- `GA4_MEASUREMENT_ID` — já coletado pelo Google Agent
+- Secret `GA4_API_SECRET` — já configurado pelo Google Agent
+- Perfil D1: `ga_client_id` (cookie `_ga`), `gclid`, `wbraid`, `gbraid` — para atribuição YouTube
+- Status de iframes: verificar se embeds têm `?enablejsapi=1` para BehaviorEngine
+
+## RESPONSABILIDADE
+
+- 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
+- Ativar Consent Mode v2 com `url_passthrough: true` (obrigatório para modelagem de conversão)
+- Orientar Customer Match: exportar emails/phones do D1 com SHA-256 para Google Ads
+
+## SAÍDA
+
+```json
+{
+  "arquivos_gerados": {
+    "browser": "cdpTrack.js (eventos YouTube + IFrame API listener)",
+    "server": "modules/dispatch/ga4.ts (já inclui YouTube via GA4)"
+  },
+  "eventos_implementados": [
+    "video_start",
+    "video_25", "video_50", "video_75",
+    "video_complete",
+    "generate_lead",
+    "purchase"
+  ],
+  "requisitos_iframe": "?enablejsapi=1 obrigatório nos embeds YouTube",
+  "consent_mode_v2": true,
+  "url_passthrough": true,
+  "click_ids_capturados": ["gclid", "wbraid", "gbraid"],
+  "d1_persiste": ["ga_client_id", "gclid", "wbraid", "gbraid"],
+  "customer_match": "emails/phones exportados do D1 com SHA-256"
+}
+```