roi-theme/wp-content/themes/apus-theme/ISSUE-32-CTA-AB-TESTING.md

# Issue #32 - CTA con A/B Testing - IMPLEMENTADO

**Fecha de implementación:** 2025-11-04
**Estado:** ✅ COMPLETADO
**Issue:** #32 - Implementar CTA con A/B Testing (2 variantes + tracking GA)

---

## 📋 Resumen de Implementación

Se ha implementado exitosamente un sistema completo de Call-to-Action (CTA) con A/B Testing que permite mostrar dos variantes diferentes (A y B) de forma aleatoria a los usuarios, con persistencia por cookies y tracking completo de conversiones mediante Google Analytics 4.

---

## 📁 Archivos Creados

### 1. Sistema Core A/B Testing
**Archivo:** `inc/cta-ab-testing.php`
- Sistema de asignación de variantes con cookies (30 días de persistencia)
- Distribución aleatoria 50/50 entre variante A y B
- Template tag `apus_display_cta()` para uso manual
- Shortcode `[apus_cta]` para inserción en contenido
- Hooks automáticos para inserción después del contenido
- Body classes dinámicas para tracking

### 2. Opciones del Customizer
**Archivo:** `inc/customizer-cta.php`
- Sección completa en el Customizer: "CTA A/B Testing"
- Toggle para habilitar/deshabilitar el CTA
- Configuración completa de Variante A (Catálogo):
  - Título configurable
  - Texto descriptivo
  - Texto del botón
  - URL destino
- Configuración completa de Variante B (Membresía):
  - Título configurable
  - Texto descriptivo
  - Texto del botón
  - URL destino
- Configuración de Google Analytics:
  - Campo para Tracking ID (GA4 o Universal Analytics)
  - Script automático de gtag.js
  - Respeto a usuarios admin (no tracking)

### 3. Template Part
**Archivo:** `template-parts/content-cta.php`
- Template part reutilizable
- Verificación de contexto (solo posts individuales)
- Uso del template tag del sistema core

