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 Shop API Key generada desde el dashboard (Production o Development).
• Acceso por SSH / SFTP al servidor (opcional, solo para wp-cli / wp-config.php).

Cita: requisitos verificados en .

Esta guía usa el entorno Development por defecto (dev-api.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-api.neuroon.ai antes de producción. Añade en wp-config.php:

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

Cita: neuroon_get_api_url() en .

Paso 3. Configurar credenciales

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

Las credenciales se guardan en wp_options (neuroon_api_key, neuroon_shop_id). En entornos compartidos, considera definirlas como constantes en wp-config.php con un filtro propio.

Paso 4. Verificar el dominio

Pulsa Verify Domain. El plugin dispara:

POST /api/plugin/shops/verify HTTP/1.1
X-Shop-API-Key: sk_xxx
Origin: https://your-shop.example
Content-Type: application/json

{"domain": "https://your-shop.example"}

El backend compara normalizeUrl(domain) con el shop.url ya registrado. Si coincide, devuelve shopId, verificationCode y datos del shop. Las pestañas Products, Widget y Diagnostics se habilitan al instante.

Cita: flujo descrito en wordpress-plugin/CLAUDE.md y handler admin_post_neuroon_verify.

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.

Lo que pasa por debajo:

• El plugin marca los seleccionados como PENDING en wp_neuroon_product_sync.
• AJAX dispara neuroon_start_sync, que llama a neuroon_sync_batch en lotes de 50 productos por defecto (Neuroon_Constants::DEFAULT_BATCH_SIZE = 50, configurable hasta 500 vía la opción neuroon_batch_size).
• Cada batch envía POST /api/plugin/shops/{shopId}/products/sync con syncType: "INCREMENTAL".
• La UI pollea neuroon_sync_status y actualiza la barra de progreso.

Cita: tabla wp_neuroon_product_sync, AJAX endpoints y batch size en wordpress-plugin/CLAUDE.md.

Latencia: tras el 200 OK, los productos 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. La constante usada:

define('NEUROON_WIDGET_VERSION',  '0.9.10');
define('NEUROON_WIDGET_SRI_HASH', 'sha384-JTaG/IN0Jj/ImfUj2x5QVMG4HkbFHzui7fTpLtwl1hsP+kY9W8OODeSJRFWN1ZP5');

Cita: .

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 engancha jQuery a los eventos de WooCommerce y dispatcha neuroon:cart-update con debounce 200 ms.

var wcCartEvents = 'added_to_cart removed_from_cart updated_wc_div ' +
                   'updated_cart_totals wc_fragments_refreshed ' +
                   'wc_fragments_loaded wc_cart_emptied';

Cita: .

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

Recomendado: usar el hook woocommerce_thankyou para llamar al endpoint server-side y no perder ventas con adblockers:

add_action('woocommerce_thankyou', function ($order_id) {
    if (!$order_id) return;

    $order = wc_get_order($order_id);
    if (!$order) return;

    $payload = [
        'orderId'     => (string) $order->get_id(),
        'orderValue'  => (float) $order->get_total(),
        'currency'    => $order->get_currency(),
        'conversions' => array_map(function ($item) {
            return [
                'productId' => (string) $item->get_product_id(),
                'quantity'  => (int) $item->get_quantity(),
                'lineTotal' => (float) $item->get_total(),
            ];
        }, array_values($order->get_items())),
    ];

    $shop_id  = get_option('neuroon_shop_id');
    $api_key  = get_option('neuroon_api_key');
    $base_url = defined('NEUROON_API_BASE_URL') ? NEUROON_API_BASE_URL : 'https://api.neuroon.ai/api';

    wp_remote_post("$base_url/api/plugin/shops/$shop_id/track/conversion", [
        'headers' => [
            'X-Shop-API-Key' => $api_key,
            'Origin'         => get_site_url(),
            'Content-Type'   => 'application/json',
        ],
        'body'    => wp_json_encode($payload),
        'timeout' => 10,
    ]);
}, 20, 1);

Si tu tienda usa un constructor de pedidos custom, engancha el handler donde marques el pedido como pagado / completado, no en thankyou.

Paso 9. Verificar la integración

# 1) Comprueba el shop info
curl -s "https://dev-api.neuroon.ai/api/plugin/shops/me" \
  -H "X-Shop-API-Key: $NEUROON_API_KEY" \
  -H "Origin: https://your-shop.example"

# 2) Recupera 5 productos sincronizados
curl -s "https://dev-api.neuroon.ai/api/plugin/shops/$NEUROON_SHOP_ID/products?size=5" \
  -H "X-Shop-API-Key: $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://dev-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; el plugin ya pausa 100 ms entre lotes.
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 el pixel	Usa el hook woocommerce_thankyou server-side (Paso 8).

Siguientes pasos

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