@saulwade/swl-ses 2.4.2 → 2.5.1

package/habilidades/paid-media-tracking/recursos/auditoria-tracking.md

@@ -1,220 +0,0 @@
-# Auditoría técnica de cuentas Google Ads
-
-## Checklist técnico de auditoría
-
-Una auditoría técnica verifica que la infraestructura de medición está
-correctamente configurada — no evalúa la estrategia de campañas.
-
-### Conversiones
-
-- [ ] **Conversiones primarias configuradas**: al menos una acción de conversión
-  marcada como "Primaria" en la cuenta. Las conversiones secundarias no se usan
-  en las estrategias de puja automática.
-- [ ] **Enhanced Conversions activadas**: en Configuración de conversiones,
-  "Enhanced conversions for web" debe estar habilitado con hash SHA-256.
-- [ ] **Auto-tagging habilitado**: en Configuración de la cuenta, permite que
-  Google Ads agregue `gclid` a las URLs de destino para importación a GA4.
-- [ ] **Sin conversiones duplicadas**: verificar que el mismo evento de compra
-  no esté configurado dos veces (una en GA4-importada y otra en etiqueta directa).
-- [ ] **Ventana de conversión correcta**: campañas de búsqueda usan 30 días;
-  campañas de display o video pueden requerir ventanas más largas (90 días).
-
-### Audiencias y remarketing
-
-- [ ] **Etiqueta de remarketing activa**: Google Ads Tag o GA4 Audience deben
-  estar recibiendo datos (verificar en Audience Manager > Fuentes de audiencia).
-- [ ] **Audiencias de remarketing creadas**: al menos "Todos los visitantes",
-  "Visitantes de producto" y "Compradores anteriores" para campañas RLSA.
-- [ ] **Customer Match habilitado**: si se usa lista de clientes, la cuenta debe
-  tener historial suficiente y cumplimiento de políticas.
-
-### Shopping (si aplica)
-
-- [ ] **Feed de productos aprobado** en Merchant Center: sin errores de
-  disponibilidad, precio o imagen. Los items rechazados no aparecen en anuncios.
-- [ ] **Vinculación Merchant Center — Google Ads**: confirmada en ambas cuentas.
-- [ ] **Etiquetas personalizadas configuradas**: para segmentación por margen,
-  temporada o prioridad de inventario.
-
-### Estructura técnica de la cuenta
-
-- [ ] **Naming convention consistente**: campañas, ad groups y keywords siguen
-  una nomenclatura que permite filtrar y reportar programáticamente.
-- [ ] **UTM parameters en URLs finales**: `utm_source=google&utm_medium=cpc&utm_campaign={campaignid}`
-  para atribución correcta en GA4 sin depender solo del auto-tagging.
-
----
-
-## Métricas de calidad de cuenta
-
-Estas métricas indican la salud técnica de la implementación, no el
-desempeño de negocio:
-
-| Métrica | Objetivo | Señal de problema |
-|---------|----------|------------------|
-| Quality Score promedio (búsqueda) | ≥ 7/10 | < 5 indica relevancia baja o landing page deficiente |
-| Impression Share de marca | ≥ 85% | < 70% indica competencia capturando tráfico de marca |
-| Invalid click rate | < 2% | > 5% indica fraude de clics o tráfico de baja calidad |
-| Discrepancia GA4 vs Google Ads | < 15% | > 15% indica problema de tracking o atribución |
-| Conversiones con valor cero | 0% | Cualquier conversión primaria sin valor = ROAS incalculable |
-
-### Query para Quality Score promedio
-
-```python
-def obtener_quality_score_promedio(customer_id: str) -> dict:
-    """Obtiene Quality Score promedio de keywords activas."""
-    ga_service = client.get_service("GoogleAdsService")
-
-    query = """
-        SELECT
-            ad_group_criterion.keyword.text,
-            ad_group_criterion.quality_info.quality_score,
-            ad_group_criterion.quality_info.creative_quality_score,
-            ad_group_criterion.quality_info.post_click_quality_score,
-            ad_group_criterion.quality_info.search_predicted_ctr,
-            metrics.impressions
-        FROM keyword_view
-        WHERE campaign.status = 'ENABLED'
-            AND ad_group.status = 'ENABLED'
-            AND ad_group_criterion.status = 'ENABLED'
-            AND ad_group_criterion.quality_info.quality_score > 0
-            AND segments.date DURING LAST_30_DAYS
-    """
-
-    response = ga_service.search(customer_id=customer_id, query=query)
-
-    scores = []
-    impresiones_total = 0
-    suma_ponderada = 0
-
-    for row in response:
-        qs = row.ad_group_criterion.quality_info.quality_score
-        imp = row.metrics.impressions
-        scores.append(qs)
-        suma_ponderada += qs * imp
-        impresiones_total += imp
-
-    if not scores:
-        return {"error": "sin_keywords_con_quality_score"}
-
-    return {
-        "promedio_simple": round(sum(scores) / len(scores), 1),
-        "promedio_ponderado_impresiones": round(
-            suma_ponderada / impresiones_total, 1
-        ) if impresiones_total > 0 else 0,
-        "total_keywords": len(scores),
-        "distribucion": {
-            "excelente_8_10": sum(1 for s in scores if s >= 8),
-            "bueno_6_7": sum(1 for s in scores if 6 <= s <= 7),
-            "bajo_1_5": sum(1 for s in scores if s <= 5),
-        },
-    }
-```
-
----
-
-## Herramientas de diagnóstico
-
-### Google Tag Assistant
-
-Extensión de Chrome para verificar que la etiqueta de Google Ads está
-disparando correctamente en el sitio:
-
-1. Activar grabación en la página objetivo
-2. Completar el flujo de conversión (compra, registro, etc.)
-3. Verificar que el evento aparece en el historial con los parámetros correctos
-4. Confirmar que no hay errores de "Tag not found" o "Tag fired multiple times"
-
-### Google Ads Diagnostics Tool
-
-En la consola de Google Ads: Herramientas > Diagnóstico y vista previa
-de anuncios. Permite verificar por qué un anuncio no aparece para una
-búsqueda específica (presupuesto agotado, keyword pausada, policy violation).
-
----
-
-## Reporte automático de auditoría con Python
-
-```python
-import json
-from dataclasses import dataclass, field
-
-@dataclass
-class ResultadoAuditoria:
-    customer_id: str
-    quality_score: dict = field(default_factory=dict)
-    discrepancia_conversiones: dict = field(default_factory=dict)
-    candidatos_negative: list = field(default_factory=list)
-    alertas: list[str] = field(default_factory=list)
-
-def ejecutar_auditoria_completa(
-    customer_id: str,
-    ga4_conversiones: float,
-    campaign_ids: list[str],
-) -> ResultadoAuditoria:
-    """
-    Ejecuta auditoría técnica completa de una cuenta Google Ads.
-
-    Retorna un ResultadoAuditoria con métricas de calidad,
-    discrepancias de conversiones y candidatos a negative keywords.
-    """
-    resultado = ResultadoAuditoria(customer_id=customer_id)
-
-    # 1. Quality Score
-    resultado.quality_score = obtener_quality_score_promedio(customer_id)
-    qs_prom = resultado.quality_score.get("promedio_simple", 0)
-    if qs_prom < 7:
-        resultado.alertas.append(
-            f"Quality Score promedio bajo: {qs_prom}/10 (objetivo ≥ 7)"
-        )
-
-    # 2. Rendimiento de campañas y discrepancia de conversiones
-    campanas = obtener_rendimiento_campanas(customer_id)
-    google_ads_conv = sum(c["conversiones"] for c in campanas)
-    resultado.discrepancia_conversiones = detectar_discrepancia_conversiones(
-        google_ads_conv, ga4_conversiones
-    )  # Nota: esta función es async en SKILL.md, adaptar según contexto
-
-    if resultado.discrepancia_conversiones.get("estado") != "ok":
-        pct = resultado.discrepancia_conversiones.get("discrepancia_porcentual", 0)
-        resultado.alertas.append(
-            f"Discrepancia de conversiones: {pct}% (umbral: 15%)"
-        )
-
-    # 3. Search terms con desperdicio
-    analisis = analizar_search_terms(customer_id, campaign_ids)
-    resultado.candidatos_negative = analisis["candidatos_negative"][:10]
-    if resultado.candidatos_negative:
-        total_desperdicio = sum(
-            t["costo_desperdiciado"] for t in resultado.candidatos_negative
-        )
-        resultado.alertas.append(
-            f"{len(resultado.candidatos_negative)} términos candidatos a negative, "
-            f"costo desperdiciado estimado: ${total_desperdicio:,.2f}"
-        )
-
-    return resultado
-
-
-def exportar_reporte_json(resultado: ResultadoAuditoria, ruta: str) -> None:
-    """Exporta el resultado de la auditoría como JSON."""
-    import dataclasses
-    with open(ruta, "w", encoding="utf-8") as f:
-        json.dump(dataclasses.asdict(resultado), f, ensure_ascii=False, indent=2)
-```
-
-### Ejemplo de uso
-
-```python
-resultado = ejecutar_auditoria_completa(
-    customer_id="1234567890",
-    ga4_conversiones=142.0,
-    campaign_ids=["111222333", "444555666"],
-)
-
-print(f"Alertas encontradas: {len(resultado.alertas)}")
-for alerta in resultado.alertas:
-    print(f"  - {alerta}")
-
-exportar_reporte_json(resultado, "auditoria_2026_04.json")
-```

