Augeo AI Docs
SDKsCapabilities

Analytics

Analytics

Analytics maps widget events onto destination writers the host already initialized. The default is off. Pass an options object to subscribe after emit. The widget never loads gtag or creates dataLayer.

Event options stamp ids and filter telemetry publish. They do not write destination events. Keep both on when you want telemetry and destination writes.

Prerequisites

ItemRequirement
Host pageServes HTTPS and can load a third-party script
Personaloyalty-concierge
Bundle globalwindow.AugeoChatSdkLoyaltyConcierge
Host tagwindow.gtag or another writer the host initialized

Load a pinned production loyalty bundle first. Read Capabilities for the shared true / false / object contract. Load your analytics tag before you construct the assistant. Host listeners for augeo.event still run on their own.

Values

ValueEffect
omittedAnalytics off. No destination writes
falseAnalytics off
trueAnalytics on. No adapters. No writes
objectAnalytics on with adapters and mapping

true without adapters writes nothing. Pass at least one adapter to send events. The IIFE bundle does not export a gtag helper. Pass an adapter object on the constructor.

Parameters

ParameterDefaultType
adapters[]writer objects with id and send
mappingregistry defaultsoverlay object
identityunset{ userId: () => string }
consentomittedgranted, denied, callback, cookie, or localStorage
allowunsetglob string array
denyunsetglob string array
classes['measured']'measured' and/or 'observed'
enrichunsetfunction that returns mapping context
onDeclineunsetfunction for skipped writes

Omitted consent piggybacks on the host tag. The widget does not read a CMP by default. classes defaults to measured names only. Observed UI facts stay off unless you add 'observed'. enrich feeds mapping only. It never copies fields onto augeo.event. identity.userId is a destination param. It never lands on the envelope.

adapters

Pass writers the host already initialized. Each writer needs id and send. Optional ready skips a write when the tag is missing.

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);
          },
        },
      ],
    },
  },
});

send receives event, cloudEvent, and mapped. event is the compact envelope. cloudEvent is the CloudEvents 1.0 form. mapped.event is the destination name. mapped.params holds only overlay keys. mapped.items is present only when mapping produces items. Do not call gtag('config') from send. The host already configured the tag.

mapping

Pass an overlay to rename events and add params. Registry defaults map cart adds to add_to_cart. Override that name when the host expects theo_add_to_cart. The overlay is the destination allowlist. Require allowDirectIdentifiers before { identity: 'userId' }.

capabilities: {
  analytics: {
    adapters: [gtagAdapter],
    mapping: {
      allowDirectIdentifiers: ['userId'],
      events: {
        'com.augeo.engagement.cart.item.added': {
          event: 'theo_add_to_cart',
          params: {
            catalog_id: { const: 'cat_1' },
            member_key: { identity: 'userId' },
          },
        },
      },
    },
    identity: { userId: () => hostMemberId },
  },
}

The destination event becomes theo_add_to_cart. member_key is filled from identity.userId. Choose that param name in the overlay. The library never bakes a host-specific key. Do not put email, phone, name, or card data in params. Mapping drops those keys.

Omit consent to piggyback. Pass { type: 'denied' } to withhold writes. Pass a callback, cookie, or localStorage source to gate writes.

capabilities: {
  analytics: {
    adapters: [gtagAdapter],
    consent: { type: 'callback', read: () => window.__consentGranted === true },
  },
}

Writes run only when the callback returns true. A throwing callback withholds the write.

allow and deny

Pass globs to skip destination writes for matching names. These filters apply after emit. They do not change host augeo.event listeners. Deny wins over allow.

capabilities: {
  analytics: {
    adapters: [gtagAdapter],
    allow: ['com.augeo.engagement.*'],
    deny: ['com.augeo.ui.*'],
  },
}

Only matching engagement names reach destination writers.

classes

Keep the default to forward measured names only.

