roi-theme/_openspec/changes/adsense-auto-ads-toggle/spec.md

Especificacion: AdSense Auto Ads Toggle

Purpose

Define el comportamiento de un interruptor "Auto Ads" que cuando se activa, delega el control de ubicacion de anuncios a Google AdSense Auto Ads, desactivando automaticamente todas las ubicaciones manuales del tema EXCEPTO los anuncios en resultados de busqueda del plugin ROI APU Search.

Problema que resuelve: El usuario necesita probar Google Auto Ads sin tener que deshabilitar manualmente cada ubicacion de anuncio. Ademas, Auto Ads tiende a romper el layout de tablas HTML, por lo que se requiere excluirlas automaticamente.

Beneficio esperado: Comparar facilmente el rendimiento (RPM, CTR, revenue) entre ubicaciones manuales vs Auto Ads de Google, manteniendo siempre activos los anuncios en el buscador APU.

---

Requirements

Requirement: Campo enable_auto_ads en Schema

El schema adsense-placement.json DEBE incluir un nuevo campo para activar Auto Ads.

Scenario: Definicion del campo en JSON Schema

• WHEN se define el campo enable_auto_ads
• THEN DEBE ubicarse en el grupo visibility con priority 10
• AND DEBE tener type boolean
• AND DEBE tener default false
• AND DEBE tener label Activar Google Auto Ads
• AND DEBE tener description Cuando esta activo, Google controla automaticamente donde mostrar anuncios. Se desactivan las ubicaciones manuales excepto los anuncios en busqueda.

Scenario: Posicion del campo en el formulario

• WHEN se renderiza el formulario de configuracion
• THEN el campo enable_auto_ads DEBE aparecer inmediatamente despues de is_enabled
• AND DEBE tener un indicador visual destacado (badge o icono) indicando que es modo automatico

---

Requirement: Desactivacion Automatica de Ubicaciones Manuales

Cuando Auto Ads esta activo, el sistema DEBE ignorar todas las configuraciones de ubicacion manual.

Scenario: Grupos afectados por enable_auto_ads

• GIVEN enable_auto_ads === true
• WHEN se evaluan las ubicaciones de anuncios
• THEN los siguientes grupos DEBEN comportarse como si estuvieran desactivados:
  • incontent_advanced (In-Content Ads Avanzado)
  • behavior (Ubicaciones en Posts) - EXCEPTO javascript_first_mode
  • anchor_ads (Anuncios Fijos)
  • vignette_ads (Anuncios de Vineta)
  • layout (Ubicaciones Archivos/Globales)
• AND el grupo search_results DEBE permanecer activo
• AND el grupo analytics DEBE permanecer activo
• AND el grupo content (credenciales) DEBE permanecer activo

Scenario: Preservacion de configuracion en base de datos

• GIVEN el usuario activa enable_auto_ads
• WHEN se guardan los settings
• THEN los valores de los campos desactivados NO DEBEN modificarse en la BD
• AND cuando el usuario desactive enable_auto_ads, sus configuraciones previas DEBEN estar intactas

Scenario: Evaluacion en PHP (Server-Side)

• GIVEN enable_auto_ads === true en los settings
• WHEN un Renderer evalua si debe insertar un slot de anuncio
• THEN DEBE verificar primero si enable_auto_ads esta activo
• AND si esta activo, DEBE retornar inmediatamente sin insertar el slot manual
• AND EXCEPTO para slots del grupo search_results

Scenario: Evaluacion en JavaScript (Client-Side)

• GIVEN JavaScript-First Mode esta activo
• AND enable_auto_ads === true
• WHEN el controller JavaScript evalua visibilidad
• THEN DEBE incluir enable_auto_ads en el response del endpoint REST
• AND el script DEBE ocultar slots manuales marcados con data-ad-manual
• AND NO DEBE ocultar slots marcados con data-ad-search

---

Requirement: Excepcion para ROI APU Search

Los anuncios en resultados de busqueda DEBEN permanecer activos independientemente del estado de Auto Ads.

Scenario: Configuracion de busqueda siempre disponible

• GIVEN enable_auto_ads === true
• WHEN se obtiene la configuracion para el plugin roi-apu-search via roi_get_adsense_search_config()
• THEN DEBE retornar la configuracion del grupo search_results
• AND search_ads_enabled DEBE evaluarse independientemente de enable_auto_ads

Scenario: Slots de busqueda con atributo especial

• WHEN se renderizan slots de anuncios para resultados de busqueda
• THEN DEBEN incluir atributo data-ad-search="true"
• AND DEBEN incluir clase CSS roi-ad-search-slot
• AND NO DEBEN incluir atributo data-ad-manual

Scenario: JavaScript no oculta slots de busqueda

