Augeo AI Docs
SDKsSearch SDK

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 fieldValue
typecom.augeo.engagement.search.submitted
typeversion1
classmeasured
source.surfacesearch_panel
data.occurrence.keywordSanitized 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 fieldValue
typecom.augeo.engagement.search.performed
typeversion1
classmeasured
source.surfacesearch_panel
data.occurrence.keywordCanonical analytics copy, not the raw query
data.occurrence.pagePresented page, counting from 1
data.occurrence.resultCountItems committed on that page
data.occurrence.outcomesuccess or empty
data.occurrence.categoryIdOmitted unless that filter was applied
data.occurrence.productTypeOmitted 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

InteractionMeasurement
Typed submit or SendNew execution. Emits after committed results or empty state
Suggestion or recent selectionNew execution for the selected term, not the typed prefix
Keystrokes or suggestion fetchNo execution
Product click or Ask AINo search measurement
Pagination or rerenderNo additional event
Agent or LLM searchNo search-bar execution
Direct route visitNo 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

CaseMeasurement
Typed coffee, 535 matches, 15 page-1 itemsOne event: keyword coffee, page 1, count 15, success
Type coff, select coffee makerMeasure coffee maker, not coff. Totals do not set count
Committed empty pagepresented({ page: 1, resultCount: 0 }) yields empty
Failed load, then valid retryNo event on error. Same handle emits once after commit
Cancel, then deliberate retryOld handle stays inert. A new submission creates a new id
Pending coffee, then teaCancel coffee. Ignore its late navigation, fetch, and commit
Submit coffee againNew id may emit again on the same route text
Duplicate commit, rerender, page 2No additional performed event
Close panel while host results loadPending host measurement stays eligible
Leave the results routeCancel that route's captured id, not a newer search
Mixed case, padding, or a long termSearch uses the raw query. The event keyword is canonical and at most 200
Whitespace-only or fully redactedNo 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 fieldValue
typecom.augeo.conversation.launcher.activated
classmeasured
source.surfacesearch_panel
data.occurrence.activationSourcesearch-field
data.occurrence.hasSeedBoolean 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.