Skip to main content

WordPress · Cart bridge

The cart bridge keeps the widget in sync with the WooCommerce cart. When a customer adds, removes or empties the cart, the plugin emits a CustomEvent('neuroon:cart-update') on window. The widget listens for that event and refreshes its responses (cross-sell, validations, prompts).

You do not have to do anything to enable the bridge: the plugin wires it up automatically when it loads the widget on the page. Internally measured coverage: ~95 % of cart mutations on a standard WC.

Subscribed jQuery events​

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

Citation: .

WooCommerce fires several events in cascade (e.g. added_to_cart + wc_fragments_refreshed almost simultaneously). To avoid floods, the plugin applies a 200 ms debounce:

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

Citation: .

Widget configuration​

The event name is exposed via the widget inline config:

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

Citation: .

If you need to change it (e.g. to avoid a collision with another listener), filter the config before printing it.

Payload​

The plugin emits the event without payload (detail absent). The widget asks the server for the updated cart state through the WooCommerce AJAX API (fragments) or queries the public WC endpoint directly. This avoids exposing sensitive data from inline scripts.

If you have a special case (cart in custom JSON, headless WC, etc.), you can emit your own event with 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'
  }
}));

The widget accepts both modes.

Robustness against deferred jQuery​

WooCommerce hooks its events on jQuery(document.body). On shops with jQuery loaded with defer or very late, the plugin retries the attach up to 10 times at 500 ms intervals (5 s total). If after that jQuery is still missing, the bridge stays inactive and a warning is logged in the console.

Citation: attachWcCartSync block in wordpress-plugin/neuroon-search/includes/widget/class-neuroon-widget-manager.php (lines ~907-925).

Validate that the bridge works​

  1. Open the browser console on a product page.
  2. Subscribe: 
    window.addEventListener('neuroon:cart-update', e => console.log('cart-update', e));
  3. Click Add to cart. You should see the log ~200 ms later.

If you do not see the event:

  • Check that jQuery is loaded (typeof jQuery !== 'undefined' in console).
  • Verify that the widget is active (the inline config must print the <script> block with externalUpdateEvent).
  • Look at the plugin's Diagnostics tab to see whether the bridge is marked as attached.

When NOT to use this bridge​

  • Headless WooCommerce / custom storefront: your own frontend already knows the cart state; emit your own CustomEvent directly. See recipes/custom-cart-bridge.
  • Fully external AJAX carts (e.g. mini-cart built in React mounted outside WC): same as above, dispatch yourself.

Next steps​

Last updated on