Surfaces
Surfaces
surface.type selects the presentation shell.
Allowed values are inline, modal, and sidebar.
No other field can change which shell renders.
Omitted surface resolves to { type: 'inline' }.
When you pass surface, type is required.
Prerequisites
| Item | Value |
|---|---|
| Persona | loyalty-concierge |
| Root options | container and auth.getToken already work |
Read Configuration first.
Choose a type
| Type | What it is | When to use |
|---|---|---|
inline | Fills the host mount node | Use a host-owned panel or page region |
modal | Overlay panel with an optional FAB | Keep host layout and launch from a button |
sidebar | Docked column beside host content | Reflow the page or fill a host sidebar slot |
Inline
Inline fills container and stays in normal document flow.
Use it when the host already owns the chat panel.
Inline fields
| Field | Required | Default | Effect |
|---|---|---|---|
type | yes | inline when omitted | Selects the inline shell |
onDismiss | no | none | Host close handler; valid only on inline |
onDismiss is a compile-time error on modal or sidebar.
Default inline
new AugeoAssistant({
container: '#chat-host',
auth: { getToken: () => token },
});Omitted surface mounts inline in #chat-host.
The widget fills that node and does not overlay the page.
Explicit inline type
surface: { type: 'inline' }The same inline shell renders.
Use the explicit object when you also pass onDismiss.
Inline onDismiss
surface: {
type: 'inline',
onDismiss: () => hostCloseChat(),
}The SDK calls hostCloseChat when the member closes the inline widget.
The host then hides or removes its panel.
Without onDismiss, close stays host-owned with no SDK callback.
Modal
Modal is an overlay panel. Use it when the chat should float over host content.
Modal fields
| Field | Required | Default | Effect |
|---|---|---|---|
type | yes | none | Selects the modal shell |
openOnMount | no | false | true auto-opens the overlay on mount |
askAi | no | none | Injects Ask AI into host search |
fab | no | injection-failed fallback | Controls the floating launcher button |
Default modal
surface: { type: 'modal' }The overlay stays closed after mount.
With no askAi, the FAB reveals after the first-paint frame.
Modal openOnMount
surface: { type: 'modal', openOnMount: true }The overlay opens as soon as the widget mounts.
openOnMount: false or omitted waits for Ask AI, the FAB, or a later open.
Modal fab: true
surface: { type: 'modal', fab: true }The FAB reveals after the first-paint frame.
Use this to opt back in while askAi is also configured.
Modal fab: false
surface: { type: 'modal', fab: false }The FAB never reveals.
The member needs askAi, openOnMount: true, or a host-owned trigger.
Modal omitted fab
Omitted fab uses the injection-failed fallback.
While askAi is pending or mounted, the FAB stays hidden.
An invalid askAi.button or a timeout emits injection-failed and then reveals the FAB.
Sidebar
Sidebar docks a column beside host content. Use it when the chat should share the page with host UI.
Sidebar fields
| Field | Required | Default | Effect |
|---|---|---|---|
type | yes | none | Selects the sidebar shell |
openOnMount | no | false | true auto-opens the dock on mount |
askAi | no | none | Injects Ask AI into host search |
fab | no | injection-failed fallback | Controls the floating launcher button |
container | no | page reflow | Host mount node; omit to wrap the page |
width.base | no | clamp(320px, 30vw, 480px) | Docked width |
width.min | no | none | Minimum docked width |
width.max | no | none | Maximum docked width |
width.at | no | none | Width overrides at viewport min-widths |
side | no | right | Docks on left or right |
mobileBreakpoint | no | 767 | At or below this width, the shell uses modal overlay |
Default sidebar
surface: { type: 'sidebar' }The dock stays closed after mount.
With no askAi, the FAB reveals after the first-paint frame.
Width is clamp(320px, 30vw, 480px) on the right.
At 767px or below, the shell falls back to a modal overlay.
With no container, the SDK reflows the page to make room.
Sidebar openOnMount
surface: { type: 'sidebar', openOnMount: true }The dock opens as soon as the widget mounts.
Omitted or false waits for Ask AI, the FAB, or a later open.
Sidebar fab: true
surface: { type: 'sidebar', fab: true }The FAB reveals after the first-paint frame.
It stays visible when injection fails or askAi is omitted.
The same value applies in the small-screen overlay.
Sidebar fab: false
surface: { type: 'sidebar', fab: false }The FAB never reveals.
That includes omitted askAi and an injection failure.
The small-screen overlay honors fab: false too.
Use open after initialization when the host owns the entry point.
Sidebar omitted fab
Omitted fab uses the injection-failed fallback.
With no askAi, the FAB reveals after the first-paint frame.
While askAi is pending or mounted, the FAB stays hidden.
Injection-failed then reveals the FAB.
Sidebar container
surface: {
type: 'sidebar',
container: '#rewards-sidebar',
}The sidebar renders into #rewards-sidebar instead of wrapping the page.
Omit container when the SDK should reflow host content.
Sidebar width.base
surface: {
type: 'sidebar',
width: { base: '380px' },
}The dock is 380px wide instead of the default clamp.
width is an object with base, min, max, and at.
Sidebar width.min and width.max
surface: {
type: 'sidebar',
width: {
base: '30vw',
min: '320px',
max: '480px',
},
}The dock can shrink to 320px and grow to 480px.
Those bounds apply with the 30vw base width.
Sidebar width.at
surface: {
type: 'sidebar',
width: {
base: '360px',
at: {
1024: { base: '420px' },
},
},
}Viewports at least 1024px wide use 420px.
Smaller viewports keep the 360px base.
Sidebar side
surface: { type: 'sidebar', side: 'left' }The dock sits on the left.
Omitted side docks on the right.
Sidebar mobileBreakpoint
surface: { type: 'sidebar', mobileBreakpoint: 640 }At 640px or below, the sidebar uses a modal overlay.
The fab override still applies in that overlay.
The default breakpoint is 767.
Ask AI
askAi is valid on modal and sidebar only.
It injects an Ask AI button into host search.
When personalization is available, one teaser anchors below that button.
| Field | Required | Default | Effect |
|---|---|---|---|
button | yes | none | CSS selector for the host search island |
seedFrom | yes | none | CSS selector whose text seeds the first turn |
timeoutMs | no | 1500 | Wait bound for the island to mount |
Both button and seedFrom must be strings.
Otherwise askAi is dropped.
surface: {
type: 'sidebar',
askAi: {
button: '#rewards-search-bar',
seedFrom: '#rewards-search-input',
},
}The SDK injects Ask AI into #rewards-search-bar.
It reads the member query from #rewards-search-input.
timeoutMs stays 1500 because it is omitted.
askAi: {
button: '#rewards-search-bar',
seedFrom: '#rewards-search-input',
timeoutMs: 2500,
}The island may take up to 2500ms to mount.
The timer is a wait bound, not the FAB reveal trigger.
If button never resolves, injection-failed fires.
Modal and sidebar then reveal the FAB unless fab is false.
An explicit fab wins on both launchable surfaces.
That override also applies in the small-screen overlay.
A late host node is still picked up, and the island can re-attach.
Host-owned Ask AI
A host that renders its own Ask AI control calls open instead of configuring askAi.
open uses the same launch path and seeds the composer without sending.
Set fab: false when the host owns the entry point.
open({ seed }) still opens and seeds the sidebar when fab is false and askAi is omitted.
Call open({ seed }) only after successful initialization.
A call before initialization completes does nothing.
const search = window.AugeoSearchSdk.createAugeoSearch({
target: document.querySelector('#rewards-search'),
auth: { getToken: () => memberToken },
onAskAi: (query) => assistant.open({ seed: query }),
});The search widget reports its own launcher activation. The assistant still reports that the shell opened.
Related pages
| Topic | Page |
|---|---|
| Root options | Configuration |
| Partner colors | Branding |
| Feature groups | Capabilities |
| Member intents | Events |
| Public types | API |
| Minimal embed | Quick start |
| Mount failures | Common issues |