Augeo AI Docs
SDKs

Product-page handoff

Product-page handoff

The host team owns the product-page component, buttons, loading states, accessibility, page lifecycle, and host integration. The AI integration owns backend generation, authoritative eligibility, event contracts, and wiring into the existing Chat SDK. The component is not delivered as a standalone product-page SDK. The AI integration defines the technical contract; the host team implements it using existing host patterns.

Prerequisites

ItemRequirement
AssistantThe existing authenticated loyalty assistant instance
ReleaseA compatible release exposing contextual open, subscribeContextualTurns, and PDP connectInteractionSource
EligibilityA verified policy supplied through capabilities.productGuidance.checkEligibility
Host bindingA component and registered activation handler connected to the authenticated API/proxy path

The component binding requires implementation and verification. Verify the authoritative business-policy source before enabling guidance. This contract uses existing activation and contextual APIs without a new incoming launch event or public adapter API. Keep guidance disabled until the actual policy and integration are verified.

Capture a private selection

Capture the product and selected prompt in an immutable local snapshot. Use a canonical positive-safe-integer productId and preserve page or selected intent. A selected denomination uses its own catalog ProductId.

Keep the question and label in private execution state and authenticated chat transport. Exclude them from the outward event bus, telemetry callbacks, and analytics. Join permitted activation identifiers to the private snapshot. Do not match selections by text, timing, or the currently visible product.

Use the registered com.augeo.ui.action.pressed chip activation pattern for native controls. Use type version 1, actionKind: 'chip', and the canonical prompt ID as actionId. Bind permitted action/event identifiers to the private component selection. The public event describes activation; its host handler invokes the contextual API.

The local contextual subscription can contain the complete context. Never forward its full objects to analytics. Project only fields allowed by the installed event contracts and destination policy.

Open the existing assistant

The example uses an existing assistant and a private validated selection. The outcome callbacks belong to the host application.

const unsubscribe = assistant.subscribeContextualTurns((event) => {
  if (event.type === 'observation') {
    observeLogicalOutcome(event.observation);
  }
});

assistant.open({
  context: {
    version: 1,
    source: 'pdp',
    product: capturedSelection.product,
    prompt: {
      id: capturedSelection.prompt.id,
      text: capturedSelection.prompt.question,
      kind: capturedSelection.prompt.kind,
    },
  },
  signal: selectionLifetime.signal,
  onHandoff: observeCallerOutcome,
});

Subscribe before opening and unsubscribe when the listener's owner is disposed. Listener removal does not cancel the shared logical turn. Contextual open automatically submits the selected question and preserves the active authorized conversation and unsent draft. The existing thread flow creates a conversation when none is active.

Connect PDP observations

Use connectInteractionSource({ kind: 'pdp-guidance', ... }) on the existing assistant. The SDK consumes registered observations and derives the measured selection, request, and admission facts from its existing contextual-turn owner. The host team owns rendering, visibility measurement, and native activation. The connection takes metadata only; it does not take a DOM root or require a particular UI framework or component.

const input = assistant.connectInteractionSource({
  kind: 'pdp-guidance',
  mountEpoch: pageLifetimeId,
  productId: product.productId,
  selection: product.selection,
  authorityEpoch: memberProgramEpoch,
  policyValidity: policyRevision,
  promptSetId: finalPromptSetId,
  prompts: finalPrompts.map(({ id, kind }) => ({ id, kind })),
  scopeKey: memberProgramScope,
});

// Inside the host's deliberate activation handler, using its captured selection:
input.observe(nativePress);
assistant.open({
  context: capturedContext,
  signal: selectionLifetime.signal,
  onHandoff: observeCallerOutcome,
});

// When the host retires this presentation:
input.dispose();

The variables in this example belong to the host. promptSetId is a UUID for the final offered set. prompts contains two fixed prompts, affordability then comparison, optionally preceded by generated-1 through generated-3 in order. Each entry contains only id and kind; its question stays private. mountEpoch, authorityEpoch, policyValidity, and scopeKey are opaque lifetime/revision keys, never credentials. Keep them stable for equivalent updates and same-member credential refreshes. Change them when their owning page, authority, policy, or member/program scope changes. Optional programId, placementId, and participantRef must meet the event contract's privacy rules.

The returned input has presentationId: string | null, observe(event: unknown), and dispose(). A null ID means observation is unavailable or the registration is invalid. Functional open still works independently. Reconnecting with an equivalent snapshot preserves the presentation ID; a changed snapshot gets a new one. Only the newest input accepts observations. Disposing an older input cannot retire its replacement. Disposing the current input stops reporting for that scope without cancelling Chat's logical turn. Destroying the assistant makes every input inert.

Feed com.augeo.ui.action.pressed directly into this input in the same handler immediately before open, using source.surface: 'suggested_prompt_chip', the canonical prompt ID as actionId, actionKind: 'chip', and the actual inputMethod. Keep the original event ID, timestamp, source instance, and optional gesture key. Programmatic presses do not qualify. Do not replay a page-wide event bus into the input or send a second copy to event intake. The SDK removes any label before outward publication. It does not add design-system provenance to a native host control.

For an impression, the host reports a registered com.augeo.ui.component.viewed only after at least 50% of the final eligible prompt group has been visible for 1,000 continuous milliseconds. The host resets dwell on hiding, suppression, detachment, or loss of visibility. Set source.surface: 'pdp_guidance' and source.instanceId to this input's presentationId. The existing catalog uses componentName: 'SuggestedPromptGroup', exposureMs at least 1000, and threshold: { ratio: 0.5, ms: 1000 }. That component name is the catalog's logical group identifier; it does not assert that a design-system component rendered the UI. Omit augds provenance for native controls. The SDK validates the observation and derives one impression per presentation. It does not inspect the host DOM or infer that a mounted group was viewed.

Keep one collection owner: this SDK publishes the minimized facts through its existing event publisher and analytics pipeline. The host supplies observations and private execution context; it does not author the SDK's measured facts. Never await measurement delivery before opening Chat.

Confirm admission

open() returns void. Requested, opened, and submitted observations do not establish durable admission. Use matching admitted proof with clientTurnId, threadId, and userMessageId. Keep the same logical identity during uncertain delivery and reconciliation. Never replay a possibly admitted turn under a new identity.

augeo.event reports registered facts and effects; augeo.ack answers effects. Neither is a documented incoming product-page launch command. Sending telemetry does not execute a chat turn.

Preserve eligibility and lifetime

Only literal true from the eligibility callback permits activation. Explicit exclusion returns false; unknown or unavailable policy cannot enable a turn. The backend independently checks authenticated access, product facts, and policy.

The host invalidates obsolete prompt results and clears unsupported presentation. Navigation does not retarget an already captured deliberate selection. The Chat owner preserves credential replacement, caller cancellation, queue behavior, and post-dispatch reconciliation. The optional signal is local caller control and is never serialized.

Apply the defined event identity and registered profile to the actual component before enabling measurement. Keep one collection owner and remove labels before outward publication. Host UI ownership does not grant permission to author Chat SDK-origin events.