Widget Viewer Documentation

Embed an existing Livstick message or viewer flow inline on your website. Two integration modes: React component or HTML script tag. A lightweight complement to the Livstick WebApp.

Quick Start API Reference

The WebApp remains the main viewing surface

The embedded viewer is a lightweight alternative for inlining a single message into a host site. For the full viewing experience — including reply messages and multi-message playback — continue to point recipients to the Livstick WebApp. Features released there land in the embedded viewer later, or not at all.

Installation

Install the viewer package from npm. Or skip installation entirely and use the script tag.

Install via npmbash

npm install @livstick/widget-viewer

Also available via:pnpm add @livstick/widget-vieweryarn add @livstick/widget-viewer

Peer dependencies: react >= 18 and react-dom >= 18. React 19 is fully supported.

Integration Modes

Choose between an HTML script tag or a React component. Use React mode whenever you need callbacks, style objects, or app-level composition.

HTML Script Taghtml

<div id="livstick-viewer-plugin"></div>

<script
  id="livstick-viewer"
  type="module"
  data-uid="abc123xyz9"
  data-domain="brand.example.com"
  data-api-url="https://api.public.v5.livstick.com"
  data-lang="fr"
  src="https://viewer.livstick.com/assets/widget-viewer.latest.js"
></script>

Required: type="module". The viewer script id is livstick-viewer, deliberately different from the recorder's livstick-widget, so both can coexist on the same page without collision.

Data Attributes

Attribute	Required	Description
`data-uid`	Yes	Viewer identifier / code identifier to display.
`data-domain`	Yes	Platform domain used by the viewer boot flow.
`data-api-url`	Yes	Base URL of the public API used by the viewer.
`data-lang`	No	Locale code (e.g. fr, en, de).
`data-api-key`	No	Optional public API key.

Mount Resolution

At runtime the bootstrap resolves the mount container in this order:

Order	Selector	Behavior
1	`#livstick-viewer-plugin`	Canonical viewer mount container.
2	`#livstick-plugin`	Shared alias (also used by the recorder widget).
3	Auto-created <div>	Appended to the script tag's parent element if neither mount exists.

Resolving a CRID into a viewer UID

The viewer needs a public uid, but your backend typically stores the internal crid (container identifier) returned when the message was created. Use the public API to resolve one into the other before rendering the widget.

Endpoint

GET

/v3/containers/{crid}

Returns all container details including the urid field. Pass it directly as the viewer's uid prop or data-uid attribute.

Resolve server-side, then injectjavascript

// Server-side (Node / edge function)
const res = await fetch(
  `https://api.public.v5.livstick.com/v3/containers/${crid}`,
  { headers: { 'X-API-Key': process.env.LIVSTICK_API_KEY } }
);
const { urid } = await res.json();
// urid is the viewer identifier — pass it directly to the widget

Inject the resolved uid into the script taghtml

<!-- Your server renders the urid into the template -->
<div id="livstick-viewer-plugin"></div>
<script
  id="livstick-viewer"
  type="module"
  data-uid="{{ urid }}"
  data-domain="{{ platformDomain }}"
  data-api-url="https://api.public.v5.livstick.com"
  src="https://viewer.livstick.com/assets/widget-viewer.latest.js"
></script>

Prefer resolving on the server so the CRID → UID mapping never leaks to the browser and so you can cache the result alongside your message metadata.

Customization

The viewer forwards any key in styleOverrides to the underlying user-flow as a CSS custom property. Keys are the variable name without the -- prefix.

styleOverrides exampletsx

<LivstickViewer
  uid="abc123xyz9"
  domain="brand.example.com"
  apiUrl="https://api.public.v5.livstick.com"
  styleOverrides={{
    // Typography
    fontFamilyTitle: '"Playfair Display", serif',
    H1ColorDark: '#1a1a2e',
    PColorDark: '#4a4a68',

    // Layout
    widgetPadding: '16px',
  }}
/>

What you can override

Any CSS custom property exposed by the Livstick viewer theme is accepted. Common categories include typography fontFamilyTitle, colors H1ColorDark, PColorDark, and layout widgetPadding. Refer to the recorder widget documentation for the full list — the viewer shares the same theme surface.

Keys named fontFace and widgetFontFace are filtered out — font loading is handled via the viewer's boot data, not via CSS variables.

Ready to transform your customer experiences?

Let's discuss your project and discover how LIVSTICK can help you create unforgettable moments.

Response within 24h

Personalized demonstration

No commitment