Returning.AIDevelopers
v1

Guides / Mobile Widget SDKs

.md

Mobile Widget SDKs

React Native

Embed Returning.AI custom widgets in a React Native CLI application or an Expo development build.

Package: @returningai/react-native-widget-sdk

Requirements

  • React 19.2 or later within the supported major version.
  • React Native 0.86, React Native WebView 16, and Node.js 22.13+.
  • Expo SDK 57 with a development build when using Expo.
  • An HTTPS client origin and a trusted embed-token backend.

Install the packages

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

Mount a custom widget

Import the component and configuration from the published package. The token provider calls your backend and returns only a fresh embed token.

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

const controller = new ReturningAIWidgetController();
const configuration = ReturningAIWidgetConfiguration.customBundle({
  widgetId: "YOUR_SUPPLIED_WIDGET_ID",
  bundleUrl: "YOUR_SUPPLIED_BUNDLE_URL",
  clientOrigin: "https://mobile-client.example",
  runtimeUrl:
    "https://unpkg.com/@returningai/widget-sdk/dist/rai-widget.iife.js",
});

export function RewardsScreen() {
  return (
    <ReturningAIWidget
      configuration={configuration}
      controller={controller}
      embedTokenProvider={async () => {
        return backend.fetchReturningAIEmbedToken();
      }}
      onExternalNavigation={(uri) => {
        appRouter.openExternal(uri);
      }}
    />
  );
}

Configure Web Crypto for Expo

Install expo-crypto and load this polyfill before the first widget mount when crypto.getRandomValues is unavailable.

polyfill-crypto.ts
import * as ExpoCrypto from "expo-crypto";

const webCrypto = globalThis.crypto;
if (
  webCrypto === undefined ||
  typeof webCrypto.getRandomValues !== "function"
) {
  Object.defineProperty(globalThis, "crypto", {
    configurable: true,
    value: {
      getRandomValues(array) {
        const bytes = ExpoCrypto.getRandomBytes(array.byteLength);
        new Uint8Array(
          array.buffer,
          array.byteOffset,
          array.byteLength,
        ).set(bytes);
        return array;
      },
    },
  });
}

Session lifecycle

  • Keep one ReturningAIWidgetController attached to one mounted widget.
  • The controller supports reload(), retry(), updateTheme(), logout(), and invalidate().
  • Unmount the widget on host logout. On account change, mount a new component with a stable, non-secret session key.
  • Do not cache a stale embed token after a session-expired event.

Return to the Mobile Widget SDK overview.