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

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.

Install the package

flutter pub add returningai_widget

Android host applications must also declare internet access in android/app/src/main/AndroidManifest.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.

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);
  },
);

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 for the shared integration sequence.