ExperienceWidget

Overview

<ExperienceWidget> is the homepage / support “floating widget” pattern: a collapsed corner preview that looks like ExperienceThumbnail, then expands to an in-page overlay when the user clicks. It is separate from the thumbnail (gallery cards stay cheap) and from a full-page <Experience> embed.

Pass only experience-id (and alt). On mount the widget calls GET /v1/experiences/{id}/preview to load gallery thumb plates — no API key and no origin allowlist. Session mint and allowlist checks happen only when the user expands.

Install

npm install @liforma/client

Surface	Import / tag
Vanilla / CMS	<liforma-experience-widget> via the CDN v2 script
Svelte	@liforma/client/svelte
React	@liforma/client/react
Next.js	@liforma/client/next (client component)

Hello world (HTML)

Use position=“bottom-right” or bottom-left (optional offset, default 16) for a paste-and-go corner FAB — ideal for CMS / WordPress. Default position=“static” fills the host so you can place size and offsets with your own CSS. On desktop, the open player can reduce to a draggable portrait dock (~50% of screen height, 9:16); mobile opens near full-screen with close only. Preview images load without an allowlist; add your site origin in app.liforma.ai before users expand (session mint).

index.html

<!-- Liforma SDK: registers <liforma-experience-widget> and window.Liforma -->
<script src="https://cdn.liforma.ai/sdk/v2/client.js"><\/script>

<!-- WordPress / CMS friendly: corner placement without host CSS -->
<liforma-experience-widget
  experience-id="exp_t0i7acmq"
  alt="Talk to our barista"
  position="bottom-right"
  offset="16"
></liforma-experience-widget>

<!-- Or position="static" (default) and wrap with your own fixed host CSS -->

Svelte / React

Widget.svelte

<script>
  import { ExperienceWidget } from '@liforma/client/svelte';
</script>

<ExperienceWidget
  experienceId="exp_t0i7acmq"
  alt="Talk to our barista"
  position="bottom-right"
  offset={16}
/>

SiteWidget.tsx

import { ExperienceWidget } from '@liforma/client/react';
// Next.js: import { ExperienceWidget } from '@liforma/client/next';

export function SiteWidget() {
  return (
    <ExperienceWidget
      experienceId="exp_t0i7acmq"
      alt="Talk to our barista"
      position="bottom-right"
      offset={16}
    />
  );
}

Loading model

When	What loads
Mount (collapsed)	Public preview API + CDN thumb plates (optional gallery-thumb skips the fetch)
Click expand (prefetch=“onExpand”)	Session mint + player iframe; Tap to talk unlocks audio
prefetch=“idle” / eager	Warms a transparent player iframe after idle / immediately so one click unlocks + expands

Mint options

Expand uses the same mint surface as <liforma-experience>: session-endpoint, language, mode, speech-input-mode, speech-only, fit, and start-button label.

Website assistant

Set website-assistant=“true” (or websiteAssistant={true}) so the widget reads bounded visible text from the host page and includes it on each managed conversation turn as untrusted reference data. Default is off.

• Does not change the scripted opening / starting phrase.
• Does not read form values, cookies, storage, or cross-origin iframes.
• Mark private sections with data-liforma-ignore.

• Enabling this sends extracted page text to the Liforma conversation pipeline (and the configured LLM provider). Keep private pages/sections out, or leave the flag off.

• Page text increases input tokens per turn (hard cap ~20k characters). Prefer Knowledge/RAG for durable site facts; use website assistant for “what is on this page right now.”

• Pass runtimeContext alongside website assistant when the page text and signed-in app data should appear on the same turn.

ExperienceWidget.svelte

<ExperienceWidget
experienceId="exp_…"
websiteAssistant={true}
runtimeContext={{
  first_name: user.firstName,
  account_plan: user.plan
}}
/>

website-assistant.html

<liforma-experience-widget
experience-id="exp_…"
alt="Ask about this page"
position="bottom-right"
website-assistant="true"
></liforma-experience-widget>

<section data-liforma-ignore>
<!-- never included in website-assistant context -->
</section>

vs ExperienceThumbnail

	Thumbnail	Widget
Role	Gallery / catalog preview	Site-wide conversation launcher
Thumb plates	Caller passes URLs	Fetched from preview API by default
Session / iframe	No (unless hosted launch)	Yes, after expand
Default open	Hosted player + returnUrl	In-page overlay

Example

Runnable demo: examples.liforma.ai — Experience widget (local http://localhost:4002 via ./start).