@returningai/react-native-widget-sdk

Embed ReturningAI custom product widgets in React Native CLI and Expo apps.

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

Install

npm install @returningai/react-native-widget-sdk react-native-webview

Peer dependencies:

• react ^19.2
• react-native ^0.86
• react-native-webview ^16
• Node.js 22.13+

Expo hosts need SDK 57 and a dev client (expo run:ios / expo run:android). Expo Go is not supported.

Install Web Crypto before the widget loads:

• Expo: expo-crypto
• React Native CLI: react-native-get-random-values

Usage

import {
  ReturningAIWidget,
  ReturningAIWidgetConfiguration,
  ReturningAIWidgetController,
} from "@returningai/react-native-widget-sdk";

const configuration = ReturningAIWidgetConfiguration.customBundle({
  widgetId: "YOUR_WIDGET_ID",
  bundleUrl: "https://widgets.example/custom-widget/bundle/store/widget.js",
  clientOrigin: "https://mobile-client.example",
});

const controller = new ReturningAIWidgetController();

<ReturningAIWidget
  configuration={configuration}
  embedTokenProvider={async () => hostMintedEmbedToken}
  controller={controller}
  onEvent={onEvent}
  onError={onError}
  onExternalNavigation={onExternalNavigation}
/>;

clientOrigin must be the exact HTTPS origin allowlisted for the widget in ReturningAI.

Mint embed tokens on your backend. Do not put accessId, accessKey, or embed tokens in the app, HTML, bridge, injectedJavaScript, 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("dark");
await controller.logout();
await controller.invalidate();

reload() replays the in-memory HTML shell. It does not call native WebView.reload().

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