returningai_widget

Embed ReturningAI custom product widgets in Flutter apps on Android and iOS.

The SDK authenticates in Dart and gives the WebView only a short-lived access token. Hosts custom rai-custom-widget bundle and page content.

Install

dependencies:
  returningai_widget: ^0.1.2

Requirements:

• Flutter 3.38+
• Dart 3.10+
• Android API 24+
• iOS 13+

Android apps must declare internet permission:

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

Usage

final controller = ReturningAIWidgetController();

ReturningAIWidget(
  controller: controller,
  configuration: ReturningAIWidgetConfiguration.customBundle(
    widgetId: 'YOUR_WIDGET_ID',
    bundleUrl: Uri.parse(
      'https://widgets.example/custom-widget/bundle/store/widget.js',
    ),
    clientOrigin: Uri.parse('https://mobile-client.example'),
  ),
  embedTokenProvider: () async => hostMintedEmbedToken,
  onEvent: onEvent,
  onError: onError,
  onExternalNavigation: onExternalNavigation,
);

clientOrigin must be the exact HTTPS origin allowlisted for the widget in ReturningAI. It is not a Flutter route or app URL.

Mint embed tokens on your backend. Do not put accessId, accessKey, or embed tokens in the app, HTML, bridge, or WebView URLs.

Pin runtimeUrl in production. The default is unpkg @returningai/widget-sdk latest.

Controller

await controller.reload();
await controller.retry();
await controller.updateTheme(ReturningAIWidgetTheme.dark);
await controller.logout();
await controller.invalidate();

On ReturningAIWidgetSessionExpired, return a freshly minted embed token from embedTokenProvider. Call invalidate() when the host user signs out.