Augeo AI Docs
SDKs

For You widget

For You widget

The For You widget embeds reward recommendations in a host-owned container. It uses the loyalty concierge bundle and mounts independently of chat. The widget uses Shadow DOM without an iframe.

The host supplies placement, member authentication, theme options, and product-detail routing. Cards provide click-through selection without cart or wishlist controls.

Prerequisites

ItemRequirement
BundleAn approved loyalty concierge release that exports createForYouWidget
Mount nodeA CSS selector matching exactly one existing container
Member sessionA synchronous callback returning the current bearer token
Product routingA callback accepting the selected product ID and type
Recommendation serviceSupports the member's eligible catalog and the for_you placement

Choose a release

This page describes the current factory contract. Source documentation alone does not establish availability in a production release.

  1. Choose an approved production release containing the factory.
  2. Replace APPROVED_VERSION in the script URL with that release version.
  3. Confirm PKG_VERSION and feature-detect createForYouWidget before mounting.
<script src="https://sdks.augeoai.net/chat-sdk/loyalty-concierge/APPROVED_VERSION/index.js"></script>

Pin the version for member-facing traffic. Reserve the moving latest path for development. A successful script response does not prove the factory exists. Reuse an already loaded compatible loyalty bundle instead of loading it twice.

The production bundle supplies its API origin. Omit apiBaseUrl unless you require a supported override. The professional-assistant bundle does not export this factory.

Mount the widget

Create the container before calling the factory.

<div id="for-you"></div>

The example uses host-owned authentication, routing, error reporting, and disposal hooks. Implement those hooks in your application.

const sdk = window.AugeoChatSdkLoyaltyConcierge;

if (typeof sdk?.createForYouWidget !== 'function') {
  host.showWidgetError('Recommendations are unavailable.');
} else {
  const widget = sdk.createForYouWidget({
    container: '#for-you',
    auth: {
      getToken: () => host.getToken(),
      onFailure: (failure) => host.recoverToken(failure),
      getScope: () => host.memberScope(),
    },
    capabilities: {
      recommendations: {
        onProductSelect: ({ productId, productType }) =>
          host.navigateToProduct(productId, productType),
      },
    },
    onError: (error) => host.reportWidgetError(error),
  });

  host.onDispose(() => widget.destroy());
}

getToken returns a string synchronously and runs for each request. Recoverable authentication failures reach auth.onFailure; a deliberate retry reads the current token. getScope returns { memberId, programId } for the active session.

Destroy the widget before logout or a member or program change. Create a new instance afterward. Keep surrounding host controls usable during loading and failures. Handle script-load failure in your host loader.

Options and routing

OptionPurpose
containerRequired selector for the host mount node
auth.getTokenRequired current-member bearer token callback
auth.onFailureOptional credential recovery callback
auth.getScopeOptional member and program identity callback
capabilities.recommendations.onProductSelectRequired product-detail routing callback
capabilities.recommendations.productTypeOptional catalog product-type filter
capabilities.refinementOptional preference and THEO destination callback
capabilities.programChatProgram chat availability snapshot; see Without THEO chat
branding.themeOptional per-instance design-system theme
apiBaseUrlOptional API origin override
onErrorReceives sanitized initialization and runtime errors

Selection supplies { productId: number, productType: string }. The callback may return a Promise. The host maps that identity to its product-detail route. The SDK does not construct a product URL or navigate the page.

Standalone products, configurable products, and gift cards use the same callback. A product the catalog marks as potentially split-tender eligible shows a Points + USD pill without a cash amount. A pending selection suppresses another activation of that product. A rejected callback keeps the cards and allows another deliberate attempt.

surface: { type: 'inline' } configures chat, not this widget. Use createForYouWidget for recommendations.

Requests and refresh

Initial requests use GET /api/recommendations?limit=5&placement=for_you. Refresh adds exclude_product_ids containing the currently displayed IDs. The existing chat opener request remains separate.

Five distinct eligible products form the normal set. Short catalogs show available products without duplicates or filler. Show me more replaces the displayed set rather than appending cards.

Refresh requires refresh_supported: true and a valid replacement excluding every previously displayed ID. Missing or false support keeps the cards and changes the DS refresh control to Try again. A repeated initial request does not establish refresh support.

NameBehavior
refresh()Runs Show me more when the current state permits refresh
retry()Retries the failed initial, refresh, or capability-probe operation
destroy()Removes the widget child immediately, even from a detached parent
isDestroyedRead-only boolean. True after destruction or a failed mount
update(patch)Applies a same-scope capabilities.programChat change

refresh() and retry() return Promise<void> and coalesce while an operation is pending. Each recommendation operation settles or times out within ten seconds. There is no polling or automatic retry. Explicit destroy() is synchronous and idempotent. Later instance methods are no-ops.

