WooCommerce widget bridge

Most WooCommerce stores need zero configuration — the plugin handles everything. The widget bridge matters when you have a custom theme, custom add-to-cart flow, or a multi-currency setup where the widget needs explicit shopper context to give correct answers.

What the bridge does

It’s a tiny JavaScript surface the plugin exposes on every storefront page. It pushes WooCommerce session state into a global the widget reads on boot:

• Cart token + current cart contents and value.
• Customer identity when the shopper is logged in (email, WordPress user ID).
• Currency, locale, and tax region based on the active WooCommerce session.
• Page context — product ID on a product page, collection slug on a category page, etc.

How the plugin emits it

On every page load the plugin echoes a small inline script (after WooCommerce’s own session initialization) that looks like this:

<script>
  window.Zubby = window.Zubby || {};
  window.Zubby.context = {
    customer: {
      email:    "shopper@example.com",   // null when guest
      wpUserId: 42,                       // null when guest
      isVip:    false
    },
    cart: {
      token:    "ck_abc...",
      currency: "USD",
      items:    [
        { sku: "TSHIRT-BLU-M", qty: 1, price: "29.00" }
      ],
      subtotal: "29.00"
    },
    page: {
      type: "product",        // home | product | category | cart | checkout | other
      productId: 1234,
      categorySlug: null
    },
    locale: "en_US"
  };
</script>

When you need to override it

Three common scenarios. In each case the answer is to call window.Zubby.update() after your custom logic finishes.

1. 1

   Custom add-to-cart

   If your theme uses AJAX add-to-cart that bypasses woocommerce_add_to_cart hooks, push the new cart line into the bridge manually:

   js

   document.addEventListener("custom:cart-added", (e) => {
     window.Zubby.update({
       cart: {
         token: e.detail.token,
         items: e.detail.items,
         subtotal: e.detail.subtotal
       }
     });
   });

   Copy
2. 2

   Multi-currency switcher

   If you use a plugin like CURCY or Aelia to switch currencies on the fly, call update() after the switch:

   js

   document.addEventListener("currency:switched", (e) => {
     window.Zubby.update({ cart: { currency: e.detail.code } });
   });

   Copy
3. 3

   Headless storefront

   On headless WooCommerce (e.g. Next.js + WP-GraphQL), there’s no WordPress server rendering the inline script. Build the context object yourself before loading the widget loader.

Identity stitching

When a logged-in customer opens the widget, Zubby stitches the anonymous session ID to the WordPress user. After that, the agent knows their order history, lifecycle stage, VIP status, and any wishlist items. Stitching happens automatically as long as the bridge emits the customer.email field — no extra code.

Disable the bridge

Some stores prefer to ship the widget completely anonymous. Toggle off Forward customer context under Settings → Zubby AI → Privacy. The bridge then emits only the cart token and page type — no customer fields.

Debugging

From the browser console:

// Inspect what the widget will read on next boot
console.log(window.Zubby?.context);

// Force a re-bootstrap with the current context
window.Zubby?.reload();

If window.Zubby is undefined, the loader didn’t run. Check the embed; see Widget not loading.