Recipe: WooCommerce end-to-end

Esta guía monta una tienda WooCommerce con búsqueda semántica, sync de catálogo, cart bridge y tracking de conversiones, todo en menos de 30 minutos. Usaremos el plugin oficial neuroon-search v0.8.4.

Si lo que buscas es el plugin para agentes de IA (UCP, Google Search AI Mode), ése se llama neuroon-agentic-commerce v0.1.0 y es un producto separado.

Tiempo estimado: 20-30 min.

Prerrequisitos

• WordPress 5.8+ (probado hasta 6.7) con WooCommerce 6.0+ (probado hasta 9.4) en PHP 7.4+.
• Acceso de administrador (manage_options).
• Una API Key generada desde el dashboard (Production o Development).
• Acceso por SSH / SFTP al servidor (opcional, solo para wp-cli / wp-config.php).

Esta guía usa el entorno Development por defecto (dev.neuroon.ai). Conmuta a Production con el switch superior cuando estés listo.

Paso 1. Instalar el plugin

# Opción A: WP-CLI
wp plugin install /path/to/neuroon-search-0.8.4.zip --activate

# Opción B: vía wp-admin
# Plugins → Add New → Upload Plugin → selecciona el ZIP → Install Now → Activate

Tras activar, verás el menú Settings → Neuroon Search. Solo será visible la pestaña Settings hasta que verifiques el dominio (progressive disclosure).

Paso 2. (Opcional) Apuntar a Development

Solo si vas a probar contra dev.neuroon.ai antes de producción. Añade en wp-config.php:

define('NEUROON_API_BASE_URL', 'https://dev.neuroon.ai/api');

Paso 3. Configurar credenciales

1. Settings → Neuroon Search → Settings tab.
2. API Key: pega la key (Bearer token).
3. Shop ID (opcional, se rellena automáticamente al verificar).
4. Pulsa Save.

Paso 4. Verificar el dominio

Pulsa Verify Domain. El plugin verifica automáticamente que el dominio actual coincide con el shop.url ya registrado en Neuroon — no es una llamada que tengas que construir tú. Si coincide, las pestañas Products, Widget y Diagnostics se habilitan al instante.

Paso 5. Sync inicial del catálogo

1. Settings → Neuroon Search → Products tab.
2. Select all (o filtra por categoría / estado).
3. Pulsa Sync selected.

El plugin sincroniza los productos seleccionados en lotes de 100 y va actualizando una barra de progreso hasta terminar.

Latencia: los productos sincronizados se indexan en Neuroon en 2 a 5 segundos.

Paso 6. Embebido del widget

El plugin inyecta automáticamente el script del widget si en Widget tab tienes activado Auto-embed.

Si quieres embebido manual (por ejemplo en un tema custom), usa el shortcode [neuroon_search] en cualquier página o bloque.

Paso 7. Cart bridge

No tienes que hacer nada para activarlo: el plugin mantiene la vista de carrito del widget sincronizada automáticamente y dispatcha neuroon:cart-update cada vez que el carrito cambia.

Validación rápida en consola del navegador:

window.addEventListener('neuroon:cart-update', e => console.log(e));
// Pulsa "Add to cart" en una página de producto

Paso 8. Tracking de conversiones

Si usas el plugin oficial no tienes que escribir ni configurar nada: el propio plugin engancha el checkout de WooCommerce y reporta cada pedido completado a Neuroon automáticamente.

Si necesitas un tracking de conversiones manual — por ejemplo, una integración custom que no pasa por el plugin — consulta la receta Conversion tracking.

Paso 9. Verificar la integración

# 1) Comprueba el shop info
curl -s "https://api.neuroon.ai/api/integrations/v1/shop" \
-H "Authorization: Bearer $NEUROON_API_KEY" \
-H "Origin: https://your-shop.example"

# 2) Recupera 5 productos sincronizados
curl -s "https://api.neuroon.ai/api/integrations/v1/products?size=5" \
-H "Authorization: Bearer $NEUROON_API_KEY" \
-H "Origin: https://your-shop.example"

# 3) Lanza una búsqueda usando el widget token (impreso en data-token)
curl -s "https://api.neuroon.ai/api/widget/search?q=camiseta&limit=3" \
-H "X-Widget-Token: $WIDGET_TOKEN"

Errores frecuentes

Síntoma	Causa	Solución
Verify Domain falla con 403	El dominio actual no coincide con shop.url registrado	Reconcilia el dominio canónico (apex vs www.).
Sync queda parado en PROCESSING	Timeout PHP-FPM (max_execution_time)	Aumenta a 60 s.
429 durante sync masiva	Rate limit sync (100/min) saturado	El plugin respeta Retry-After; espera y reintenta.
Widget no carga, integrity mismatch	El SRI no coincide con la versión del widget	Recalcula el SRI con openssl dgst -sha384 -binary.
Productos no aparecen en búsqueda	Latencia de indexación 2-5 s	Espera 5 s y reintenta.
Tracking no impacta dashboard	Adblocker bloquea un pixel client-side	El tracking del plugin ya es server-side por defecto; revisa que la API Key y el dominio verificado sean correctos.

Siguientes pasos

• plugins/wordpress/admin-dashboard — pestañas y AJAX.
• plugins/wordpress/product-sync — modos FULL / INCREMENTAL.
• Recipe · Conversion tracking — patrones cross-stack.
• Authentication · API Key.