package/habilidades/paid-media-tracking/recursos/google-ads-api.md

@@ -1,215 +0,0 @@
-# Google Ads API — Referencia técnica
-
-## Autenticación
-
-### Tipos de credenciales
-
-| Tipo | Cuándo usar | Configuración requerida |
-|------|-------------|------------------------|
-| OAuth2 con refresh token | Acceso en nombre de un usuario | `client_id`, `client_secret`, `refresh_token` |
-| Service Account | Procesos server-side sin interacción humana | Archivo JSON de service account + acceso delegado en MCC |
-| Developer Token | Obligatorio en todos los casos | Aprobado por Google en la cuenta MCC principal |
-
-### Niveles del Developer Token
-
-| Nivel | Quota diaria | Cuentas accesibles |
-|-------|-------------|-------------------|
-| Test | 15,000 ops/día | Solo cuentas de prueba |
-| Basic | 1,000 ops/día | Todas las cuentas vinculadas al MCC |
-| Standard | 10,000 ops/día | Requiere solicitud y aprobación de Google |
-
-En producción con reportes diarios, **Standard es necesario** si se tienen
-más de 50 cuentas o consultas de más de 30 días de datos.
-
-### Configuración con diccionario Python
-
-```python
-from google.ads.googleads.client import GoogleAdsClient
-
-config = {
-    "developer_token": settings.GOOGLE_ADS_DEVELOPER_TOKEN,
-    "client_id": settings.GOOGLE_ADS_CLIENT_ID,
-    "client_secret": settings.GOOGLE_ADS_CLIENT_SECRET,
-    "refresh_token": settings.GOOGLE_ADS_REFRESH_TOKEN,
-    "login_customer_id": settings.GOOGLE_ADS_MCC_ID,  # ID del MCC, sin guiones
-    "use_proto_plus": True,  # Objetos Python nativos en lugar de protobuf raw
-}
-
-client = GoogleAdsClient.load_from_dict(config)
-```
-
-### Configuración con archivo YAML (alternativa)
-
-```yaml
-# google-ads.yaml (NO subir a repositorio)
-developer_token: "Tu_Developer_Token"
-client_id: "client_id.apps.googleusercontent.com"
-client_secret: "client_secret"
-refresh_token: "1//0g..."
-login_customer_id: "1234567890"
-use_proto_plus: true
-```
-
-```python
-client = GoogleAdsClient.load_from_storage("google-ads.yaml")
-```
-
----
-
-## GAQL — Google Ads Query Language
-
-### Estructura básica
-
-```sql
-SELECT campo1, campo2, metrica1
-FROM recurso_principal
-WHERE condicion1 AND condicion2
-ORDER BY metrica1 DESC
-LIMIT 100
-```
-
-### Recursos principales
-
-| Recurso | Qué contiene |
-|---------|-------------|
-| `campaign` | Campañas: nombre, status, tipo, presupuesto |
-| `ad_group` | Grupos de anuncios dentro de campañas |
-| `ad_group_ad` | Anuncios individuales con sus métricas |
-| `keyword_view` | Keywords configuradas con Quality Score |
-| `search_term_view` | Términos exactos que activaron anuncios |
-| `geographic_view` | Rendimiento por ubicación geográfica |
-| `audience_view` | Rendimiento por audiencia configurada |
-| `shopping_performance_view` | Rendimiento de campañas Shopping |
-
-### Segmentos comunes
-
-Los segmentos dividen las métricas por dimensión. No todos son compatibles
-con todos los recursos — la API retorna error si se combina incorrectamente.
-
-```sql
--- Segmentar por fecha
-SELECT campaign.name, metrics.clicks, segments.date
-FROM campaign
-WHERE segments.date DURING LAST_30_DAYS
-
--- Segmentar por dispositivo
-SELECT campaign.name, metrics.clicks, segments.device
-FROM campaign
-WHERE segments.date DURING LAST_7_DAYS
-
--- Rangos de fecha explícitos
-WHERE segments.date BETWEEN '2026-01-01' AND '2026-03-31'
-```
-
-### Períodos predefinidos útiles
-
-| Constante GAQL | Equivalente |
-|----------------|-------------|
-| `LAST_7_DAYS` | Últimos 7 días |
-| `LAST_30_DAYS` | Últimos 30 días |
-| `LAST_MONTH` | Mes calendario anterior completo |
-| `THIS_MONTH` | Mes calendario actual hasta hoy |
-| `LAST_YEAR` | Año anterior completo |
-
-### Filtros de status importantes
-
-```sql
--- Solo campañas activas (ENABLED)
-WHERE campaign.status = 'ENABLED'
-
--- Campañas activas y pausadas (excluye eliminadas)
-WHERE campaign.status IN ('ENABLED', 'PAUSED')
-
--- Search terms de campañas activas únicamente
-WHERE campaign.status = 'ENABLED'
-    AND ad_group.status = 'ENABLED'
-```
-
----
-
-## Paginación y streaming
-
-### `search` vs `search_stream`
-
-| Método | Cuándo usar | Comportamiento |
-|--------|-------------|----------------|
-| `search` | Resultados esperados < 10,000 filas | Devuelve páginas de 10,000 resultados |
-| `search_stream` | Resultados esperados > 10,000 filas | Stream de chunks, más eficiente en memoria |
-
-```python
-# Para datasets grandes (search terms de cuentas con alto volumen)
-stream = ga_service.search_stream(customer_id=customer_id, query=query)
-resultados = []
-for batch in stream:
-    for row in batch.results:
-        resultados.append(procesar_fila(row))
-```
-
----
-
-## Batch operations con `MutateGoogleAdsRequest`
-
-Para operaciones de escritura (agregar negative keywords, pausar campañas),
-agrupar en un solo request reduce el consumo de quota.
-
-```python
-from google.ads.googleads.client import GoogleAdsClient
-
-def agregar_negative_keywords(
-    customer_id: str,
-    campaign_id: str,
-    terminos: list[str],
-) -> None:
-    """Agrega lista de negative keywords a una campaña en un solo request."""
-    campaign_criterion_service = client.get_service("CampaignCriterionService")
-
-    operaciones = []
-    for termino in terminos:
-        operacion = client.get_type("CampaignCriterionOperation")
-        criterio = operacion.create
-        criterio.campaign = f"customers/{customer_id}/campaigns/{campaign_id}"
-        criterio.negative = True
-        criterio.keyword.text = termino
-        criterio.keyword.match_type = client.enums.KeywordMatchTypeEnum.BROAD
-        operaciones.append(operacion)
-
-    campaign_criterion_service.mutate_campaign_criteria(
-        customer_id=customer_id,
-        operations=operaciones,
-    )
-```
-
----
-
-## Errores comunes y solución
-
-| Error | Causa probable | Solución |
-|-------|----------------|----------|
-| `PERMISSION_DENIED` | `login_customer_id` incorrecto o sin acceso | Verificar que el MCC tiene acceso a la sub-cuenta |
-| `QUOTA_ERROR` | Quota diaria agotada | Implementar caché, solicitar nivel Standard |
-| `NOT_FOUND` | `customer_id` o `campaign_id` no existe | Verificar IDs sin guiones |
-| `INVALID_CUSTOMER_ID` | `customer_id` con guiones | `customer_id.replace("-", "")` |
-| `AUTHENTICATION_ERROR` | `refresh_token` vencido o revocado | Regenerar refresh token en Google OAuth Playground |
-| `RESOURCE_EXHAUSTED` | Demasiados requests en poco tiempo | Implementar retry con backoff exponencial |
-
-### Retry con backoff exponencial
-
-```python
-import time
-from google.ads.googleads.errors import GoogleAdsException
-
-def ejecutar_con_retry(fn, max_reintentos: int = 3):
-    """Ejecuta una llamada a la API con retry y backoff exponencial."""
-    for intento in range(max_reintentos):
-        try:
-            return fn()
-        except GoogleAdsException as ex:
-            es_quota = any(
-                "QUOTA" in str(e.error_code) for e in ex.failure.errors
-            )
-            if es_quota and intento < max_reintentos - 1:
-                espera = 2 ** intento  # 1s, 2s, 4s
-                time.sleep(espera)
-                continue
-            raise
-```