Move and destroy

isDestroyed is a read-only boolean on the widget handle. It is false while the instance is live. It becomes true after terminal destruction and stays true.

An initialization failure still calls onError once with a sanitized error. The returned handle is inert and reports isDestroyed as true. refresh, retry, and destroy on that handle remain no-ops. A thrown or rejected onError result stays contained.

destroy() runs immediately and is safe to call twice. It removes the widget element even when the parent is detached. Later instance methods are no-ops.

A same-task move between connected parents keeps the same instance. Moving the widget or an ancestor counts. Opening or closing sidebar chat is that move. Items stay on the page. The widget does not show loading again or send a new recommendations request.

A disconnect still detached after one microtask destroys the widget. Reattaching that element does not revive the destroyed instance. Create a new widget on the connected container after destruction completes. That call mounts a live replacement and does not throw. A later-task reattach is not kept. Create a new instance for that case. Modal chat that does not move the page is unchanged.

Recovery states

ConditionDisplay and recovery
Initial loadingFive noninteractive skeleton tiles and an announced loading status
Initial errorAn error message with a deliberate initial retry
Unavailable serviceAn unavailable message with Try again
Empty catalogEmpty-only fallback message with Try again; no filler cards
Short catalogAvailable cards and an announced explanation of the short set
Refresh pendingExisting cards remain usable while more recommendations load
Refresh failure or overlapExisting cards remain; the DS refresh control reads Retry and repeats the exclusions
Refresh unsupportedExisting cards remain; the DS refresh control reads Try again and probes an initial request
Exhausted refreshExisting cards remain; Try again repeats the exclusion check
Product-routing failureExisting cards remain; routing feedback is announced; activate a card to retry

Successful refresh preserves focus on its initiating control. Status changes use a screen-reader-only widget-local announcement region. There is no standalone visible status row or separate retained-card retry row. Failures remain inside the widget; surrounding host navigation stays available.

Explanation and theme

The design system supplies the Recommended for you heading, default description, cards, spacing, and refresh presentation. The description's interests control opens the existing preferences destination. Verified recommendation provenance remains in the hidden announcement region and existing analytics.

Response sourceAnnounced explanation
historyBased on your history
wishlistBased on your wishlist
popularPopular rewards to explore
interestsBased on your interests
Missing or unrecognizedExplore these rewards

A generic personalized source does not establish that declared interests drove ranking. The widget keeps that provenance announcement generic.

branding.theme.bodyFontFamily overrides body typography for that instance. Otherwise the design-system sans family applies. Bundled Inter font faces are registered once per document without changing host-page typography. Allow data: in your font policy when using the bundled fonts.

Optional preference refinement

Set capabilities.refinement.activate to open quiz, preferences, or THEO through your host integration. The callback receives a typed destination and returns its outcome. Every input carries an opening for its destination. Make one call for all three destinations:

activate: async (input) => {
  assistant.open({ opening: input.opening });
  return { status: 'opened' };
},
DestinationopeningTHEO opens on
preferences'preferences'Shopping preferences
quiz'quiz'The interest quiz
theo'for_you_refresh'The For You message

None of the three sends a chat message or asks a model to navigate. The widget uses the DS interests entry for preferences. It does not render an external interests list, personalization button, preference button, or profile-read recovery controls.

THEO also receives the published refinement seed, entryPoint: 'for_you', autoSubmit: true, and conversation: 'fresh'. The for_you_refresh opening starts on the new-chat welcome and preserves prior history. A member with no saved interests is offered the quiz and preferences. A member with saved interests is offered up to three saved categories and preferences. An unread profile gets the saved-interests message with preferences only. Hosts that call assistant.open({ seed: input.seed, autoSubmit: true }) for THEO keep the auto-sent seed. Before the third successful refresh, show the recommendation feedback footer. After three successful disjoint refreshes, that footer is replaced by the native in-panel footnote. The footnote reads Refreshed a few times? Tell THEO more about what you're looking for. Its action is Chat with THEO. There is no separate prompt or dismissal action. Opening fails without replacing the cards; activate the same entry again to retry.

Return saved only after a confirmed preference save. Use { status: 'saved', returnPath: sdk.CONFIRMED_REFINEMENT_SAVE_RETURN } for that outcome. The widget then rereads the profile and requests initial recommendations without exclusions. Opened, requested, cancelled, failed, or uncertain outcomes do not confirm a save. Keep cards usable while opening a destination or reloading recommendations.

Recommendation feedback

A successful load with cards shows feedback under the cards before any Show me more press. The same controls appear when chat is enabled and when chat is off. Before the third successful refresh, the line reads How are these picks? Give us feedback:. That line does not mention refreshes. The footer has a thumbs up and a thumbs down. A thumb opens a local reason panel and does not save anything by itself.

