SDK reference
Every script attribute and JavaScript method, in one place.
3Guide ships as two separate scripts. The Guidance script is 3Guide; the Analytics script is optional. See Installation options.
| Script | data-guideai-bundle | What it does |
|---|---|---|
https://cdn.3guideai.com/sdk/guideai.js | guidance | Chat bubble, guides, help hints, announcements, AI Assistant |
https://cdn.3guideai.com/sdk/guideai-tracking.js | tracking | Analytics, replays, feature flags. Invisible. |
Both need the same data-site-id and data-token. When both are loaded they share one window.guideai object.
The easiest way to set most attributes is the editor in Settings → SDK Installation, which builds the snippet for you. Some settings, such as the bubble label, icon and widget mode, can also be saved there and are applied on the next page load without changing your snippet.
Script attributes
Required
| Attribute | Value |
|---|---|
data-site-id | Your site's ID (or read it from storage with data-site-id-source, data-site-id-key and data-site-id-token-field, see Installation options) |
data-token | Your Public Token (pk_live_…) |
Connection
| Attribute | Default | Notes |
|---|---|---|
data-api-url | https://cdn.3guideai.com | 3Guide API address |
data-cdn-url | https://cdn.3guideai.com | Where knowledge base and assets load from |
data-disable-routes | none | Comma-separated paths where 3Guide stays completely off, e.g. /admin/*,/checkout |
Chat and bubble
| Attribute | Default | Notes |
|---|---|---|
data-widget-mode | set by Agent Blueprint | combined, guide, assistant, support or docs. Leave it out to let the dashboard decide. See chat modes. |
data-bubble-enabled | true | Show the chat bubble |
data-bubble-label | none | Text on the bubble, e.g. Help |
data-bubble-icon | robot | Mascot icon. Or set data-bubble-image to your own image URL. |
data-bubble-position | bottom-right | bottom-right, bottom-left or center (bottom-centre) |
data-bubble-bottom-offset | 0 | Percentage of screen height. Positive moves the launcher up, negative down. |
data-bubble-mode | drift | How the bubble moves: drift (gently floats) or crawl (moves along the page edges with speech messages) |
data-chat-expand-dock | right | Where the expanded chat docks: right, left or bottom |
data-chat-suggestions | How do I get started?, Show me around | Starter questions, separated by | |
data-chat-guidance-title / -text | built in | Welcome text in Guidance mode |
data-chat-assistant-title / -text | built in | Welcome text in Assistant mode |
data-live-support | true | Allow hand-off to a person |
data-headless | false | No built-in UI at all. Drive everything from your own code. See Use 3Guide with your own AI. |
data-voice-input | true | Mic button. false hides it. |
data-voice-reply | true | Read answers to recorded messages aloud. false hides it. |
data-live-voice | false | Live conversation button. true shows it. |
data-home-source | inline | Use published to load the Home configuration published from Experience Studio. The generated installation snippet sets this for you. |
Experience Studio buttons
When Home is enabled, any element can open a specific widget destination:
<button data-guideai-open="home">Get help</button>
<button data-guideai-open="assistant">Ask the Assistant</button>
<button data-guideai-open="demos">Browse demos</button>Use home, chat, guidance, assistant, demos, blog, updates or
support. The destination is ignored when its Home section is disabled.
Look and feel
| Attribute | Default |
|---|---|
data-theme-primary | #3b82f6 |
data-theme-text | #1a1a2e |
data-theme-background | #ffffff |
data-theme-font | system font |
data-color-scheme | light (or dark, auto) |
data-dark-primary, data-dark-background, data-dark-text, data-dark-text-secondary, data-dark-text-muted, data-dark-border, data-dark-surface, data-dark-surface-hover | built-in dark palette (used only when dark is active) |
data-bubble-background, data-bubble-background-hover, data-bubble-text-color, data-bubble-border, data-bubble-border-hover, data-bubble-shadow, data-bubble-shadow-hover, data-bubble-focus-ring | derived from the theme |
Guides and hints
| Attribute | Default | Notes |
|---|---|---|
data-guides-enabled | true | Allow guides to play |
data-auto-advance-on-target-click | true | Move to the next step when the user clicks the highlighted element |
data-chip-dismiss-seconds | 300 | How long a dismissed suggestion chip stays hidden |
data-hint-icon-color, data-hint-button-color, data-hint-button-text-color, data-hint-button-label | built in | Help hint colours and demo-button label. Hints are on by default; turn them off in Settings. |
data-help-hints-cache-ttl-ms | 86400000 (24 h) | How long hints are cached in the browser |
Announcements
| Attribute | Default | Notes |
|---|---|---|
data-announcement-surface | modal | modal, banner or drawer |
data-announcement-display-mode | auto | Default for announcements that don't set their own |
data-announcement-frequency | once | Default frequency |
data-announcement-auto-show-delay-ms | 500 | Delay before auto-showing |
data-announcement-close-on-backdrop | true | Close when the backdrop is clicked |
Settings chosen for an individual announcement in the Studio take priority.
Analytics and privacy
| Attribute | Default | Notes |
|---|---|---|
data-recording | false | Session replays (on the tracking script) |
data-geolocation | off | off, granted-only or prompt. Location otherwise comes from the IP address. |
data-idle-timeout | 20000 | Milliseconds before a visitor counts as idle |
data-session-timeout-ms | 1800000 | Inactivity before a new session starts (30 min) |
data-batch-size / data-batch-interval-ms | 50 / 30000 | How events are batched |
data-feedback-auto-prompt | false | Ask for feedback automatically |
JavaScript API
Everything is on window.guideai. It's available once the script has loaded. Wait for it with:
await window.guideai.ready()Identity
| Method | What it does |
|---|---|
initialize({ visitor, account }) | Identify the signed-in person and their account, with any properties |
identify(userId) | Switch to a stable user ID, merging earlier anonymous activity |
clearSession() | Forget the current person. Call on sign-out. |
Analytics
| Method | What it does |
|---|---|
track(name, properties?) | Send a business event, e.g. track('invoice_paid', { amount: 120 }). track('signup') and track('login') also start onboarding, even without the Analytics script. |
trackFeature(key, label?, properties?) | Record use of a feature |
pageLoad() | Record a page view manually, for routers 3Guide can't detect |
flushNow() | Send buffered events immediately |
optOut() / optIn() / isOptedOut() | Pause and resume tracking, e.g. for consent |
Feature flags
| Method | What it does |
|---|---|
isFeatureEnabled(key) | true if the flag is on for this visitor |
getFeatureFlag(key) | The flag's value or variant |
getFeatureFlagPayload(key) | Extra data attached to the flag |
reloadFeatureFlags() | Fetch flags again, e.g. after identify |
Guides
| Method | What it does |
|---|---|
validateGuideById(id) | Check a guide exists and can play |
showGuideById(id, stepIndex?) | Start a guide, optionally from a given step |
dismissGuide() | Close the guide that's playing |
Chat
| Method | What it does |
|---|---|
openChat(mode?, lockMode?, anchor?, compact?) | Open the chat, optionally in a mode, anchored to an element, compact or full. See your own button. |
openGuidance() / openAssistant() | Open it in a specific mode |
openDocsSearch(anchor?) / closeDocsSearch() | Open or close Docs mode search |
setColorScheme(scheme) | light, dark or auto |
refreshHelpHints() | Look for help hints again after your app changes the page |
openSupportChat() | Open a conversation with your team |
send(text, { mode? }) | Send a message as the user. In headless mode it resolves with the answer and steps. |
runWalkthrough(steps, title?) | Play walkthrough steps on the page |
navigateTo(url) | Take the user to a page |
assistantAvailable | true if Assistant mode can answer on this site |
expandChat(dock?) / collapseChat() | Expand the chat (right, left or bottom) or collapse it |
Surveys and lifecycle
| Method | What it does |
|---|---|
showNPSSurvey(context?) / showCSATSurvey(context?) | Show a survey now |
on(event, handler) | Listen to SDK events |
destroy() | Remove 3Guide from the page |
To change script attributes on a live page, call destroy(), then add the script tag again with the new attributes.