### 4. Estilos CSS
**Archivo:** `assets/css/cta.css`
- Diseño con degradado naranja-amarillo (#FF8600 → #FFB800)
- Sombra prominente con color naranja
- Botón blanco con hover effects
- Diseño responsive (2 columnas en desktop, stack en mobile)
- Soporte para reduced motion (accesibilidad)
- Soporte para alto contraste
- Soporte para dark mode
- Estilos de impresión optimizados
- Soporte RTL (right-to-left)
- Animaciones de entrada opcionales

### 5. JavaScript de Tracking
**Archivo:** `assets/js/cta-tracking.js`
- Tracking de impresiones con IntersectionObserver
- Tracking de clicks en botones CTA
- Integración con Google Analytics 4
- Validación de consistencia de variantes
- Debug mode para desarrollo
- API pública para extensiones
- Fallbacks para navegadores antiguos

---

## ⚙️ Configuración en functions.php

Se agregaron las siguientes líneas al archivo `functions.php`:

```php
// CTA A/B Testing system (Issue #32)
if (file_exists(get_template_directory() . '/inc/cta-ab-testing.php')) {
    require_once get_template_directory() . '/inc/cta-ab-testing.php';
}

// CTA Customizer options (Issue #32)
if (file_exists(get_template_directory() . '/inc/customizer-cta.php')) {
    require_once get_template_directory() . '/inc/customizer-cta.php';
}
```

---

## 🎨 Configuración en enqueue-scripts.php

Se agregó la función de enqueue en `inc/enqueue-scripts.php`:

```php
/**
 * Enqueue CTA A/B Testing styles and scripts
 */
function apus_enqueue_cta_assets() {
    // Solo enqueue en posts individuales
    if (!is_single()) {
        return;
    }

    // Verificar si el CTA está habilitado
    $enable_cta = get_theme_mod('apus_enable_cta', true);
    if (!$enable_cta) {
        return;
    }

    // CTA CSS
    wp_enqueue_style(
        'apus-cta-style',
        get_template_directory_uri() . '/assets/css/cta.css',
        array('apus-bootstrap'),
        APUS_VERSION,
        'all'
    );

    // CTA Tracking JS
    wp_enqueue_script(
        'apus-cta-tracking',
        get_template_directory_uri() . '/assets/js/cta-tracking.js',
        array(),
        APUS_VERSION,
        array(
            'in_footer' => true,
            'strategy'  => 'defer',
        )
    );
}

add_action('wp_enqueue_scripts', 'apus_enqueue_cta_assets', 16);
```

---

## 🎯 Variantes del CTA

### Variante A: Enfoque en Catálogo
**Target:** Usuarios que buscan consultar APUs específicos
- **Título:** "Accede a 200,000+ Análisis de Precios Unitarios"
- **Descripción:** "Consulta estructuras completas, insumos y dosificaciones de los APUs más utilizados en construcción en México."
- **Botón:** "Ver Catálogo Completo"
- **Color de evento GA:** Value = 1

### Variante B: Enfoque en Membresía
**Target:** Usuarios interesados en acceso ilimitado
- **Título:** "¿Necesitas Consultar Más APUs?"
- **Descripción:** "Accede a nuestra biblioteca de 200,000 análisis de precios unitarios con estructuras detalladas y listados de insumos."
- **Botón:** "Conocer Planes de Membresía"
- **Color de evento GA:** Value = 2

---

## 🚀 Uso del CTA

### Método 1: Template Tag (Recomendado)
En cualquier archivo de template (ej: `single.php`):

```php
<?php apus_display_cta(); ?>
```

O en `template-parts`:

```php
<?php get_template_part('template-parts/content', 'cta'); ?>
```

### Método 2: Shortcode
En el contenido de un post o página:

```
[apus_cta]
```

### Método 3: Auto-inserción
Activar en el Customizer: **CTA A/B Testing > Auto-insertar CTA después del contenido**

---

## 📊 Tracking con Google Analytics

### Configuración

1. Ir a **Apariencia > Personalizar > CTA A/B Testing**
2. Scroll hasta la sección **━━━ Google Analytics ━━━**
3. Ingresar el Tracking ID (formato: G-XXXXXXXXXX o UA-XXXXXXXXX-X)
4. Guardar cambios

**Nota:** Si ya tienes Google Analytics instalado mediante otro plugin, deja este campo vacío para evitar duplicación.

### Eventos Tracked

#### 1. Impresión del CTA (`cta_impression`)
Se dispara cuando el CTA es visible al menos 50% en el viewport.

**Parámetros:**
- `event_category`: "CTA"
- `event_label`: "Variant_A" o "Variant_B"
- `variant`: "A" o "B"
- `non_interaction`: true

#### 2. Click en el Botón (`cta_click`)
Se dispara cuando el usuario hace click en el botón del CTA.

**Parámetros:**
- `event_category`: "CTA"
- `event_label`: "Variant_A" o "Variant_B"
- `variant`: "A" o "B"
- `button_text`: Texto del botón clickeado
- `target_url`: URL destino del botón
- `value`: 1 (variante A) o 2 (variante B)

### Ver Resultados en Google Analytics 4

1. Ir a **Eventos** en Google Analytics
2. Buscar eventos `cta_impression` y `cta_click`
3. Crear informe personalizado para comparar:
   - Impresiones por variante
   - Clicks por variante
   - CTR (Click-Through Rate) por variante
   - Conversiones por variante

### Calcular CTR por Variante

```
CTR Variante A = (cta_click Variant_A / cta_impression Variant_A) × 100
CTR Variante B = (cta_click Variant_B / cta_impression Variant_B) × 100
```

---

## 🎨 Personalización en el Customizer

### Acceder al Panel
1. Ir a **Apariencia > Personalizar**
2. Buscar sección **CTA A/B Testing**

### Opciones Disponibles

#### Configuración General
- ✅ **Habilitar CTA con A/B Testing**: Toggle para activar/desactivar
- ☐ **Auto-insertar CTA después del contenido**: Inserción automática (recomendado usar template tag manual)

#### Variante A: Catálogo
- **Título**: Texto del encabezado
- **Texto descriptivo**: Descripción del CTA
- **Texto del botón**: Call-to-action del botón
- **URL del botón**: Destino al hacer click

#### Variante B: Membresía
- **Título**: Texto del encabezado
- **Texto descriptivo**: Descripción del CTA
- **Texto del botón**: Call-to-action del botón
- **URL del botón**: Destino al hacer click

#### Google Analytics
- **Google Analytics Tracking ID**: ID de propiedad GA4 o Universal Analytics

---

## 🔧 Características Técnicas

### Sistema A/B Testing

**Método de asignación:**
- Asignación aleatoria 50/50 mediante `rand(0, 1)`
- Cookie `apus_cta_variant` con duración de 30 días
- Persistencia de variante por usuario
- Validación en JavaScript para consistencia

**Cookie Details:**
- **Nombre:** `apus_cta_variant`
- **Valores:** "A" o "B"
- **Duración:** 30 días
- **Path:** COOKIEPATH (configurado en WordPress)
- **Domain:** COOKIE_DOMAIN (configurado en WordPress)

### Performance

**CSS:**
- Tamaño: ~5KB (no minificado)
- Dependencias: Bootstrap 5.3.2
- Carga: Solo en single posts
- Media queries para responsive

**JavaScript:**
- Tamaño: ~6KB (no minificado)
- Dependencias: Ninguna (vanilla JS)
- Carga: Defer en footer
- IntersectionObserver para impresiones
- Event delegation para clicks

### Accesibilidad

- ✅ Soporte para `prefers-reduced-motion`
- ✅ Soporte para `prefers-contrast: high`
- ✅ Focus visible en botones
- ✅ Texto alternativo en iconos
- ✅ Color contrast ratio WCAG AA compliant
- ✅ Keyboard navigation compatible

### Responsive Design

**Desktop (≥992px):**
- Layout de 2 columnas (8/4 grid)
- Botón alineado a la derecha

**Tablet (768px - 991px):**
- Layout de 2 columnas ajustado
- Font sizes ligeramente reducidos

**Mobile (<768px):**
- Stack vertical (1 columna)
- Botón full-width
- Padding reducido para mejor uso del espacio

---

## 🧪 Testing y Validación

### Verificar Sintaxis PHP
Todos los archivos han sido validados con `php -l`:

```bash
✅ inc/cta-ab-testing.php - No syntax errors
✅ inc/customizer-cta.php - No syntax errors
✅ template-parts/content-cta.php - No syntax errors
✅ inc/enqueue-scripts.php - No syntax errors
✅ functions.php - No syntax errors
```

### Checklist de Testing

#### Funcionalidad Básica
- [ ] CTA se muestra en posts individuales
- [ ] CTA no se muestra en páginas/archive/home
- [ ] Solo una variante visible por carga de página
- [ ] Refrescar página múltiples veces muestra ambas variantes (~50/50)
- [ ] Cookie se crea correctamente (`apus_cta_variant`)
- [ ] Misma variante se muestra en múltiples visitas (cookie persistence)

#### Customizer
- [ ] Opciones aparecen en "Apariencia > Personalizar > CTA A/B Testing"
- [ ] Cambios en textos se reflejan en el frontend
- [ ] Cambios en URLs funcionan correctamente
- [ ] Toggle on/off funciona correctamente

#### Tracking
- [ ] Click en botón registra evento en consola del navegador
- [ ] Si GA está instalado, evento `cta_click` aparece en GA4 Real-Time
- [ ] Parámetro `event_label` distingue correctamente entre Variant_A y Variant_B
- [ ] Evento `cta_impression` se registra cuando el CTA es visible
- [ ] IntersectionObserver funciona correctamente

#### Diseño y Responsive
- [ ] Diseño responsive funciona en móviles (stack vertical)
- [ ] Sombra naranja visible alrededor del CTA
- [ ] Degradado naranja-amarillo se muestra correctamente
- [ ] Hover en botón funciona (elevación + sombra)
- [ ] Icono de flecha (Bootstrap Icon) aparece a la derecha del texto
- [ ] Botón es full-width en mobile

#### Accesibilidad
- [ ] Navegación por teclado funciona (Tab, Enter)
- [ ] Focus visible en botones
- [ ] Reduced motion respetado (sin animaciones)
- [ ] Alto contraste funciona correctamente

---

## 🐛 Debugging

### Habilitar Debug Mode

El sistema incluye debug logging que se activa automáticamente cuando `WP_DEBUG` está habilitado.

En `wp-config.php`:

```php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
```

### Ver Logs en Consola

Abre las Developer Tools (F12) en el navegador y busca mensajes con el prefijo `[CTA A/B Test]`.

Ejemplos:
```
[CTA A/B Test] Inicializando CTA A/B Testing Tracking {variant: "A", ...}
[CTA A/B Test] ✓ Variante consistente: A
[CTA A/B Test] IntersectionObserver configurado para el CTA
[CTA A/B Test] Impresión del CTA registrada {variant: "A"}
[CTA A/B Test] Click del CTA registrado {variant: "A", buttonText: "...", ...}
```

### API JavaScript Pública

El sistema expone una API pública para debugging:

```javascript
// En la consola del navegador:

// Obtener variante actual
apusCTATracking.getVariant(); // "A" o "B"

// Ver configuración
apusCTATracking.config;

// Disparar evento manualmente
apusCTATracking.trackClick('A', 'Texto del botón', 'https://example.com');
apusCTATracking.trackImpression('A');
```

### Validar Cookie

En la consola del navegador:

```javascript
document.cookie.split(';').find(c => c.includes('apus_cta_variant'))
// Resultado: " apus_cta_variant=A" o " apus_cta_variant=B"
```

---

## 📈 Métricas Recomendadas

### KPIs Principales

1. **CTR (Click-Through Rate) por Variante**
   - Métrica: (Clicks / Impresiones) × 100
   - Objetivo: > 5%

2. **Tasa de Conversión por Variante**
   - Métrica: (Conversiones / Clicks) × 100
   - Objetivo: Depende del negocio

3. **Engagement Time**
   - Métrica: Tiempo promedio en página después de ver el CTA
   - Objetivo: Aumentar en 20%+

### Análisis Recomendado

**Periodo mínimo de testing:** 30 días o 1000 impresiones por variante (lo que sea mayor)

**Significancia estadística:** Usar calculadora de A/B test para validar resultados antes de tomar decisiones.

**Criterio de éxito:** La variante ganadora debe tener:
- CTR al menos 20% mayor
- Significancia estadística > 95%
- Muestra suficiente (>1000 impresiones/variante)

---

## 🔮 Mejoras Futuras (Opcional)

### Test Multivariante (A/B/C)
Agregar una tercera variante C con diferente enfoque:

```php
// En cta-ab-testing.php
$variant = (rand(0, 2) === 0) ? 'A' : ((rand(0, 1) === 0) ? 'B' : 'C');
```

### Persistencia por Usuario Logueado
Guardar variante en user_meta para usuarios registrados:

```php
if (is_user_logged_in()) {
    $user_id = get_current_user_id();
    $variant = get_user_meta($user_id, 'cta_variant', true);
    if (!$variant) {
        $variant = (rand(0, 1) === 0) ? 'A' : 'B';
        update_user_meta($user_id, 'cta_variant', $variant);
    }
}
```

### Test Dirigido por Categoría
Mostrar variantes específicas según la categoría del post:

```php
$category = get_the_category()[0]->slug;
if (in_array($category, ['construccion', 'obra-civil'])) {
    $variant = 'A'; // Catálogo
} else {
    $variant = 'B'; // Membresía
}
```

### Dashboard de Resultados en WP-Admin
Crear página en wp-admin para ver estadísticas de clicks por variante sin salir de WordPress.

### Segmentación por Fuente de Tráfico
Mostrar diferentes variantes según si el usuario viene de:
- Google Search
- Redes sociales
- Tráfico directo
- Referencias

---

## 📚 Dependencias

- ✅ **Bootstrap 5.3.2** (local) - Grid responsive y componentes
- ✅ **Bootstrap Icons 1.11.3** (CDN) - Icono de flecha
- ✅ **JavaScript ES6** - No requiere jQuery
- ⚠️ **Google Analytics 4** (opcional) - Solo para tracking

---

## 🔗 Referencias

- Template HTML: `_planeacion/theme-template/index.html` (líneas 973-1002)
- Template CSS: `_planeacion/theme-template/css/style.css` (líneas 467-470)
- Template JS: `_planeacion/theme-template/js/main.js` (líneas 85-114)
- Issue original: GitHub #32
- Google Analytics Events: https://developers.google.com/analytics/devguides/collection/ga4/events
- A/B Testing Best Practices: https://www.optimizely.com/optimization-glossary/ab-testing/

---

## ✅ Verificación Final

### Archivos Creados (5)
- ✅ `inc/cta-ab-testing.php` - Sistema core de A/B testing
- ✅ `inc/customizer-cta.php` - Opciones del Customizer
- ✅ `template-parts/content-cta.php` - Template part
- ✅ `assets/css/cta.css` - Estilos CSS
- ✅ `assets/js/cta-tracking.js` - JavaScript tracking

### Archivos Modificados (2)
- ✅ `functions.php` - Require de nuevos módulos
- ✅ `inc/enqueue-scripts.php` - Enqueue de assets

### Validación de Sintaxis
- ✅ Todos los archivos PHP validados sin errores
- ✅ Comentarios en español según especificaciones
- ✅ Código siguiendo estándares WordPress

---

## 📞 Soporte

Para issues o preguntas sobre la implementación:
- GitHub: Issue #32
- Documentación completa en este archivo

---

**Implementado por:** Claude Code
**Fecha:** 2025-11-04
**Issue:** #32 - Implementar CTA con A/B Testing

---

🎉 **El Issue #32 ha sido completado exitosamente.**