ThumbReason chips
UpAccurate, Helpful, Clear, Complete, Other
DownInaccurate, Not helpful, Off-topic, Unsafe, Other

The panel includes a Share details (optional) text box. Submit accepts up to 2,000 characters. Send posts the thumb, selected reasons, and comment to /api/feedback. No chat session is created. Dismiss closes the panel without writing. A member can send with no reasons and no text. A saved status requires an HTTP 200 receipt for the submitted target.

Forward the feedback target from the displayed for_you response. Placement and source stay inside that server-signed target. Do not add a placement field, a thread id, or a default-placement token.

The controls stay after the first and second successful refreshes. After the third successful refresh with chat, the Chat with THEO footnote replaces the controls. After the third successful refresh without chat, the line becomes Refreshed a few times? Give us feedback:. The thumbs stay in that non-chat footer. Loading, empty, unavailable, and error states hide the controls. A feedback failure leaves the picks and host controls usable. Feedback does not reload recommendations or reset the refresh count.

Without THEO chat

Run For You without chat when THEO chat is off for the program. The widget does not need a chat assistant instance.

The catalog host owns the presentation snapshot. Map the resolved showRewardsAgent flag through the existing bootstrap helper. Literal true is enabled. Literal false is disabled. Loading, missing, invalid, or failed resolution is explicit unresolved. Pass the same snapshot to this widget and to Search. Do not add an entitlement endpoint.

interface ProgramChatScope {
  readonly programId: string;
  readonly authScopeKey: string;
}

type ProgramChatAvailability =
  | { readonly status: 'enabled'; readonly scope: ProgramChatScope }
  | { readonly status: 'disabled'; readonly scope: ProgramChatScope }
  | { readonly status: 'unresolved'; readonly scope: ProgramChatScope | null };

programId is the program ID. authScopeKey is an opaque, nonblank host generation for the authorization scope. Do not put a bearer token or raw member ID in it. A token, a refinement callback, or an assistant instance does not establish availability. Chat authorization stays a separate check.

InputPresentation
enabledExisting chat presentation
disabledNon-chat presentation
Explicit unresolvedNon-chat presentation
Malformed valueNon-chat presentation; recommendations stay usable
Omitted at creationLegacy chat presentation, not an entitlement

Pass capabilities.programChat at creation. Omit it only for an existing integration. A new integration passes enabled, disabled, or unresolved.

const widget = sdk.createForYouWidget({
  container: '#for-you',
  auth: {
    getToken: () => host.getToken(),
    onFailure: (failure) => host.recoverToken(failure),
    getScope: () => host.memberScope(),
  },
  capabilities: {
    recommendations: {
      onProductSelect: ({ productId, productType }) =>
        host.navigateToProduct(productId, productType),
    },
    programChat: {
      status: 'disabled',
      scope: { programId: host.programId(), authScopeKey: host.authScopeKey() },
    },
  },
  onError: (error) => host.reportWidgetError(error),
});

Non-chat presentation

The description reads Personalized picks based on what you’ve browsed, saved, or redeemed. The interests control and its preferences popover are not rendered. The Chat with THEO footnote is not rendered. Cards, Show me more, routing, and recovery states are unchanged. The feedback footer is present on first load. See Recommendation feedback. After three successful disjoint refreshes, the line becomes Refreshed a few times? Give us feedback:. The Chat with THEO footnote is not rendered. When the recommendation response carries no feedback metadata, the cards stay and submit is disabled.

Change availability

widget.update({ capabilities: { programChat: nextSnapshot } });

update changes availability only. It does not replace auth, recommendations, refinement, or branding. An omitted programChat keeps the previous snapshot. It cannot restore the omission default. A same-scope change repaints in place. It does not remount, reread the profile, refresh recommendations, or reset the refresh count.

A snapshot with a different non-null scope does not enable the new principal. The widget falls back to the non-chat presentation and ignores later availability updates. For a program or authorization-scope change, call destroy(), replace the credential scope, and create a new instance with the new snapshot. Token rotation for the same member keeps the instance and its snapshot.

Design-system compatibility gaps

The pinned @kigo-digital/design-system@0.14.0-alpha.5 supports the native footnote and retained-card retry through its public refresh control. Its empty phase has no content or retry slot, so the empty-only SDK fallback remains. It has no in-panel status slot for retained-card refresh or routing failure copy; those messages use the hidden live region.

The footnote exposes no element ref or action pending/disabled styling. Footnote exposure measurement awaits a public DS ref API and connection to the existing visibility measurement. Mounting the footnote is not evidence that a member viewed it. The SDK owns the existing activation events and omits DS action IDs to avoid duplicate click events.

TopicPage
Loyalty bundle installationQuick start
Theme optionsBranding
Public host typesAPI
Integration failuresCommon issues