Augeo AI Docs
SDKsTroubleshooting

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

ItemRequirement
Host pageServes HTTPS and can load a third-party script
Personaloyalty-concierge only
Bundle globalwindow.AugeoChatSdkLoyaltyConcierge
Production CDNhttps://sdks.augeoai.net
Production API defaulthttps://api.augeoai.net

Load a pinned production loyalty bundle before you construct the assistant. See Quick start for the minimal embed.

Version

ConstantValueMeaning
Event specaugeo.eventValue of spec on every upward envelope
Ack specaugeo.ackValue of spec on every host ack
Spec version1.0Value of specversion
DOM event nameaugeo.eventUpward CustomEvent name

Constants

NameValueUse
AUGEO_EVENTaugeo.eventExact upward DOM event name
AUGEO_ACK_EVENTaugeo.ackExact downward DOM event name
Mount selector example#chat-hostGeneric host container
Bundle globalwindow.AugeoChatSdkLoyaltyConciergeConstructor 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

  1. Create the mount node before the constructor runs.
  2. Confirm the selector with document.querySelector.
  3. Pass that same selector as container.
  4. Wire onError so 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

FieldResolution behavior
containerResolves once during construction. Missing values call onError with no retry.
surface.containerSidebar host. Failure calls onError and opens modal without retrying.
surface.askAi.buttonA valid missing target is watched. An invalid selector reports once.
surface.askAi.seedFromRead on each launch. Missing values provide no seed text.

Fix

  1. Validate each selector in the browser console.
  2. Use a simple id or class selector the host owns.
  3. Keep the Ask AI target in the document while the widget runs.
  4. Wire onError so 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

  1. Implement auth.getToken so each call returns a fresh token string.
  2. Pass auth.onFailure to refresh the host session token.
  3. Keep the refreshed value where auth.getToken can 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

  1. Listen for the exact name augeo.event.
  2. Prefer subscribeAugeoEvents so the name stays correct.
  3. 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

  1. Deduplicate on id when you use both surfaces.
  2. Prefer one subscribe path on document.
  3. 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

CaseHelper behavior
Complete compact envelopeDelivers the event
Wrong spec or specversionDrops the event
Missing required fieldDrops the event

Fix

  1. Pin one production bundle version on the host page.
  2. Prefer the helper over a raw listener.
  3. Gate raw listeners with isAugeoEventEnvelope.
  4. 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

ConditionSDK response
Invalid Ask AI selectorInjection-failed fires immediately; FAB reveals
Missing Ask AI containerWait bound elapses; injection-failed fires; FAB reveals
Explicit surface.fabStill wins on modal and sidebar
Sidebar injection cannot runFalls back to modal and reports through onError

Fix

  1. Confirm surface.askAi.button resolves in the live DOM.
  2. Keep the search bar mounted on routes that need Ask AI.
  3. Set surface.fab: true when you want the FAB always.
  4. Watch onError for 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

  1. Load your analytics tag before you construct the assistant.
  2. Pass capabilities.analytics as an object with adapters.
  3. Confirm window.gtag is a function on the host page.
  4. Check onDecline for 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

  1. Call destroy() when the host route or session ends.
  2. Drop your own event unsubscribers in the same teardown path.
  3. Construct a new AugeoAssistant only 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

CheckExpected
Mount node exists before constructiondocument.querySelector('#chat-host') is non-null
Persona global is presentwindow.AugeoChatSdkLoyaltyConcierge is defined
Event name is exactListener uses augeo.event
Dual delivery is dedupedHost collapses on envelope id
Token refresh is wiredauth.onFailure mints a new bearer token
Route exit destroys the instancedestroy() runs once per mount
PageUse it for
Debugging with devtoolsLive event inspector
Quick startMinimal production embed
SurfacesSidebar, modal, and Ask AI placement
EventsSubscriptions and version gates
AnalyticsDestination writers and gtag adapters
Event envelopeCompact field list
Event catalogNames this widget emits
APIPublic types and helpers