In this section
Resources / Developers / Embed
Embed script reference
Every attribute and query parameter of the Hubbo embed script, plus what happens when it boots.
The embed script is served from https://api.hubbo.io/embed. It is a JavaScript ES module that creates the Hubbo widget host on your page. The same tag works in HTML shells and SPA frameworks (React, Vue, Next.js, Nuxt, Svelte, Angular) — see the Installation guides.
Canonical tag
<script src="https://api.hubbo.io/embed?key=ACCOUNT_KEY" id="hubbo-embed-script" async type="module" crossorigin="use-credentials"></script>Script tag attributes
| Attribute | Required | Notes |
|---|---|---|
| src | Yes | https://api.hubbo.io/embed with query parameters (see below). |
| id | Yes | Must be hubbo-embed-script. The bundle reads its own query string from this element. |
| type | Yes | module |
| async | Recommended | Does not block HTML parsing. |
| crossorigin | Yes | use-credentials, so the browser accepts the project key cookie and sends cookies on later requests. |
Query parameters
| Parameter | Used for | Description |
|---|---|---|
| key | All modes | Your account key. Required. |
| roadmap | Roadmap mode | ID of a published roadmap. When present, the script mounts only the roadmap Web Component (see Roadmap embed). |
| mount | Roadmap mode | CSS selector of the element to mount into, URL-encoded (for example %23product-roadmap for #product-roadmap). Defaults to document.body. |
| mode | Roadmap mode | inline (default) or iframe. |
| cookieOnly | Internal | When present together with key, the endpoint only sets the project key cookie and returns an empty script. The widget uses it to prime the cookie before calling GraphQL. |
What the script does on load
- Registers the
hubbo-roadmapcustom element. - If the
roadmapparameter is present, mounts the roadmap and stops. Otherwise creates a fixed, full-viewport host element with idhubbo-embedand attaches an open Shadow DOM to it. The host ignores pointer events itself, only the widgets are interactive. - Calls
client_getCurrentAccount. This is the first GraphQL call, it counts the session as a page view and returnsusageAllowed. - If
usageAllowedis not false, mounts notifications first, then NPS and surveys after a short delay to keep the number of parallel requests low. - Subscribes to account updates over WebSocket so appearance changes made in the admin app show up live.
Style isolation
Widget styles live in the Shadow DOM. Your site CSS does not leak into Hubbo widgets, and Hubbo CSS does not leak into your page.
Presentation queue, stacking and top bar offset
The hubbo-embed host is position: fixed with z-index: 2147483000. Auto-shown surfaces (popup, survey, NPS, toast) share a mutual-exclusion queue — only one of those runs at a time, with a short leave animation before the next enters (priority: popup → survey → NPS → toast). The bell, tooltip and top bar stay outside that queue so the launcher remains reachable. A host overlay on your page with a higher z-index can still cover Hubbo. The top bar spans nearly the full viewport with a 5px inset from the top and sides; it sets the CSS variable --hubbo_topBarsHeight on <html> to the distance from the top of the viewport to the bottom of the bar (0px when none), which you can use to offset a sticky header. See Install with the HTML snippet.
Cookies
The response to /embed?key=... sets hubbo_api_key (httpOnly, Secure, SameSite=None) and includes Access-Control-Allow-Credentials: true. Page-view session state is stored in hubbo_pv_* cookies, also httpOnly. Guest chat on the notification page may also set hubbo_chat_*. See Cookies, CORS and credentials.
One script per page
The id is how the script finds its parameters
Because the bundle looks up the element by id, include only one hubbo-embed-script per page. If you need both the standard widgets and a roadmap on the same page, use the standard snippet for widgets and the roadmap iframe URL for the board.
Visitor identity (optional)
After the script loads, your app may call window.hubbo.identify({ id }) so Targeting can gate widgets on logged-in vs anonymous visitors. Full details: Identify visitors.
Visitor language (optional)
Call window.hubbo.setLang('pl') when your product locale changes so notifications, NPS and surveys use the matching translation overlay. Clear with setLang(null). Full details: Set visitor language.
Not available
- No
Hubbo.init()and no configuration through data attributes on the script tag. Behavior is configured in the admin app. - No official GTM or npm package.