@saulwade/swl-ses 1.0.0

package/habilidades/tracking-measurement/SKILL.md

@@ -0,0 +1,239 @@
+---
+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.

package/habilidades/tracking-measurement/recursos/consent-mode.md

@@ -0,0 +1,231 @@
+# Consent Mode v2: GDPR, CCPA e integración con CMPs
+
+## Qué es Consent Mode v2
+
+Consent Mode v2 es un mecanismo de Google que permite a los tags de Google
+(GA4, Google Ads, Floodlight) adaptar su comportamiento según el consentimiento
+del usuario. Introducido en 2024 como requisito para mantener la personalización
+de anuncios en el EEE y UK.
+
+### Los 4 parámetros de consentimiento
+
+| Parámetro | Controla |
+|-----------|----------|
+| `analytics_storage` | Cookies de medición (GA4: `_ga`, `_ga_*`) |
+| `ad_storage` | Cookies de publicidad (Google Ads, Floodlight) |
+| `ad_user_data` | Envío de datos de usuario a Google para publicidad |
+| `ad_personalization` | Remarketing y personalización de anuncios |
+
+Cuando un parámetro está `denied`, Google no almacena cookies pero sí
+registra eventos "sin cookies" (pings anónimos) para el modelado estadístico.
+
+## Implementación base con gtag
+
+El código de Consent Mode debe ejecutarse ANTES del snippet de GTM o gtag.
+El orden importa: si GTM carga primero, puede crear cookies antes del consentimiento.
+
+```html
+<!-- 1. Snippet de Consent Mode — ANTES de GTM -->
+<script>
+  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,  // ms para esperar la respuesta del CMP
+  });
+
+  gtag('set', 'ads_data_redaction', true);  // Redactar URLs de click si denied
+  gtag('set', 'url_passthrough', true);     // Pasar info de click en URL para atribución
+</script>
+
+<!-- 2. Snippet de GTM — DESPUÉS de Consent Mode -->
+<script>
+  (function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
+  new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
+  j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
+  'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
+  })(window,document,'script','dataLayer','GTM-XXXXXXX');
+</script>
+```
+
+### Actualizar consentimiento tras decisión del usuario
+
+```javascript
+// Llamar después de que el usuario acepta en el banner del CMP
+function otorgarConsentimiento(opciones) {
+  gtag('consent', 'update', {
+    analytics_storage: opciones.analytics ? 'granted' : 'denied',
+    ad_storage: opciones.publicidad ? 'granted' : 'denied',
+    ad_user_data: opciones.publicidad ? 'granted' : 'denied',
+    ad_personalization: opciones.publicidad ? 'granted' : 'denied',
+  });
+}
+
+// Llamar cuando el usuario rechaza todo
+function rechazarConsentimiento() {
+  gtag('consent', 'update', {
+    analytics_storage: 'denied',
+    ad_storage: 'denied',
+    ad_user_data: 'denied',
+    ad_personalization: 'denied',
+  });
+}
+```
+
+## Integración con CMPs
+
+### Cookiebot
+
+Cookiebot dispara el evento `CookiebotOnAccept` / `CookiebotOnDecline`.
+Integración directa disponible en GTM como template oficial de la galería.
+
+```javascript
+// Listener para Cookiebot
+window.addEventListener('CookiebotOnAccept', function() {
+  gtag('consent', 'update', {
+    analytics_storage: Cookiebot.consent.statistics ? 'granted' : 'denied',
+    ad_storage: Cookiebot.consent.marketing ? 'granted' : 'denied',
+    ad_user_data: Cookiebot.consent.marketing ? 'granted' : 'denied',
+    ad_personalization: Cookiebot.consent.marketing ? 'granted' : 'denied',
+  });
+}, false);
+```
+
+### OneTrust
+
+OneTrust usa categorías de cookies mapeadas a grupos:
+
+| Grupo OneTrust | Parámetro Consent Mode |
+|---------------|----------------------|
+| `C0002` (Performance) | `analytics_storage` |
+| `C0004` (Targeting) | `ad_storage`, `ad_user_data`, `ad_personalization` |
+
+```javascript
+// Template GTM disponible en: OneTrust > GTM Integration
+// O implementación manual:
+window.OneTrust?.OnConsentChanged(function(event) {
+  const activas = event.detail;
+  gtag('consent', 'update', {
+    analytics_storage: activas.includes('C0002') ? 'granted' : 'denied',
+    ad_storage: activas.includes('C0004') ? 'granted' : 'denied',
+    ad_user_data: activas.includes('C0004') ? 'granted' : 'denied',
+    ad_personalization: activas.includes('C0004') ? 'granted' : 'denied',
+  });
+});
+```
+
+### Usercentrics
+
+Usercentrics expone el objeto `UC_UI` y el evento `ucEvent`:
+
+```javascript
+window.addEventListener('ucEvent', function(e) {
+  if (e.detail?.event === 'consent_status') {
+    const servicios = e.detail;
+    gtag('consent', 'update', {
+      analytics_storage: servicios['Google Analytics'] ? 'granted' : 'denied',
+      ad_storage: servicios['Google Ads'] ? 'granted' : 'denied',
+      ad_user_data: servicios['Google Ads'] ? 'granted' : 'denied',
+      ad_personalization: servicios['Google Ads'] ? 'granted' : 'denied',
+    });
+  }
+});
+```
+
+## Modelado de conversiones en GA4
+
+Cuando `analytics_storage` o `ad_storage` está `denied`, GA4 no puede
+atribuir conversiones directamente. Google utiliza ML para estimar las
+conversiones faltantes basándose en usuarios con consentimiento similar.
+
+**Condiciones para que el modelado funcione**:
+- Mínimo 1,000 conversiones observables por semana.
+- Tasa de consentimiento > 0% (si nadie acepta, no hay datos base).
+- Consent Mode implementado correctamente (los pings anónimos llegan).
+
+**Verificar que los pings llegan**: En GA4 > Admin > Data streams > tu stream >
+Measurement Protocol. Debe mostrar eventos incluso de usuarios sin consentimiento
+(aparecen como eventos anónimos sin `client_id`).
+
+## GDPR: base legal por tipo de tracking
+
+| Tipo de tracking | Base legal posible | Requiere banner |
+|-----------------|-------------------|-----------------|
+| Analytics de medición interna | Interés legítimo (debatible) | Sí, en la mayoría de países |
+| Analytics para mejora de producto | Interés legítimo | Sí |
+| Retargeting / remarketing | Consentimiento explícito | Sí, siempre |
+| Conversiones para optimización de anuncios | Consentimiento explícito | Sí, siempre |
+
+**Práctica recomendada**: usar consentimiento explícito para todo tracking
+publicitario y analítico. El interés legítimo es cuestionable y está siendo
+restringido en interpretaciones recientes del GDPR.
+
+**Registro de consentimiento**: almacenar en base de datos:
+- Fecha y hora de la decisión
+- Versión de la política de privacidad aceptada
+- Opciones específicas seleccionadas por el usuario
+- IP anonimizada (últimos 2 octetos a 0)
+
+## CCPA: opt-out en lugar de opt-in
+
+En California (CCPA), el modelo es inverso al GDPR: tracking activo por
+defecto, con obligación de ofrecer opt-out.
+
+```javascript
+// URL de opt-out requerida por CCPA
+// El usuario llega desde el enlace "No vender mi información personal"
+if (new URLSearchParams(location.search).has('ccpa_opt_out')) {
+  gtag('consent', 'update', {
+    ad_storage: 'denied',
+    ad_user_data: 'denied',
+    ad_personalization: 'denied',
+  });
+  // Persistir la preferencia en localStorage
+  localStorage.setItem('ccpa_opt_out', 'true');
+}
+
+// Al cargar la página, verificar opt-out previo
+if (localStorage.getItem('ccpa_opt_out') === 'true') {
+  gtag('consent', 'update', {
+    ad_storage: 'denied',
+    ad_user_data: 'denied',
+    ad_personalization: 'denied',
+  });
+}
+```
+
+**US Privacy String**: formato `1YNN` (versión 1, aviso notificado, opt-out no,
+LSPA no). Incluir en requests de publicidad si se usa un ad server compatible.
+
+## Verificación con Consent Mode Inspector
+
+En Chrome DevTools > Application > Cookies:
+- Antes de aceptar: no deben existir `_ga`, `_ga_*`, `_gcl_*`, `_fbp`
+- Después de aceptar analytics: `_ga` y `_ga_MEASUREMENTID` deben aparecer
+- Después de aceptar publicidad: `_gcl_au` (Google Ads) debe aparecer
+
+En la consola del browser:
+```javascript
+// Ver estado actual del consentimiento
+window.dataLayer.filter(e => e[0] === 'consent')
+// Debe mostrar el 'default' y los 'update' aplicados
+```
+
+Con la extensión **Consent Mode Inspector** de Google (Chrome Web Store):
+muestra en tiempo real el estado de cada parámetro y los cambios al interactuar
+con el banner de consentimiento.
+
+## Checklist de cumplimiento pre-lanzamiento
+
+- [ ] Consent Mode inicializado ANTES del snippet de GTM
+- [ ] Default: los 4 parámetros en `denied`
+- [ ] Banner de CMP visible en primera visita para usuarios del EEE
+- [ ] `gtag('consent', 'update', ...)` se ejecuta al aceptar/rechazar
+- [ ] Sin cookies `_ga`, `_fbp` antes del consentimiento (verificar en DevTools)
+- [ ] Registro de consentimiento almacenado en base de datos
+- [ ] Enlace "No vender mi información" visible en footer (para CCPA)
+- [ ] Política de privacidad actualizada con tecnologías de tracking usadas

