Common issues
Common issues
Diagnose and fix common loyalty widget integration failures on a host site.
Each section is self-contained. Read the symptom that matches your failure first.
Prerequisites
| Item | Requirement |
|---|---|
| Host page | Serves HTTPS and can load a third-party script |
| Persona | loyalty-concierge only |
| Bundle global | window.AugeoChatSdkLoyaltyConcierge |
| Production CDN | https://sdks.augeoai.net |
| Production API default | https://api.augeoai.net |
Load a pinned production loyalty bundle before you construct the assistant. See Quick start for the minimal embed.
Version
| Constant | Value | Meaning |
|---|---|---|
| Event spec | augeo.event | Value of spec on every upward envelope |
| Ack spec | augeo.ack | Value of spec on every host ack |
| Spec version | 1.0 | Value of specversion |
| DOM event name | augeo.event | Upward CustomEvent name |
Constants
| Name | Value | Use |
|---|---|---|
AUGEO_EVENT | augeo.event | Exact upward DOM event name |
AUGEO_ACK_EVENT | augeo.ack | Exact downward DOM event name |
| Mount selector example | #chat-host | Generic host container |
| Bundle global | window.AugeoChatSdkLoyaltyConcierge | Constructor and helpers |
Read constants from the persona IIFE global after the script loads.
Missing container
Symptom
The widget does not mount.
onError reports a missing or unresolved container.
Cause
container must already exist when the constructor runs.
The SDK resolves it with document.querySelector.
Fix
- Create the mount node before the constructor runs.
- Confirm the selector with
document.querySelector. - Pass that same selector as
container. - Wire
onErrorso mount failures appear in host logs.
<div id="chat-host"></div>
<script>
const { AugeoAssistant } = window.AugeoChatSdkLoyaltyConcierge;
const assistant = new AugeoAssistant({
container: '#chat-host',
auth: { getToken: () => bearerToken },
onError: (error) => {
console.error(error);
},
});
</script>Confirm the selector in the console with document.querySelector('#chat-host').
A null result means the mount node is still missing.
Invalid selectors
Symptom
Ask AI never appears, sidebar injection fails, or onError reports a selector error once.
Cause
Surface selectors use document.querySelector with field-specific retry behavior.
Affected fields
| Field | Resolution behavior |
|---|---|
container | Resolves once during construction. Missing values call onError with no retry. |
surface.container | Sidebar host. Failure calls onError and opens modal without retrying. |
surface.askAi.button | A valid missing target is watched. An invalid selector reports once. |
surface.askAi.seedFrom | Read on each launch. Missing values provide no seed text. |
Fix
- Validate each selector in the browser console.
- Use a simple id or class selector the host owns.
- Keep the Ask AI target in the document while the widget runs.
- Wire
onErrorso reported selector failures appear in host logs.
const assistant = new AugeoAssistant({
container: '#chat-host',
auth: { getToken: () => bearerToken },
surface: {
type: 'sidebar',
container: '#assistant-sidebar-slot',
askAi: {
button: '#host-search-bar',
seedFrom: '#host-search-input',
},
},
onError: (error) => {
console.error(error);
},
});An invalid Ask AI selector reports once and starts no watcher. A late but valid search bar still mounts when the host renders it.
Auth recovery
Symptom
API calls fail after the member session expires. The widget shows auth errors or stops loading threads.
Cause
Every request needs a current bearer token from auth.getToken.
An expired or invalid token is rejected by the production API.
Fix
- Implement
auth.getTokenso each call returns a fresh token string. - Pass
auth.onFailureto refresh the host session token. - Keep the refreshed value where
auth.getTokencan read it.
const assistant = new AugeoAssistant({
container: '#chat-host',
auth: {
getToken: () => window.__HOST_MEMBER_TOKEN__,
onFailure: async () => {
window.__HOST_MEMBER_TOKEN__ = await window.refreshMemberToken();
},
},
onError: (error) => {
console.error(error);
},
});Mint a new token inside auth.onFailure.
The next request reads it through auth.getToken.
Wrong event names
Symptom
Member actions in the widget produce no host handler calls. The listener fails silently.
Cause
Every compact fact uses one DOM name: augeo.event.
A misspelled name never receives the stream.
Fix
- Listen for the exact name
augeo.event. - Prefer
subscribeAugeoEventsso the name stays correct. - Confirm delivery with the event devtools panel.
const { AUGEO_EVENT, subscribeAugeoEvents } =
window.AugeoChatSdkLoyaltyConcierge;
const unsubscribe = subscribeAugeoEvents(document, (event) => {
handleFact(event);
});Raw listeners must use the same exact string.
const { AUGEO_EVENT, isAugeoEventEnvelope } =
window.AugeoChatSdkLoyaltyConcierge;
document.addEventListener(AUGEO_EVENT, (e) => {
const event = e.detail;
if (!isAugeoEventEnvelope(event)) return;
handleFact(event);
});Do not invent per-intent DOM names.
Namespacing lives in event.type, not in many event names.
Open the live inspector with the steps in Debugging with devtools. If the panel shows events and your listener does not, the host name is wrong.
Duplicate delivery
Symptom
One member click runs the host handler twice. Cart or wishlist commits double-apply.
Cause
The same envelope can reach a helper and a raw document listener.
Both deliveries share one id.
Fix
- Deduplicate on
idwhen you use both surfaces. - Prefer one subscribe path on
document. - Make cart and wishlist commits idempotent on item id.
const seen = new Set();
function handle(event) {
if (seen.has(event.id)) return;
seen.add(event.id);
commitOnce(event);
}
const { subscribeAugeoEvents } = window.AugeoChatSdkLoyaltyConcierge;
subscribeAugeoEvents(document, handle);Deduplicate on envelope id.
Version mismatch
Symptom
subscribeAugeoEvents never delivers some events.
A raw listener receives envelopes your host does not understand.
Cause
The helper requires a complete compact envelope. A mismatched envelope is dropped.
Helper behavior
| Case | Helper behavior |
|---|---|
| Complete compact envelope | Delivers the event |
Wrong spec or specversion | Drops the event |
| Missing required field | Drops the event |
Fix
- Pin one production bundle version on the host page.
- Prefer the helper over a raw listener.
- Gate raw listeners with
isAugeoEventEnvelope. - Ignore types your handler does not implement.
const { AUGEO_EVENT, isAugeoEventEnvelope } =
window.AugeoChatSdkLoyaltyConcierge;
document.addEventListener(AUGEO_EVENT, (e) => {
const event = e.detail;
if (!isAugeoEventEnvelope(event)) return;
handleKnownType(event);
});Do not trust a payload for a typeversion you were not built against.
See Events v1 for the current schema.
Unreachable launchers
Symptom
Members cannot open the assistant. No Ask AI button or FAB appears.
Cause
Ask AI kept the FAB hidden, and the Ask AI target did not mount. A broken sidebar path can also fall back without an obvious entry control.
Rescue behavior
| Condition | SDK response |
|---|---|
| Invalid Ask AI selector | Injection-failed fires immediately; FAB reveals |
| Missing Ask AI container | Wait bound elapses; injection-failed fires; FAB reveals |
Explicit surface.fab | Still wins on modal and sidebar |
| Sidebar injection cannot run | Falls back to modal and reports through onError |
Fix
- Confirm
surface.askAi.buttonresolves in the live DOM. - Keep the search bar mounted on routes that need Ask AI.
- Set
surface.fab: truewhen you want the FAB always. - Watch
onErrorfor sidebar fallback and selector failures.
const assistant = new AugeoAssistant({
container: '#chat-host',
auth: { getToken: () => bearerToken },
surface: {
type: 'modal',
fab: true,
askAi: {
button: '#host-search-bar',
seedFrom: '#host-search-input',
},
},
onError: (error) => {
console.error(error);
},
});Removing the search bar on an SPA route change reveals the FAB immediately. Restoring the bar re-attaches the same Ask AI island and hides the FAB.
See Surfaces for full placement options.
Destination writes never appear
Symptom
The gtag debug view shows no widget events. Host tags receive no mapped destination names.
Cause
Analytics is off by default.
true without adapters writes nothing.
A missing window.gtag makes ready skip the write.
Denied consent withholds every write.
Fix
- Load your analytics tag before you construct the assistant.
- Pass
capabilities.analyticsas an object with adapters. - Confirm
window.gtagis a function on the host page. - Check
onDeclinefor consent, mapping, and ready failures.
const { AugeoAssistant } = window.AugeoChatSdkLoyaltyConcierge;
new AugeoAssistant({
container: '#chat-host',
auth: { getToken: () => bearerToken },
capabilities: {
analytics: {
adapters: [
{
id: 'gtag',
ready: () => typeof window.gtag === 'function',
send(dispatch) {
window.gtag('event', dispatch.mapped.event, dispatch.mapped.params);
},
},
],
},
},
});See Analytics for mapping, identity, and consent.
Teardown
Symptom
Stale listeners, duplicate widgets, or leftover Ask AI nodes after a route change. Host layout padding remains after the chat area unmounts.
Cause
The instance stays alive until you call destroy().
Injected Ask AI nodes and panel listeners need that cleanup.
Fix
- Call
destroy()when the host route or session ends. - Drop your own event unsubscribers in the same teardown path.
- Construct a new
AugeoAssistantonly when the member needs the widget again.
const { AugeoAssistant, subscribeAugeoEvents } =
window.AugeoChatSdkLoyaltyConcierge;
const unsubscribe = subscribeAugeoEvents(document, handleFact);
const assistant = new AugeoAssistant({
container: '#chat-host',
auth: { getToken: () => bearerToken },
});
window.addEventListener('pagehide', () => {
unsubscribe();
assistant.destroy();
});After destroy(), the instance is inert.
Injected Ask AI nodes are removed.
Do not call methods on the destroyed instance.
Quick checklist
| Check | Expected |
|---|---|
| Mount node exists before construction | document.querySelector('#chat-host') is non-null |
| Persona global is present | window.AugeoChatSdkLoyaltyConcierge is defined |
| Event name is exact | Listener uses augeo.event |
| Dual delivery is deduped | Host collapses on envelope id |
| Token refresh is wired | auth.onFailure mints a new bearer token |
| Route exit destroys the instance | destroy() runs once per mount |
Related pages
| Page | Use it for |
|---|---|
| Debugging with devtools | Live event inspector |
| Quick start | Minimal production embed |
| Surfaces | Sidebar, modal, and Ask AI placement |
| Events | Subscriptions and version gates |
| Analytics | Destination writers and gtag adapters |
| Event envelope | Compact field list |
| Event catalog | Names this widget emits |
| API | Public types and helpers |