Widget overview
The widget is the surface where your shoppers actually talk to the AI. It’s a single embeddable script that renders one of four UI modes, all of which share the same conversation runtime, audience targeting, analytics, and brand styling. Pick a mode per page (or per device, or per audience) — they’re not mutually exclusive.
The four modes
Each mode trades off prominence vs. interruption. Most stores start with the launcher, then add inline placement on specific pages where the AI is a hero rather than an accessory.
| Mode | What it looks like | Best for |
|---|---|---|
| Launcher | Floating bubble in the bottom-right; expands into a panel on click. | Default. Always available, never intrusive. Use on every page. |
| Popup | Centered modal triggered by exit intent, time-on-page, or scroll depth. | High-intent moments: leaving the cart, dwelling on a product page. |
| Inline | Embedded inside a page section like any other block. | Landing pages, “quiz” pages, gift-finder funnels. |
| Fullscreen | Takes over the viewport, with brand chrome. | Mobile-first stores; dedicated /ask pages. |
How the widget boots
The loader script does three things on page load:
- Resolves the store ID + widget key. Either is pulled from the script’s
data-*attributes or fromwindow.Zubby.context. - POSTs to
/api/v1/widget/bootstrapwith the page URL, referrer, and visitor cookies. The SaaS evaluates audience rules and returns a config object: which mode to render, what theme, what starter prompts, and a short-lived session token. - Injects the React UI in a shadow DOM (so your storefront CSS can’t leak in and break it) and starts listening for shopper events.
Why a shadow DOM?
What the widget can see
Out of the box, the widget reads:
- The URL of the current page (path, query, fragment) — used for context, never logged with PII.
- The visitor cookie Zubby dropped on first visit (a short opaque ID, no PII).
- Anything you push via the
window.Zubby.contextglobal — cart, customer email, locale, page type.
It does not read form fields, password inputs, or any payment information. The agent can ask shoppers for their email during conversation; only that explicitly-typed input is captured.
What you can configure
From Dashboard → Widget, you can:
- Pick a mode and place. Different rules per page template (e.g. launcher on product pages, popup on exit from cart). See Audience rules.
- Style it — colors, typography, position, density, dark/light mode. See Designer & themes.
- Customize copy — launcher greeting, starter prompts, welcome message.
- Set a language strategy — auto-detect from the browser, force a locale, or offer a switcher. See Languages.
- Choose which tools the AI is allowed to call (e.g. disable order status lookups if you don’t want PII flowing).
Performance
The loader is roughly 14 KB gzipped. The full chat UI is lazy-loaded only after the shopper clicks the launcher, so first-paint impact on your storefront is negligible. We aim for under 30 ms of main-thread time during the initial page load, and we measure it on the public status page.
Where to go next
- Designer & themes — make it look like your brand.
- Audience rules — decide who sees what.
- Embed codes — paste it into any storefront.