Configuration

Complete reference for widget tags, HTML attributes, DOM events, and the JavaScript API.

Widget Tags

Each widget type has its own custom element tag. Use the tag that matches the experience you want to embed.

Attributes

All attributes are set as HTML attributes on the widget tag. Boolean attributes are enabled when present.

DOM Events

Widgets dispatch custom DOM events that bubble up from the element. Listen with addEventListener or framework equivalents.

Public API

The SDK exposes a global object for imperative control. Use it to programmatically reload auth, log out, or inspect authentication state.

// Access the global API
const widget = window.ReturningAIWidget

// SDK version
widget.version                     // current SDK version

// Re-run the auth flow (e.g. after user logs in on your side)
await widget.reload()

// Clear tokens and remove the iframe
await widget.logout()

// Check authentication state
widget.isAuthenticated()           // boolean

// Inspect token metadata (no raw token values exposed)
widget.getTokenInfo()

Store callbacks (SDK 1.5.0+)

Store and custom-store widgets can ask your page for purchase field options at runtime. Use callbackFieldOptions when the selectable values must come from the broker's backend.

const widget = document.querySelector('rai-store-widget')

widget.registerCallback('callbackFieldOptions', async (payload) => {
  const response = await fetch('/api/returningai/store-field-options', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
  })

  return response.json() // { fieldOptions, signature }
})

widget.lockCallbacks()

Register callbacks on each widget element before calling widget.lockCallbacks(). The browser callback calls your backend, and your backend returns { fieldOptions, signature }. Mint the signature server-side - never call the ReturningAI callback-signature endpoint from browser code. This works in iframe and bundle mode. The SDK exports TypeScript types for payloads, results, and callbacks: StoreCallbackFieldOptionsPayload, StoreCallbackFieldOptionsResult, and ReturningAIStoreCallbackFieldOptionsCallback.