package/habilidades/tracking-measurement/SKILL.md

@@ -1,239 +0,0 @@
----
-name: tracking-measurement
-description: >
-  Implementación técnica de sistemas de medición web: GTM (dataLayer, triggers,
-  variables, tags), GA4 (eventos, e-commerce, dimensiones personalizadas), Meta
-  CAPI server-side con deduplicación, Enhanced Conversions y Consent Mode v2.
-  Cargar cuando se implemente conversion tracking, se configure GTM, se integre
-  GA4 o Meta Pixel, se construya un endpoint server-side para CAPI, o se
-  implemente cumplimiento de privacidad GDPR/CCPA en tracking.
-version: "1.0.0"
-herramientasPermitidas: [Read, Write]
-evolvable: true  # default para skill estandar
-exclusiones:
-  - "No cargar para análisis de datos de conversiones ya capturados (reportes de ROAS, atribución multi-touch) — para análisis de datos de paid media cargar `paid-media-tracking`."
-  - "No cargar para instrumentación de aplicaciones backend con OpenTelemetry o métricas de negocio en Prometheus — para observabilidad de sistemas cargar `monitoring-alertas`."
-  - "No cargar para implementar sistemas de analytics propietarios o data warehouses (BigQuery, Snowflake) sin componente de tracking web — para pipelines de datos cargar el skill de cloud correspondiente."
-  - "No cargar para scraping o extracción de datos de plataformas publicitarias externas — para acceso a APIs de Google Ads o Meta Business cargar `paid-media-tracking`."
----
-# tracking-measurement — Sistemas de medición web
-
-## Cuándo NO cargar
-
-- La tarea es analizar datos de conversiones ya capturados (ROAS, atribución): cargar `paid-media-tracking`.
-- La tarea es instrumentación de backend con OpenTelemetry o Prometheus: cargar `monitoring-alertas`.
-- La tarea es construir un data warehouse o pipeline de datos sin componente de tracking web: cargar el skill de cloud correspondiente.
-- La tarea es acceder a APIs de Google Ads o Meta Business para reportes: cargar `paid-media-tracking`.
-
-## Cuándo cargar este skill
-
-- Configurar GTM: workspace, triggers, variables, tags
-- Implementar eventos GA4 (e-commerce, custom dimensions, Measurement Protocol)
-- Construir endpoint server-side para Meta Conversions API (CAPI)
-- Implementar Enhanced Conversions de Google Ads
-- Añadir Consent Mode v2 (GDPR/CCPA) a una aplicación web
-- Integrar CMP (Cookiebot, OneTrust, Usercentrics) con GTM
-- Depurar discrepancias entre datos de plataformas y datos reales
-
-## Arquitectura de medición moderna
-
-```
-Navegador                      Servidor                    Plataformas
-─────────                      ────────                    ──────────
-GTM Container                  Server-side GTM             Google Analytics 4
-  └─ dataLayer.push()    ──►   (Cloud Run / App Engine)   Meta Ads Manager
-  └─ GA4 tag             ──►   └─ GA4 Measurement API     Google Ads
-  └─ Meta Pixel tag      ──►   └─ Meta CAPI               Microsoft Ads
-  └─ Consent Mode        ──►   └─ Hash PII antes de enviar
-```
-
-El tracking browser-only pierde 40-60% de eventos en Safari/iOS por ITP.
-El server-side tagging recupera esos eventos usando datos first-party.
-
-## Reglas obligatorias
-
-### Regla 1 — Limpiar ecommerce antes de cada evento
-
-Siempre ejecutar `dataLayer.push({ ecommerce: null })` antes de cualquier
-evento e-commerce. Sin esto, GTM mezcla datos de eventos anteriores.
-
-**Verificación**: En Tag Assistant, cada evento e-commerce debe tener
-`ecommerce: null` inmediatamente antes en el historial del dataLayer.
-
-### Regla 2 — Hashear PII antes de enviar a plataformas externas
-
-Email y teléfono NUNCA se envían en texto plano. Siempre SHA-256 normalizado:
-email en minúsculas sin espacios, teléfono en formato E.164.
-
-```python
-import hashlib
-
-def hash_pii(valor: str) -> str:
-    """Normaliza y hashea PII para plataformas externas (SHA-256)."""
-    return hashlib.sha256(valor.strip().lower().encode()).hexdigest()
-```
-
-**Verificación**: En los payloads de red (DevTools > Network), los campos
-`em`, `ph`, `hashed_email` deben ser cadenas de 64 caracteres hexadecimales.
-
-### Regla 3 — Deduplicación con event_id único
-
-Cuando el mismo evento se envía desde browser (pixel) Y desde servidor (CAPI
-o Measurement Protocol), AMBOS deben incluir el mismo `event_id`. Sin esto,
-GA4 y Meta cuentan el evento dos veces.
-
-```javascript
-// Generar event_id antes de disparar el evento browser
-const eventId = `purchase_${transactionId}_${Date.now()}`;
-// Este mismo eventId se pasa al servidor para el envío CAPI
-```
-
-**Verificación**: En Meta Events Manager > Test Events, el campo "Match
-type" debe mostrar "Deduplicated" para eventos con browser + server.
-
-### Regla 4 — Consent Mode: default denied, actualizar al consentir
-
-Inicializar Consent Mode con todo denegado ANTES de cargar GTM. Actualizar
-solo después de que el usuario otorgue consentimiento explícito.
-
-```javascript
-// Debe ejecutarse ANTES del snippet de GTM
-window.dataLayer = window.dataLayer || [];
-function gtag(){dataLayer.push(arguments);}
-gtag('consent', 'default', {
-  analytics_storage: 'denied',
-  ad_storage: 'denied',
-  ad_user_data: 'denied',
-  ad_personalization: 'denied',
-  wait_for_update: 500,
-});
-```
-
-**Verificación**: En Chrome DevTools > Application > Cookies, no deben
-existir cookies `_ga`, `_fbp` antes de que el usuario acepte.
-
-### Regla 5 — transaction_id único por compra
-
-Un `transaction_id` duplicado en GA4 causa que la compra no se cuente
-(deduplicación silenciosa). Usar el ID de orden del sistema, nunca
-generado en frontend.
-
-**Verificación**: En GA4 DebugView, el evento `purchase` debe aparecer
-con el mismo `transaction_id` que la orden en la base de datos.
-
-## dataLayer schema para e-commerce (GA4 Enhanced Ecommerce)
-
-```javascript
-window.dataLayer = window.dataLayer || [];
-
-// Vista de producto
-dataLayer.push({ ecommerce: null });
-dataLayer.push({
-  event: 'view_item',
-  ecommerce: {
-    currency: 'MXN',
-    value: 299.00,
-    items: [{
-      item_id: 'SKU-001',
-      item_name: 'Producto Premium',
-      item_category: 'Software',
-      price: 299.00,
-      quantity: 1,
-    }]
-  }
-});
-
-// Compra completada
-const eventId = `purchase_${transactionId}_${Date.now()}`;
-dataLayer.push({ ecommerce: null });
-dataLayer.push({
-  event: 'purchase',
-  event_id: eventId,           // Para deduplicación con Meta CAPI
-  ecommerce: {
-    transaction_id: 'ORD-2026-001',  // Único — del sistema backend
-    value: 299.00,
-    tax: 47.84,
-    currency: 'MXN',
-    items: [{
-      item_id: 'SKU-001',
-      item_name: 'Producto Premium',
-      price: 299.00,
-      quantity: 1,
-    }]
-  },
-  user_data: {                 // Para Enhanced Conversions (GTM hashea esto)
-    email_address: 'usuario@ejemplo.com',
-    phone_number: '+525512345678',
-  }
-});
-```
-
-## GA4 via Measurement Protocol (server-side)
-
-```python
-import httpx
-from app.core.config import settings
-
-async def enviar_evento_ga4(
-    client_id: str,
-    evento: str,
-    parametros: dict,
-    session_id: str | None = None,
-) -> None:
-    """Envía evento a GA4 desde el servidor usando Measurement Protocol."""
-    payload = {
-        "client_id": client_id,
-        "events": [{
-            "name": evento,
-            "params": {
-                "session_id": session_id,
-                "engagement_time_msec": "100",
-                **parametros,
-            }
-        }]
-    }
-    async with httpx.AsyncClient() as client:
-        await client.post(
-            "https://www.google-analytics.com/mp/collect",
-            params={
-                "measurement_id": settings.GA4_MEASUREMENT_ID,
-                "api_secret": settings.GA4_API_SECRET,  # Solo en servidor
-            },
-            json=payload,
-            timeout=5.0,
-        )
-```
-
-El `client_id` viene de la cookie `_ga`: formato `GA1.1.XXXXXXXXXX.XXXXXXXXXX`,
-los dos últimos segmentos separados por punto.
-
-## Anti-patrones críticos
-
-| Anti-patrón | Problema | Solución |
-|-------------|----------|----------|
-| Email en texto plano en CAPI | Violación GDPR/Meta ToS | SHA-256 normalizado |
-| `transaction_id` generado en frontend | Duplicados por recargas | Usar ID de orden del backend |
-| Sin `ecommerce: null` previo | Datos de evento anterior contaminan | Siempre limpiar antes |
-| `api_secret` de GA4 en frontend | Exposición de credenciales | Solo en variables de servidor |
-| Pixel browser como única fuente | 40-60% pérdida en iOS | Agregar server-side CAPI |
-| Consent Mode sin inicializar | Cookies antes del banner | Default denied antes de GTM |
-
-## Referencias a recursos
-
-| Tema | Archivo |
-|------|---------|
-| GTM: dataLayer avanzado, triggers, variables, workspace, server-side | [recursos/gtm-datalayer.md](recursos/gtm-datalayer.md) |
-| Meta CAPI: endpoint completo, deduplicación, hashing PII, EMQ | [recursos/meta-capi.md](recursos/meta-capi.md) |
-| Consent Mode v2, GDPR, CCPA, integración con CMPs | [recursos/consent-mode.md](recursos/consent-mode.md) |
-
----
-
-## Gotchas / Errores comunes no obvios
-
-**GTM dispara el tag de `purchase` dos veces en SPAs (React, Angular) porque el trigger "All Pages" se activa tanto en la carga inicial como en la navegación history-pushState, y el dataLayer push de compra queda en memoria entre rutas**: en una tienda Angular, el usuario completa la compra en `/checkout/success`, el evento `purchase` se envía correctamente. Pero si el usuario regresa a `/` usando el botón atrás y luego navega de nuevo a `/checkout/success` sin recargar, GTM vuelve a disparar el tag porque el dataLayer aún contiene el objeto `ecommerce` de la compra anterior. Causa: GTM persiste el dataLayer en memoria durante toda la sesión de la SPA; sin limpiar `{ ecommerce: null }` al navegar, el estado de eventos anteriores contamina rutas subsecuentes. Fix: en el router de la SPA, ejecutar `dataLayer.push({ ecommerce: null })` en cada cambio de ruta (Angular Router: `NavigationEnd` event), y usar triggers de GTM basados en evento personalizado (`purchase_completed`) en lugar de "All Pages" para eventos de conversión.
-
-**Consent Mode v2 configurado con `wait_for_update: 500` bloquea el primer pageview de GA4 en dispositivos lentos donde el CMP tarda más de 500ms en renderizar, causando pérdida del 5-15% de pageviews en usuarios móviles con conexión 3G**: el banner de consentimiento en redes lentas tarda 800-1200ms en cargar el script del CMP. Durante ese tiempo, `wait_for_update: 500` expiró y GA4 disparó el pageview sin el estado de consentimiento correcto, lo que puede generar datos sin la cookie `_ga` y pageviews no atribuibles. Causa: `wait_for_update` es una espera máxima en milisegundos; si el CMP no llama a `gtag('consent', 'update', ...)` antes de ese límite, GA4 procede con el estado default. Fix: aumentar `wait_for_update` a 1500ms para móviles o implementar el CMP de forma que el script cargue de forma crítica (no diferida) para garantizar que actualiza el consentimiento antes del timeout.
-
-**La deduplicación de Meta CAPI falla silenciosamente cuando el `event_id` del browser pixel y del server-side tienen formatos diferentes aunque semánticamente sean el mismo ID**: `event_id: "purchase_ORD-2026-001_1714500000000"` en el browser pixel y `event_id: "purchase_ord-2026-001_1714500000000"` (lowercase) en CAPI son tratados como eventos diferentes por Meta. Meta Events Manager muestra los dos como eventos separados sin deduplicar, duplicando las conversiones reportadas. Causa: Meta compara `event_id` como string exacto, case-sensitive. Fix: definir la generación del `event_id` en una sola función compartida (backend), enviarla al frontend como parte de la respuesta de creación de orden, y usar exactamente ese string en ambos lados. Documentar el formato como contrato: `purchase_{ORDER_ID_UPPERCASE}_{UNIX_TIMESTAMP_MS}`.
-
-**El hashing SHA-256 de email para Meta CAPI falla en la deduplicación cuando el email viene con caracteres de espacio en blanco invisible (NBSP, U+00A0) que el usuario copió de un email de confirmación**: `hashlib.sha256("usuario@ejemplo.com".encode()).hexdigest()` y `hashlib.sha256("usuario@ejemplo.com\u00a0".encode()).hexdigest()` producen hashes completamente diferentes, y Meta no puede hacer match con el PII del usuario registrado. Causa: el método `.strip()` de Python elimina espacios ASCII (U+0020) pero no todos los caracteres de espacio Unicode como NBSP (U+00A0) o ZWSP (U+200B). Fix: normalizar el email con `unicodedata.normalize('NFKC', email).strip().lower()` antes del hash. La normalización NFKC convierte variantes Unicode de caracteres de espacio a sus equivalentes ASCII, garantizando consistencia del hash.