• GIVEN el controller JavaScript detecta enable_auto_ads === true
• WHEN procesa los slots de anuncios
• THEN NO DEBE agregar clase roi-ad-hidden a elementos con data-ad-search
• AND DEBE disparar evento roi-adsense-activate para slots de busqueda

---

Requirement: CSS para Excluir Tablas de Auto Ads

El sistema DEBE inyectar CSS que indica a Google Auto Ads que NO inserte anuncios dentro de tablas.

Scenario: Inyeccion de CSS google-auto-ads ignore

• GIVEN enable_auto_ads === true
• WHEN se renderiza el header del sitio
• THEN DEBE inyectar el siguiente CSS:

table,
.wp-block-table,
.tablepress,
figure.wp-block-table,
.entry-content table {
  google-auto-ads: ignore;
}

• AND el CSS DEBE cargarse ANTES del script de AdSense

Scenario: CSS solo cuando Auto Ads esta activo

• GIVEN enable_auto_ads === false
• WHEN se renderiza el header
• THEN NO DEBE inyectar el CSS de google-auto-ads: ignore

Scenario: Selectores adicionales configurables

• GIVEN el usuario necesita excluir elementos adicionales
• WHEN existe un campo auto_ads_exclude_selectors en el schema
• THEN DEBE agregar esos selectores al CSS de exclusion
• AND el campo DEBE ser de tipo textarea
• AND DEBE tener default vacio

---

Requirement: Script de Google Auto Ads

Cuando Auto Ads esta activo, el sistema DEBE insertar el script requerido por Google.

Scenario: Insercion del script adsbygoogle

• GIVEN enable_auto_ads === true
• AND is_enabled === true
• WHEN se renderiza el head del documento
• THEN DEBE insertar el script de AdSense:

<script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-XXXXXXXXXX"
     crossorigin="anonymous"></script>

• AND DEBE usar el publisher_id configurado en el grupo content

Scenario: No duplicar scripts

• GIVEN el tema ya encola el script de AdSense para ubicaciones manuales
• WHEN enable_auto_ads === true
• THEN NO DEBE duplicar el script
• AND DEBE reutilizar el script existente

Scenario: Delay de carga respetado

• GIVEN delay_enabled === true en el grupo forms
• AND enable_auto_ads === true
• WHEN se carga la pagina
• THEN el script de AdSense DEBE cargarse con delay
• AND DEBE respetar el valor de delay_timeout

---

Requirement: Indicador Visual en Admin UI

El panel de administracion DEBE mostrar claramente cuando Auto Ads esta activo.

Scenario: Badge de estado Auto Ads