capabilities: {
  analytics: {
    adapters: [gtagAdapter],
    classes: ['measured', 'observed'],
  },
}

Both classes forward when listed.

enrich

Return host context for mapping paths. Do not expect that object on augeo.event.

capabilities: {
  analytics: {
    adapters: [gtagAdapter],
    mapping: {
      events: {
        'com.augeo.engagement.cart.item.added': {
          event: 'theo_add_to_cart',
          params: { placement_type: { from: 'context.storefront.attribution' } },
        },
      },
    },
    enrich: () => ({ storefront: { attribution: 'THEO' } }),
  },
}

placement_type reads the enrich patch. The compact envelope still lacks storefront.

onDecline

Pass onDecline to observe skipped writes. A throwing callback is logged and ignored.

ReasonMeaning
lifecycleDictionary name is deprecated
consent_withheldConsent source returned false
not_allowlistedName missed allow or hit deny
mapped_dropOverlay set the destination name to null
direct_identifier_blockedIdentity param without allowlist
forbidden_keyParam used a blocked identifier key
destination_not_readyAdapter ready returned false
adapter_errorAdapter send threw
capabilities: {
  analytics: {
    adapters: [gtagAdapter],
    onDecline: (event, reason) => {
      window.hostTelemetry?.capture?.('analytics_declined', {
        type: event.type,
        reason,
      });
    },
  },
}

Host duties

  1. Load your analytics tag before you construct the assistant.
  2. Pass at least one adapter object on capabilities.analytics.
  3. Set destination names the host tag already expects.
  4. Keep member identity on destination params only.
  5. Confirm writes in the destination debug view.

Do not inject gtag from the widget. Do not call gtag('config') from an adapter. Do not put email, phone, name, or card data on the envelope. Do not expect identity.userId on augeo.event.

Missed writes

SymptomLikely cause
No destination hitsAnalytics omitted or set to true
ready skips every writeHost tag is missing or late
Consent declinesCallback, cookie, or storage withheld
Identity param missingOverlay omitted allowDirectIdentifiers
  1. Confirm window.gtag is a function on the host page.
  2. Pass an analytics object with at least one adapter.
  3. Check onDecline for consent, mapping, and ready failures.

Full example

  1. Load your gtag snippet on the host page.
  2. Construct the assistant with an analytics adapter.
  3. Confirm writes in the gtag debug view.
const { AugeoAssistant } = window.AugeoChatSdkLoyaltyConcierge;

function createHostGtagAdapter() {
  return {
    id: 'gtag',
    ready: () => typeof window.gtag === 'function',
    send(dispatch) {
      const params = { ...dispatch.mapped.params };
      if (dispatch.mapped.items) params.items = dispatch.mapped.items;
      window.gtag('event', dispatch.mapped.event, params);
    },
  };
}

new AugeoAssistant({
  container: '#chat-host',
  auth: { getToken: () => bearerToken },
  capabilities: {
    analytics: {
      adapters: [createHostGtagAdapter()],
      mapping: {
        allowDirectIdentifiers: ['userId'],
        events: {
          'com.augeo.engagement.cart.item.added': {
            event: 'theo_add_to_cart',
            params: {
              placement_type: { const: 'THEO' },
              member_key: { identity: 'userId' },
            },
          },
        },
      },
      identity: { userId: () => hostProfileId },
    },
  },
});

The widget maps cart adds to theo_add_to_cart. member_key is a destination param from identity.userId. The compact envelope still carries only opaque participantRef.

TopicPage
Product scopeOverview
Constructor fieldsConfiguration
PlacementSurfaces
Capability listCapabilities
Event optionsEvent options
HistoryHistory
PrivacyPrivacy
Message actionsMessage actions
ChatChat
SuggestionsSuggestions
WishlistWishlist
SupportSupport
RecoveryRecovery
DevtoolsDevtools
DOM eventsEvents
Public typesAPI
Integration failuresCommon issues