Saltar al contenido principal

WordPress · Cart bridge

El cart bridge mantiene al widget en sintonía con el carrito de WooCommerce. Cuando un cliente añade, quita o vacía el carrito, el plugin emite un CustomEvent('neuroon:cart-update') en window. El widget escucha ese evento y refresca sus respuestas (cross-sell, validaciones, prompts).

No tienes que hacer nada para activar el bridge: el plugin lo wirea automáticamente cuando carga el widget en la página. Cobertura medida internamente: ~95 % de las mutaciones del carrito en una WC estándar.

Eventos jQuery suscritos​

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

Cita: .

WooCommerce dispara varios eventos en cascada (p. ej. added_to_cart + wc_fragments_refreshed casi a la vez). Para evitar floods, el plugin aplica debounce de 200 ms:

function onWcCartEvent() {
    if (wcDebounceTimer) clearTimeout(wcDebounceTimer);
    wcDebounceTimer = setTimeout(function () {
        window.dispatchEvent(new CustomEvent('neuroon:cart-update'));
    }, 200);
}

Cita: .

Configuración del widget​

El nombre del evento está expuesto vía la config inline del widget:

'externalUpdateEvent' => 'neuroon:cart-update'

Cita: .

Si necesitas cambiarlo (p. ej. para evitar colisión con otro listener), filtra la config antes de imprimirla.

Payload​

El plugin emite el evento sin payload (detail ausente). El widget pide al servidor el estado actualizado del carrito a través de la API de WooCommerce vía AJAX (fragments) o consulta directamente el endpoint público de WC. Esto evita exponer datos sensibles desde scripts inline.

Si tienes un caso especial (carrito en JSON propio, headless WC, etc.), puedes emitir tu propio evento con detail:

window.dispatchEvent(new CustomEvent('neuroon:cart-update', {
  detail: {
    items: [
      { productId: 'PRD-001', name: 'Smart Speaker', price: 79.99, quantity: 2 }
    ],
    total: 159.98,
    currency: 'EUR'
  }
}));

El widget acepta ambos modos.

Robustez frente a jQuery diferido​

WooCommerce engancha sus eventos sobre jQuery(document.body). En tiendas con jQuery cargado en defer o muy tarde, el plugin reintenta el attach hasta 10 veces a intervalos de 500 ms (5 s totales). Si tras eso jQuery sigue ausente, el bridge queda inactivo y se loguea un warning en consola.

Cita: bloque attachWcCartSync en wordpress-plugin/neuroon-search/includes/widget/class-neuroon-widget-manager.php (líneas ~907-925).

Validar que el bridge funciona​

  1. Abre la consola del navegador en una página con producto.
  2. Suscríbete: 
    window.addEventListener('neuroon:cart-update', e => console.log('cart-update', e));
  3. Pulsa Add to cart. Deberías ver el log ~200 ms después.

Si no ves el evento:

  • Comprueba que jQuery está cargado (typeof jQuery !== 'undefined' en consola).
  • Verifica que el widget está activo (la config inline debe imprimir el bloque <script> con externalUpdateEvent).
  • Mira la pestaña Diagnostics del plugin para ver si el bridge está marcado como attached.

Cuándo NO usar este bridge​

  • Headless WooCommerce / Storefront propio: tu propio frontend ya conoce el estado del carrito; emite tu propio CustomEvent directamente. Ver recipes/custom-cart-bridge.
  • Carritos completamente AJAX externos (ej. mini-cart hecho en React montado fuera de WC): igual que arriba, dispatcha tú.

Próximos pasos​

Última actualización en