Reference

Configuration

Start with the three required custom-widget attributes. Add presentation options or environment overrides only when the integration needs them.

Required attributes

Common attributes

Language codes and fallback

SDK 1.8.11 accepts these language codes: en, de, es, fr, it, pt, pl, da, nl, ru, chs, el, ko, cht, th, ja, id, vt, ms, hi, fil, ta, tr, ar, mn, sw.

Regional tags are normalized: fr-FR selects fr, zh-Hans or zh-CN selects chs, zh-Hant or zh-TW selects cht, and vi selects vt. Unsupported or malformed values are not forced; a non-empty invalid value warns once and leaves browser-language fallback to the widget.

This is SDK language selection, not a promise of translated content in every bundle. Ask the setup owner which translations and fallback the supplied widget supports, and record a visible check for each required locale in the handover.

Advanced environment overrides

The current SDK already defaults to Returning.AI production hosts. Do not copy these overrides into a normal production embed.

DOM events

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

widget.addEventListener('rai-authenticated', () => {
  console.log('Widget user authenticated')
})

widget.addEventListener('rai-mounted', () => {
  console.log('Widget bundle mounted')
})

widget.addEventListener('rai-session-expired', async () => {
  const response = await fetch('/api/widget-token')
  const { embedToken } = await response.json()
  widget.setAttribute('embed-token', embedToken)
})

widget.addEventListener('rai-error', (event) => {
  console.error(event.detail.message)
})

JavaScript API

The SDK exposes one global controller after it loads.

const sdk = window.ReturningAIWidget

sdk.version
sdk.isAuthenticated()
sdk.getTokenInfo()

await sdk.reload()
await sdk.logout()

Bundle callbacks

Register callbacks on the specific custom element before calling lockCallbacks(). Store bundles may also use callbackFieldOptions to request signed choices from your backend.

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

widget.registerCallback('storePurchaseSuccess', (purchase) => {
  console.log('Purchase completed', purchase)
})

widget.registerCallback('milestoneCtaClick', ({ buttonName }) => {
  console.log('CTA clicked', buttonName)
})

widget.lockCallbacks()

Legacy attributes

These fields remain documented for existing integrations. They are outside the custom-widget starter path.

See Architecture for the custom bundle lifecycle.