package/habilidades/tracking-measurement/recursos/gtm-datalayer.md

@@ -0,0 +1,216 @@
+# GTM: dataLayer avanzado, triggers, variables y server-side
+
+## Arquitectura de GTM
+
+GTM funciona con tres conceptos fundamentales que se relacionan en orden:
+
+```
+Trigger (cuándo) ──► Tag (qué hacer) ──► Variable (con qué datos)
+```
+
+Un **trigger** detecta un evento en la página. Una **tag** se dispara cuando
+el trigger se activa. Las **variables** proveen los datos que la tag necesita.
+
+### Workspace y versiones
+
+- El **workspace** es el entorno de trabajo en progreso (sin publicar).
+- Cada **versión** es un snapshot publicado con nombre, fecha y descripción.
+- Crear una versión antes de cada cambio relevante: `Versión > Nueva versión`.
+- En producción usar siempre un contenedor publicado, nunca el workspace.
+- Ambientes (`Environments`): crear uno por stage (dev, staging, prod) para
+  probar sin afectar el contenedor de producción.
+
+## Variables
+
+### Variables built-in
+
+GTM incluye variables activables sin configuración extra:
+
+| Variable | Valor |
+|----------|-------|
+| `Page URL` | URL completa de la página actual |
+| `Page Path` | Solo el path: `/productos/sku-001` |
+| `Click URL` | URL del elemento clickeado |
+| `Click Text` | Texto del elemento clickeado |
+| `Click Classes` | Clases CSS del elemento clickeado |
+| `Form URL` | URL de acción del formulario enviado |
+| `Scroll Depth Threshold` | Porcentaje de scroll alcanzado |
+
+Activarlas en: Variables > Built-In Variables > Configure.
+
+### Variables personalizadas de dataLayer
+
+Para leer valores del objeto `ecommerce` del dataLayer:
+
+- Tipo: **Data Layer Variable**
+- Nombre de variable: `ecommerce.transaction_id` (notación de punto)
+- Versión del dataLayer: **Version 2** (siempre para GA4)
+- Nombre de la variable en GTM: `{{DL - ecommerce.transaction_id}}`
+
+Convención de naming para variables de dataLayer: `{{DL - ruta.al.valor}}`.
+
+### Variables de JavaScript personalizado
+
+Para lógica más compleja (formateo, cálculos, lectura de cookies):
+
+```javascript
+// Variable: {{JS - GA Client ID}}
+function() {
+  var cookie = document.cookie.match(/_ga=([^;]+)/);
+  if (!cookie) return undefined;
+  var parts = cookie[1].split('.');
+  return parts.slice(-2).join('.');
+}
+```
+
+```javascript
+// Variable: {{JS - FBC Cookie}}
+function() {
+  var match = document.cookie.match(/_fbc=([^;]+)/);
+  return match ? match[1] : undefined;
+}
+```
+
+## Triggers
+
+### Tipos de trigger más usados
+
+**All Pages (Pageview)**: Se dispara en cada carga de página. Base para GA4
+Configuration tag. Siempre presente en todo contenedor.
+
+**Custom Event**: Se dispara cuando `dataLayer.push({ event: 'nombre' })`
+coincide con el nombre configurado. Usar para eventos de e-commerce.
+
+```
+Trigger > Custom Event
+Event name: purchase
+(Para capturar todos los eventos custom: usar regex .*)
+```
+
+**Click - All Elements**: Se dispara en cualquier click. Útil para tracking
+de botones sin código JavaScript adicional.
+
+**Form Submission**: Se dispara al enviar un formulario. Requiere activar
+`Form` en Built-In Variables.
+
+**History Change**: Esencial en Single-Page Apps (React, Angular, Vue) donde
+la URL cambia sin recarga completa. Usar en lugar de Pageview para SPAs.
+
+### Race conditions en SPAs
+
+En aplicaciones de una sola página, el trigger `History Change` puede
+dispararse antes de que el componente actualice el dataLayer. Solución:
+
+```javascript
+// Después del cambio de ruta, esperar al siguiente tick
+router.afterEach((to) => {
+  setTimeout(() => {
+    dataLayer.push({ ecommerce: null });
+    dataLayer.push({
+      event: 'page_view',
+      page_path: to.path,
+      page_title: to.meta.title,
+    });
+  }, 0);
+});
+```
+
+Alternativa con GTM: usar la variable `{{JS - Page Path}}` con `Page Path`
+built-in, que siempre refleja la URL actual al momento del trigger.
+
+## Tags
+
+### GA4 Configuration Tag
+
+Una sola por contenedor. Se dispara en All Pages.
+
+- Tag type: **Google Analytics: GA4 Configuration**
+- Measurement ID: `{{Constant - GA4 Measurement ID}}`
+- Fields to set: `debug_mode` = `true` (solo en workspace de desarrollo)
+
+### GA4 Event Tag
+
+Una por tipo de evento e-commerce.
+
+- Tag type: **Google Analytics: GA4 Event**
+- Configuration Tag: seleccionar la Configuration Tag creada arriba
+- Event Name: `{{DL - event}}` (lee el nombre del evento del dataLayer)
+- Trigger: Custom Event con el nombre del evento
+
+Para pasar el objeto `ecommerce` completo:
+- Event Parameters: agregar `items` = `{{DL - ecommerce.items}}`
+- Marcar **Send Ecommerce data**: activado, Source: Data Layer
+
+### Conversion Linker
+
+Tag obligatoria para Enhanced Conversions y cross-device tracking:
+
+- Tag type: **Conversion Linker**
+- Trigger: All Pages
+- Colocar antes que cualquier tag de conversión de Google Ads
+
+## GTM Server-Side en Cloud Run
+
+El servidor GTM actúa como proxy entre el browser y las plataformas de ads,
+permitiendo enviar datos first-party sin depender de las restricciones del browser.
+
+### Setup mínimo
+
+1. Crear un contenedor de tipo **Server** en GTM.
+2. Desplegar la imagen `gcr.io/cloud-tagging-10302018/gts-preview:latest`
+   en Cloud Run (mínimo 1 instancia siempre activa para latencia).
+3. Configurar el **Server Container URL** en el contenedor browser de GTM.
+4. Verificar que las requests van a `tu-dominio.com/g/collect` en vez de
+   directamente a `google-analytics.com`.
+
+### Client templates
+
+El servidor GTM necesita un **Client** que reciba las requests del browser:
+
+- **GA4 Client**: recibe requests del tag GA4 del browser.
+- **Meta Pixel Client**: recibe requests del Meta Pixel del browser.
+
+Cada client parsea el payload y lo pone disponible para los tags del servidor.
+
+### Tag templates del servidor
+
+Los tags del servidor envían datos a las plataformas finales:
+
+- **GA4 (server-side)**: usa `measurement_id` y `api_secret` como variables.
+- **Meta CAPI**: usa `pixel_id` y `access_token` como variables de entorno.
+
+Ventaja clave: las variables con credenciales viven en el servidor,
+nunca expuestas en el browser.
+
+## Modo de depuración
+
+### Tag Assistant
+
+1. En GTM workspace > Preview: abre Tag Assistant en una nueva pestaña.
+2. Ingresar la URL del sitio y activar la sesión de debug.
+3. El panel izquierdo muestra todos los eventos del dataLayer en orden.
+4. Hacer click en un evento para ver qué tags se dispararon y cuáles no.
+
+### GA4 DebugView
+
+En GA4 > Admin > DebugView: muestra eventos en tiempo real del browser
+con `debug_mode: true`. Indispensable para validar eventos e-commerce.
+
+### Regla de validación antes de pasar a producción
+
+1. Verificar en Tag Assistant que cada evento tiene `ecommerce: null` previo.
+2. Confirmar en GA4 DebugView que el evento `purchase` llega con el
+   `transaction_id` correcto.
+3. Publicar una versión con nombre descriptivo: `"feat: purchase event GA4"`.
+4. Monitorear GA4 > Realtime durante las primeras 24 horas post-deploy.
+
+## Buenas prácticas de naming
+
+| Tipo | Convención | Ejemplo |
+|------|-----------|---------|
+| Variable dataLayer | `{{DL - ruta.del.valor}}` | `{{DL - ecommerce.transaction_id}}` |
+| Variable JavaScript | `{{JS - Descripción}}` | `{{JS - GA Client ID}}` |
+| Constante | `{{Constant - Nombre}}` | `{{Constant - GA4 Measurement ID}}` |
+| Trigger custom event | Igual que el nombre del evento | `purchase`, `view_item` |
+| Tag GA4 | `GA4 - Nombre del evento` | `GA4 - Purchase`, `GA4 - Config` |
+| Tag conversión | `Ads - Nombre conversión` | `Ads - Purchase Conversion` |