Events
Search measurement, catalog context, launcher events, and keyword privacy.
Search dispatches the DOM event augeo.event with the Augeo event envelope in CustomEvent.detail.
Events bubble and cross the Shadow DOM boundary through composed: true.
Search submission and result presentation use that same dispatch.
Prerequisites
- Mount a Search SDK instance.
- Use Host integration for callbacks that need actual search or prompt text.
- Read Configuration before forwarding events through host analytics.
Event contract
The SDK uses the augeo.search-sdk.loyalty-concierge@1 profile.
It forwards only admitted event types and classes for their surfaces.
Its envelope has spec: 'augeo.event' and specversion: '1.0'.
Event type versions are separate from the SDK bundle version.
Member tokens and recent-search text do not belong in event envelopes.
Other events still drop member search text.
Sanitized keyword is admitted only on search submitted and search performed, typeversion 1.
Use callbacks for the original query, product selection, and conversation seeds.
Do not rebuild the raw query from the analytics keyword.
Search submitted
The SDK emits one com.augeo.engagement.search.submitted event for each deliberate nonblank submission: Enter, Send, a recent search, or a catalog suggestion.
It emits synchronously before calling onSearchSubmit or starting a panel catalog request.
A query-only host callback needs no measurement code or completion handle to produce this event.
The occurrence schema is search.submitted/1.
| Envelope field | Value |
|---|---|
type | com.augeo.engagement.search.submitted |
typeversion | 1 |
class | measured |
source.surface | search_panel |
data.occurrence.keyword | Sanitized analytics copy of the submitted term |
This event has no page, result count, or outcome because results are not known yet. Count this type for search volume, including searches that later fail or are cancelled. Do not add performed events to that count: a successful search can produce both types. Repeated deliberate submissions create distinct event ids, even for identical terms. Typing, blank input, product clicks, Ask AI, request retries, reopening, and rerenders create no submission event. Suggestions use the selected term, not the typed prefix.
Both search events use the keyword sanitizer. A fully redacted keyword suppresses telemetry while the raw query still executes. The SDK emits on its root event bus; destination forwarding still requires analytics configuration, consent, and an admitted mapping. Synchronous host teardown happens after bus emission, but remote delivery across teardown or full document navigation is not guaranteed.
Search performed
An execution can additionally emit one com.augeo.engagement.search.performed event after matching results commit.
typeversion is 1.
class is measured.
source.surface is search_panel.
The occurrence schema is search.performed/1.
Both panel results and host-owned results use the same completion path. The SDK publishes the event only after matching products or an empty state commit. Configured analytics receives that root event when mapping and allow include it. Do not emit a parallel host-only event.
| Envelope field | Value |
|---|---|
type | com.augeo.engagement.search.performed |
typeversion | 1 |
class | measured |
source.surface | search_panel |
data.occurrence.keyword | Canonical analytics copy, not the raw query |
data.occurrence.page | Presented page, counting from 1 |
data.occurrence.resultCount | Items committed on that page |
data.occurrence.outcome | success or empty |
data.occurrence.categoryId | Omitted unless that filter was applied |
data.occurrence.productType | Omitted unless that filter was applied |
resultCount is the committed page-item count, not total matches.
A positive count derives outcome: 'success'.
Zero derives outcome: 'empty'.
The host does not send outcome.
Omit categoryId and productType when unavailable.
Do not guess them from one product card.
An empty string or non-string filter throws TypeError.
Keyword copy
The emission boundary calls the published sanitizeSearchKeyword helper.
It trims, lowercases, redacts emails, phone-like runs, and digit runs of 7 or more, then caps at 200 characters.
A null helper result suppresses that execution's event.
The original query still drives the request, route, and display.
A fully redacted term still searches with the raw query.
It emits no performed event.
A 201-character term still searches in full.
Its event keyword is the canonical value capped at 200.
Telemetry failure does not replace the committed result.
A consumed or suppressed execution does not emit again.
When it emits
| Interaction | Measurement |
|---|---|
| Typed submit or Send | New execution. Emits after committed results or empty state |
| Suggestion or recent selection | New execution for the selected term, not the typed prefix |
| Keystrokes or suggestion fetch | No execution |
| Product click or Ask AI | No search measurement |
| Pagination or rerender | No additional event |
| Agent or LLM search | No search-bar execution |
| Direct route visit | No synthesized execution |
Report only after the matching products or empty state commit. Router completion, fetch completion, loading placeholders, and retained previous cards are not presentation.
execution.presented({
page: currentPage,
resultCount: displayedProducts.length,
});execution.presented({ page: 1, resultCount: 0 });displayedProducts is the committed page, not the match total.
currentPage is a safe integer of at least 1.
Handle lifecycle
Each execution emits at most once.
A duplicate presented call is ignored.
Release your active reference before calling presented.
A synchronous listener may start a newer search.
presented requires a safe integer page of at least 1.
resultCount must be a safe integer of at least 0.
Missing, non-numeric, non-finite, or fractional values throw TypeError.
That error does not consume pending eligibility.
If you released the handle first, put it back and correct the facts.
A later valid report can still emit once.
Terminal handles ignore late calls.
A recoverable failure shows the error state and emits nothing.
Retry on that same handle emits once when the retry view commits.
A terminal failure calls cancel() and must not be reported as empty.
After cancellation, submit again.
That creates a new execution.
The SDK has no programmatic retry method.
Closing the panel keeps a pending host execution. Leaving the results route cancels the id that route captured. An old route cleanup must not cancel a newer execution. Member or program changes cancel pending work. The handle lives only while the SPA shell and SDK stay mounted. Full document navigation cannot retain it. If your flow unloads the SDK, implement an explicit transfer before production acceptance.
SDK types are SearchExecution and SearchPresentedResults.
Host controller, adapter, commit, and retry wiring are in Host integration.
Concrete outcomes
| Case | Measurement |
|---|---|
Typed coffee, 535 matches, 15 page-1 items | One event: keyword coffee, page 1, count 15, success |
Type coff, select coffee maker | Measure coffee maker, not coff. Totals do not set count |
| Committed empty page | presented({ page: 1, resultCount: 0 }) yields empty |
| Failed load, then valid retry | No event on error. Same handle emits once after commit |
| Cancel, then deliberate retry | Old handle stays inert. A new submission creates a new id |
| Pending coffee, then tea | Cancel coffee. Ignore its late navigation, fetch, and commit |
Submit coffee again | New id may emit again on the same route text |
| Duplicate commit, rerender, page 2 | No additional performed event |
| Close panel while host results load | Pending host measurement stays eligible |
| Leave the results route | Cancel that route's captured id, not a newer search |
| Mixed case, padding, or a long term | Search uses the raw query. The event keyword is canonical and at most 200 |
| Whitespace-only or fully redacted | No performed event. A blank submit still does nothing |
Ask AI activation
Selecting Ask AI or a THEO prompt produces one com.augeo.conversation.launcher.activated event.
| Envelope field | Value |
|---|---|
type | com.augeo.conversation.launcher.activated |
class | measured |
source.surface | search_panel |
data.occurrence.activationSource | search-field |
data.occurrence.hasSeed | Boolean indicating whether seed text exists |
The actual seed arrives through onAskAi(query) only.
Without that callback, the activation still fires and the panel requests closure.
The host must decide whether to open chat.
Ask AI does not emit search.submitted or search.performed.
Catalog context
When the host sets catalogContext.catalog, admitted events copy that value to data.context.theo.catalog.
The accepted values are kigo and rewards_hub.
Omitting catalog leaves the field absent and preserves existing product-catalog semantics.
The SDK does not send catalog as a query parameter and does not choose a provider from it.
When an admitted event identifies a result, use the returned canonical item reference.
An offer reference has kind: "offer" and id equal to the offer id string.
Do not substitute a merchant id, wallet token, or location id.
A callback, searchCatalog response, or fetch completion is not a result-view event.
search.performed still waits until the widget or the host paints the page.
searchCatalog itself does not emit search.submitted or search.performed, and it does not create a SearchExecution.
Call presented only after that paint for an ordinary-search execution.
Listen and unsubscribe
Listen on the mount container to scope events to this widget. Validate unknown detail before forwarding selected fields to your telemetry system. This JavaScript example records only the launcher event identifier and seed-presence flag.
const target = document.getElementById('search-host');
if (!target) throw new Error('Search mount container is missing.');
function onSearchEvent(event) {
if (!(event instanceof CustomEvent)) return;
const envelope = event.detail;
if (!envelope || envelope.spec !== 'augeo.event') return;
if (envelope.type !== 'com.augeo.conversation.launcher.activated') return;
if (typeof envelope.id !== 'string') return;
const hasSeed = envelope.data?.occurrence?.hasSeed;
if (typeof hasSeed !== 'boolean') return;
console.info('Search AI activation', { id: envelope.id, hasSeed });
}
target.addEventListener('augeo.event', onSearchEvent);
// Run alongside search.destroy() during host teardown.
const removeSearchListener = () => {
target.removeEventListener('augeo.event', onSearchEvent);
};Record a performed event only after you check typeversion and occurrence shape.
Do not log the raw query, bearer, or the whole event.detail.
function onPerformed(event) {
if (!(event instanceof CustomEvent)) return;
const envelope = event.detail;
if (!envelope || envelope.spec !== 'augeo.event') return;
if (envelope.type !== 'com.augeo.engagement.search.performed') return;
if (envelope.typeversion !== 1) return;
const occurrence = envelope.data && envelope.data.occurrence;
if (!occurrence || typeof occurrence.keyword !== 'string') return;
if (occurrence.keyword.length < 1 || occurrence.keyword.length > 200) return;
console.info('Search performed', {
id: envelope.id,
page: occurrence.page,
resultCount: occurrence.resultCount,
outcome: occurrence.outcome,
});
}Avoid logging raw event.detail, callback query text, or Authorization headers.
A document-level listener can observe several SDK instances; scope or identify its source before acting.
Use onAskAi to open chat once with the seed, and use the event for measurement.
Use presented to complete a search, and use this listener only to observe it.
Related links
- Completion handle: Configuration
- Host callbacks: Host integration
- Interaction behavior: Functionality
- Shared envelopes: Events Dictionary
- Privacy acceptance checks: Validation