Mobile Widget SDKs

# 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.
```

## Navigation

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.