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
| Item | Requirement |
|---|---|
| Assistant | The existing authenticated loyalty assistant instance |
| Release | A compatible release exposing contextual open, subscribeContextualTurns, and PDP connectInteractionSource |
| Eligibility | A verified policy supplied through capabilities.productGuidance.checkEligibility |
| Host binding | A 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.