• GIVEN el usuario accede al panel de configuracion de AdSense
• WHEN enable_auto_ads === true
• THEN DEBE mostrar un badge visible "AUTO ADS ACTIVO" en color naranja (#FF8600)
• AND los grupos desactivados DEBEN aparecer con opacidad reducida (0.5)
• AND los grupos desactivados DEBEN mostrar tooltip "Desactivado por Auto Ads"

Scenario: Seccion de grupos no afectados

• GIVEN enable_auto_ads === true
• WHEN se renderiza el formulario
• THEN los grupos search_results, analytics, y content DEBEN renderizarse normalmente
• AND DEBEN tener indicador "Siempre activo" visible

Scenario: Confirmacion al activar

• GIVEN el usuario hace click en enable_auto_ads
• WHEN el campo cambia de false a true
• THEN DEBE mostrar dialogo de confirmacion con mensaje: "Al activar Auto Ads, Google controlara automaticamente donde mostrar anuncios. Tus configuraciones manuales se mantendran guardadas pero no se usaran. Los anuncios en resultados de busqueda seguiran funcionando. Continuar?"
• AND DEBE tener botones "Activar Auto Ads" y "Cancelar"

---

Requirement: Separacion de Capas segun Clean Architecture

La implementacion DEBE seguir Clean Architecture.

Scenario: Value Object AutoAdsConfiguration en Domain

• WHEN se crea el Value Object AutoAdsConfiguration
• THEN DEBE ubicarse en Shared/Domain/ValueObjects/
• AND DEBE ser inmutable despues de construccion
• AND DEBE exponer isAutoAdsEnabled(), getExcludedSelectors(), getPublisherId()
• AND NO DEBE contener logica de WordPress

Scenario: Interface en Domain

• WHEN se define el contrato para verificar si un grupo esta activo
• THEN DEBE existir metodo en AdsenseSettingsInterface: isGroupActiveWithAutoAds(string $groupName): bool
• AND DEBE retornar false para grupos manuales cuando Auto Ads esta activo
• AND DEBE retornar true para search_results, analytics, content

Scenario: Service en Infrastructure

• WHEN se implementa la logica de evaluacion
• THEN el AdsenseSettingsService DEBE verificar enable_auto_ads antes de evaluar ubicaciones
• AND DEBE exponer metodo getActiveGroups(): array que retorna solo grupos activos

---

Requirement: Endpoint REST para Estado de Auto Ads

El endpoint de visibilidad DEBE informar el estado de Auto Ads.

Scenario: Inclusion en response de visibility

• GIVEN el endpoint /wp-json/roi-theme/v1/adsense-placement/visibility
• WHEN responde exitosamente
• THEN DEBE incluir campo auto_ads_enabled: boolean
• AND DEBE incluir campo auto_ads_exclude_selectors: string

Scenario: Response cuando Auto Ads esta activo

• GIVEN enable_auto_ads === true
• WHEN se llama al endpoint
• THEN el response DEBE incluir:

{
  "show_ads": true,
  "auto_ads_enabled": true,
  "auto_ads_exclude_selectors": "table,.wp-block-table",
  "manual_slots_disabled": true,
  "search_slots_enabled": true,
  "reasons": [],
  "cache_seconds": 300,
  "timestamp": 1733900000
}

---

Requirement: Migracion y Retrocompatibilidad

La implementacion DEBE mantener compatibilidad con instalaciones existentes.

Scenario: Valor default para instalaciones existentes

• GIVEN una instalacion existente sin el campo enable_auto_ads
• WHEN se ejecuta sync-component
• THEN DEBE crear el campo con valor false
• AND el comportamiento existente NO DEBE cambiar

Scenario: Sin cambios en logica si Auto Ads esta desactivado

• GIVEN enable_auto_ads === false
• WHEN se evaluan ubicaciones de anuncios
• THEN el comportamiento DEBE ser identico al actual
• AND NO DEBE haber impacto en rendimiento

---

Requirement: Logging y Diagnostico

El sistema DEBE proveer informacion de diagnostico para troubleshooting.

Scenario: Log cuando Auto Ads ignora ubicacion

• GIVEN enable_auto_ads === true
• AND WP_DEBUG === true
• WHEN un Renderer es llamado para ubicacion manual
• THEN DEBE loguear mensaje: "AdSense: Skipping manual slot '{slot_name}' - Auto Ads active"
• AND el log DEBE ser level DEBUG

Scenario: Comentario HTML de diagnostico

• GIVEN enable_auto_ads === true
• AND WP_DEBUG === true
• WHEN se renderiza el header
• THEN DEBE incluir comentario HTML:

<!-- ROI AdSense: Auto Ads Mode Active | Manual slots: disabled | Search slots: enabled -->

---

Implementation Notes

Schema Changes (adsense-placement.json)

Agregar al grupo visibility:

"enable_auto_ads": {
  "type": "boolean",
  "label": "Activar Google Auto Ads",
  "default": false,
  "editable": true,
  "description": "Google controla automaticamente la ubicacion de anuncios. Se desactivan ubicaciones manuales excepto busqueda."
}

Agregar al grupo forms (nuevo campo):

"auto_ads_exclude_selectors": {
  "type": "textarea",
  "label": "Selectores adicionales a excluir de Auto Ads",
  "default": "",
  "editable": true,
  "description": "Selectores CSS adicionales donde Auto Ads no debe insertar anuncios (uno por linea)"
}

CSS Default Exclusions

/* Elementos que Google Auto Ads debe ignorar */
table,
.wp-block-table,
.tablepress,
figure.wp-block-table,
.entry-content table,
.roi-apu-results,
.roi-apu-result-item,
pre,
code,
.wp-block-code,
.syntax-highlighted {
  google-auto-ads: ignore;
}

Grupos y su comportamiento con Auto Ads

Grupo	Con Auto Ads OFF	Con Auto Ads ON
visibility	Activo	Activo (controla is_enabled global)
analytics	Activo	Activo
content	Activo	Activo (provee publisher_id)
incontent_advanced	Activo	IGNORADO
behavior	Activo	IGNORADO (excepto javascript_first_mode)
anchor_ads	Activo	IGNORADO
vignette_ads	Activo	IGNORADO
search_results	Activo	ACTIVO (excepcion)
layout	Activo	IGNORADO
forms	Activo	Activo (delay, exclusiones)

---

Validation Checklist

Antes de considerar esta especificacion implementada:

• Campo enable_auto_ads existe en schema y BD
• Campo auto_ads_exclude_selectors existe en schema y BD
• CSS de exclusion se inyecta solo cuando Auto Ads activo
• Slots manuales no se renderizan cuando Auto Ads activo
• Slots de busqueda SI se renderizan cuando Auto Ads activo
• roi_get_adsense_search_config() funciona independiente de Auto Ads
• Admin UI muestra indicador visual de Auto Ads activo
• Grupos desactivados aparecen con opacidad reducida
• Endpoint REST incluye auto_ads_enabled en response
• JavaScript oculta slots manuales pero no de busqueda
• Script de AdSense se carga correctamente
• No hay duplicacion de scripts
• Logs de debug funcionan cuando WP_DEBUG activo
• Sync-component migra correctamente instalaciones existentes