Configuration

The four mobile packages share one custom-widget contract. Platform spelling differs, but the configuration responsibilities stay the same.

Required values

Widget ID: Copy the supplied URL-safe custom-widget ID unchanged. Do not use a raw Mongo ObjectId or derive an ID from a bundle filename.
Bundle or page URL: Use the URL supplied for this widget and environment. Bundle content maps to ReturningAIWidgetContent.bundle; hosted content maps to ReturningAIWidgetContent.page.
Client origin: Use the exact HTTPS origin allowlisted on this widget. It has no path, query, fragment, or user information.
Token provider: Fetch a current embed token from the host backend. The configuration object never accepts Returning.AI access credentials.

Widget runtime

Mobile examples use the latest public Widget SDK runtime:

runtime URL

https://unpkg.com/@returningai/widget-sdk/dist/rai-widget.iife.js

The field is named runtimeUrl in Flutter, Android, and React Native, and runtimeURL in Swift.

Standard hosts are built in

Endpoint presets and domain keys are optional. Set them only when Returning.AI supplies environment-specific values.

Display, theme, and locale

Choose light, dark, or system theme through the platform theme type.
Use display options for initial height, automatic height, bounds, loading text, background color, and automatic refresh.
Set one locale value. The SDK writes compatible locale and language attributes for the widget runtime.
Use distinct, non-secret storagePrefix values when multiple widgets appear on one screen.

Events

Each package exposes typed mounted, ready, logout, session-expired, height-change, error, and external-navigation events. Other nonempty runtime event names may arrive as custom events with JSON-compatible detail.

Host callbacks

Default callback names are callbackFieldOptions, storePurchaseSuccess, and milestoneCtaClick. Register a handler for every callback the host intends to serve. Missing handlers fail closed with a sanitized error.

An explicit callback list replaces defaults

Passing an empty callback-name collection removes the default allowlist. It does not merge with the defaults.

Callbacks such as field options may require a server signature. Mint the signature on the backend.

callback-signature.http

POST https://api-v2.returning.ai/v2/api/widget-access-keys/callback-signature
Content-Type: application/json
Authorization: <server-side credentials>

// Send and sign the callback payload from your backend.
// Never place signing credentials in the mobile app.

The SDK keeps configured HTTPS hosts inside its WebView. It delegates an off-allowlist HTTPS main-frame or new-window URL through onExternalNavigation. Open that URL through the host application. Unknown schemes and plain HTTP are rejected outside an explicit localhost debug configuration.

Debug mode

Production URLs must use HTTPS. Enable debug only for explicit localhost HTTP development. Never broaden this exception to a remote insecure host.