Embed the widget on Shopify

Once your store is paired, you need to render the widget on the storefront. There are two paths. App Embed is the right choice for 95% of stores — it’s a no-code toggle inside the theme editor. The universal snippet is for headless or hyper-customized themes where the App Embed isn’t the right fit.

Option 1 — App Embed (recommended)

The App Embed is a theme app extension. It runs only on Online Store 2.0 themes (Dawn and every theme published after July 2021). If you’re still on a Vintage theme, jump to the universal snippet option below.

1. 1

   Open the theme editor

   From your Shopify admin go to Online Store → Themes → Customize on the active theme.
2. 2

   Open the App embeds panel

   Click the puzzle-piece App embeds icon in the left rail. Shopify lists every installed app extension here.
3. 3

   Toggle Zubby AI Chat

   Find Zubby AI Chat and switch the toggle to on. The preview updates immediately.
4. 4

   Adjust position (optional)

   The block exposes a few settings: corner alignment, mobile offset, and a kill-switch for specific page templates (e.g. hide on the cart page). Default values match what most stores want.
5. 5

   Save the theme

   Click Save in the top-right. Changes are live the moment you save.

Option 2 — Universal snippet

For headless storefronts (Hydrogen, Next.js Storefront API) or for stores on Vintage themes, paste the universal snippet just before </body>.

<script
  src="https://cdn.zubbyai.com/widget/v1/loader.js"
  data-store-id="YOUR_STORE_ID"
  data-widget-key="YOUR_WIDGET_KEY"
  async
></script>

Both values are visible at Dashboard → Widget → Embed. The widget key is rotatable if leaked.

Pass shopper context (advanced)

For accurate identity stitching across logged-in customers, push the customer email and cart token into the global before the loader runs. The widget picks them up and threads them through the conversation.

<script>
  window.Zubby = window.Zubby || {};
  window.Zubby.context = {
    customer: { email: "{{ customer.email }}", id: "{{ customer.id }}" },
    cart:     { token: "{{ cart.token }}", currency: "{{ cart.currency.iso_code }}" },
    locale:   "{{ localization.language.iso_code }}"
  };
</script>
<script src="https://cdn.zubbyai.com/widget/v1/loader.js" async></script>

Verify the launcher

Open your storefront in a new tab. The launcher should appear in the bottom-right within two seconds. If it doesn’t:

• Open DevTools. Check for a 401 on /api/v1/widget/bootstrap — if you see one, the widget key is wrong.
• Confirm the App Embed toggle saved (Shopify’s theme editor occasionally swallows un-saved changes).
• See the full debugging playbook at Widget not loading.

Removing the widget

To hide the widget temporarily without uninstalling Zubby, just toggle the App Embed off in the theme editor. Conversations and analytics keep working in the dashboard; only the storefront launcher is hidden.