Complete reference for widget tags, HTML attributes, DOM events, and the JavaScript API.
Each widget type has its own custom element tag. Use the tag that matches the experience you want to embed.
| Tag | Widget Type |
|---|---|
| <rai-widget> | store |
| <rai-channel-widget> | channel |
| <rai-milestone-widget> | milestone |
| <rai-social-widget> | social |
| <rai-currency-widget> | currency-view |
All attributes are set as HTML attributes on the widget tag. Boolean attributes are enabled when present.
| Attribute | Type | Default | Description |
|---|---|---|---|
| widget-id | string | - | Required. Unique widget identifier from the admin panel. |
| widget-type | string | Inferred from tag | Widget type override. Usually inferred automatically from the tag name. |
| theme | "light" | "dark" | "light" | Visual theme. Applies to the widget chrome and iframe content. |
| width | string | "100%" | CSS width of the widget container. |
| height | string | "600px" | CSS height of the widget container. |
| api-url | string | - | Required. Base URL for the widget API. |
| widget-url | string | - | Required. Base URL for the hosted widget frontend. |
| auto-refresh | boolean | true | Automatically refresh auth tokens before expiry. |
| debug | boolean | false | Enable verbose console logging for troubleshooting. |
| eager | boolean | false | Load the widget iframe immediately instead of waiting for viewport intersection. |
| locale | string | "en" | Locale code for widget text and number formatting. |
| max-retries | number | 3 | Maximum number of auth retry attempts on failure. |
| retry-delay | number | 1000 | Milliseconds to wait between retry attempts. |
| height-debounce | number | 100 | Debounce interval (ms) for auto-height resize messages. |
| storage-prefix | string | "rai-" | Prefix for localStorage keys used by the widget. |
| retry-label | string | "Retry" | Label text for the retry button shown on auth errors. |
| custom-data | string (JSON) | - | JSON string of custom key-value data forwarded to the widget. |
| auth-url | string | - | URL for token authentication. The SDK will POST to this endpoint to obtain tokens. |
| data-email | string | - | User email for attribute authentication. Also sent as a header when calling auth-url for token auth. |
Widgets dispatch custom DOM events that bubble up from the element. Listen with addEventListener or framework equivalents.
| Event | Detail Payload | Fires When |
|---|---|---|
| rai-authenticated | { email: string } | Auth flow completes successfully and the user is identified. |
| rai-ready | { widgetId: string } | Widget iframe is loaded and ready to interact. |
| rai-error | { message: string; code?: string } | An auth or loading error occurs. |
| rai-logout | {} | The user session is cleared (token expired or manual logout). |
| rai-height-change | { height: number } | Widget content height changes (for auto-sizing containers). |
The SDK exposes a global object for imperative control. Use it to programmatically refresh or destroy widgets.
// Access the global API
const api = window.ReturningAIWidget
// Refresh a specific widget's auth token
api.refresh('YOUR_WIDGET_ID')
// Destroy a widget and clean up all listeners
api.destroy('YOUR_WIDGET_ID')
// Destroy all widgets on the page
api.destroyAll()
// Check if a widget is currently authenticated
const isAuthed = api.isAuthenticated('YOUR_WIDGET_ID')