Widget SDK

Drop-in Web Components with Access Key authentication and bundle mode rendering. Framework-agnostic, works with React, Vue, Angular, or plain HTML.

Install

If you use a bundler (Vite, Next.js, Webpack), install via npm:

npm install @returningai/widget-sdk

Or skip the install and load the SDK from a CDN - see the attribute auth example below.

Quickstart: Access Key + Bundle Mode

The recommended setup. Your backend exchanges access credentials for a 15-minute JWT. The widget renders directly in the page DOM (bundle mode) for native scrolling and CSS integration.

<rai-store-widget
  community-id="YOUR_COMMUNITY_ID"
  api-url="https://prod-widgets.returning.ai"
  v2-api-url="https://api-v2.returning.ai"
  embed-token="TOKEN_FROM_YOUR_SERVER"
  domain-key="PROD"
  data-user-id="USER_ID"
  data-user-objectid="USER_OBJECT_ID"
  data-username="USERNAME"
  bundle-url="https://prod-widgets.returning.ai/store-widget/bundle/widget.js"
  theme="dark"
  width="100%"
  height="600px"
></rai-store-widget>

See the Auth - Access Key guide for the full walkthrough including backend setup and token lifecycle.

Alternative: Attribute Auth

If you don't have backend access, you can identify users by passing data-* attributes directly on the widget element. See the Auth - Attribute guide.

Bundle mode vs Iframe mode

The SDK supports two rendering modes:

	Bundle Mode (recommended)	Iframe Mode
Trigger	Set `bundle-url`	Default (no `bundle-url`)
DOM	Light DOM - widget renders in page	Shadow DOM + iframe
CSS	Page CSS cascades into widget	Fully isolated
Scrolling	Native page scrolling	Separate scroll context

See Architecture for more details on rendering modes.

Customize

Every widget accepts HTML attributes for common options:

theme - "light" or "dark" (default: "light")
width / height - any CSS length value

For the full attribute reference, see the Configuration page.

Guides

Auth - Access Key

Server-issued embed tokens with bundle mode rendering. The recommended approach for production.

Auth - Attribute (Legacy)

Identify users by passing data attributes directly on the widget element. No backend required. For new integrations, use Access Key auth instead.

Frameworks

React, Vue, Angular, and plain HTML examples.

Configuration

Every attribute, event, and global API method.

Architecture

Rendering modes (bundle vs iframe), auth flow, and token lifecycle.