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
| Item | Requirement |
|---|---|
| Host page | Serves HTTPS and can load a third-party script |
| Persona | loyalty-concierge |
| Bundle global | window.AugeoChatSdkLoyaltyConcierge |
| Host tag | window.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
| Value | Effect |
|---|---|
| omitted | Analytics off. No destination writes |
false | Analytics off |
true | Analytics on. No adapters. No writes |
| object | Analytics 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
| Parameter | Default | Type |
|---|---|---|
adapters | [] | writer objects with id and send |
mapping | registry defaults | overlay object |
identity | unset | { userId: () => string } |
consent | omitted | granted, denied, callback, cookie, or localStorage |
allow | unset | glob string array |
deny | unset | glob string array |
classes | ['measured'] | 'measured' and/or 'observed' |
enrich | unset | function that returns mapping context |
onDecline | unset | function 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.
consent
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.
| Reason | Meaning |
|---|---|
lifecycle | Dictionary name is deprecated |
consent_withheld | Consent source returned false |
not_allowlisted | Name missed allow or hit deny |
mapped_drop | Overlay set the destination name to null |
direct_identifier_blocked | Identity param without allowlist |
forbidden_key | Param used a blocked identifier key |
destination_not_ready | Adapter ready returned false |
adapter_error | Adapter send threw |
capabilities: {
analytics: {
adapters: [gtagAdapter],
onDecline: (event, reason) => {
window.hostTelemetry?.capture?.('analytics_declined', {
type: event.type,
reason,
});
},
},
}Host duties
- Load your analytics tag before you construct the assistant.
- Pass at least one adapter object on
capabilities.analytics. - Set destination names the host tag already expects.
- Keep member identity on destination params only.
- 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
| Symptom | Likely cause |
|---|---|
| No destination hits | Analytics omitted or set to true |
ready skips every write | Host tag is missing or late |
| Consent declines | Callback, cookie, or storage withheld |
| Identity param missing | Overlay omitted allowDirectIdentifiers |
- Confirm
window.gtagis a function on the host page. - Pass an analytics object with at least one adapter.
- Check
onDeclinefor consent, mapping, and ready failures.
Full example
- Load your gtag snippet on the host page.
- Construct the assistant with an analytics adapter.
- 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.
Related pages
| Topic | Page |
|---|---|
| Product scope | Overview |
| Constructor fields | Configuration |
| Placement | Surfaces |
| Capability list | Capabilities |
| Event options | Event options |
| History | History |
| Privacy | Privacy |
| Message actions | Message actions |
| Chat | Chat |
| Suggestions | Suggestions |
| Wishlist | Wishlist |
| Support | Support |
| Recovery | Recovery |
| Devtools | Devtools |
| DOM events | Events |
| Public types | API |
| Integration failures | Common issues |