Mobile Widget SDKs

# Flutter

Use the official Flutter package to host Returning.AI custom widgets in an existing Android or iOS application.

Package: [returningai_widget](https://pub.dev/packages/returningai_widget)

## Requirements

- Flutter 3.38 or later and Dart 3.10 or later.
- Android API 24 or later, or iOS 13 or later.
- An HTTPS client origin allowlisted for the target widget.
- A trusted backend that returns freshly minted embed tokens.

> Android and iOS only
>
> This package hosts a native WebView on Android and iOS. Flutter web, desktop, and other platforms are not supported by this SDK.

## Install the package

`terminal`

```bash
flutter pub add returningai_widget
```

Android host applications must also declare internet access in `android/app/src/main/AndroidManifest.xml`.

`AndroidManifest.xml`

```xml
<uses-permission android:name="android.permission.INTERNET" />
```

## Mount a custom widget

Copy the widget ID and matching bundle URL from your Returning.AI handover. The token provider calls your backend and returns only the short-lived embed token.

`returning_ai_widget.dart`

```dart
final controller = ReturningAIWidgetController();

ReturningAIWidget(
  controller: controller,
  configuration: ReturningAIWidgetConfiguration.customBundle(
    widgetId: 'YOUR_SUPPLIED_WIDGET_ID',
    bundleUrl: Uri.parse('YOUR_SUPPLIED_BUNDLE_URL'),
    clientOrigin: Uri.parse('https://mobile-client.example'),
    runtimeUrl: Uri.parse(
      'https://unpkg.com/@returningai/widget-sdk/dist/rai-widget.iife.js',
    ),
  ),
  embedTokenProvider: () async {
    return backend.fetchReturningAIEmbedToken();
  },
  onEvent: (event) {
    if (event is ReturningAIWidgetSessionExpired) {
      debugPrint('The next authentication request needs a fresh embed token');
    }
  },
  onExternalNavigation: (uri) {
    appRouter.openExternal(uri);
  },
);
```

> clientOrigin is not a Flutter route
>
> Use the exact HTTPS origin allowlisted for this widget. The SDK sends it as the authentication request's Origin header. Do not substitute a Navigator route, bundle identifier, or Android package name.

## Own the session lifecycle

- Keep the widget mounted while the same signed-in user owns the session.
- Return a fresh embed token when the SDK authenticates after `ReturningAIWidgetSessionExpired`.
- Use the controller for `reload()`, `retry()`, `updateTheme()`, `logout()`, and `invalidate()`.
- Remove the old widget immediately on host logout or account change, then create a new surface for the new user.

Return to the [Mobile Widget SDK overview](https://docs.returning.ai/mobile-widget-sdk.md) for the shared integration sequence.