# React Native & Flutter

The Chat Embed SDK is browser-only: it creates an `<iframe>` via `document`, listens on `window` `message` events, and posts to `iframe.contentWindow`. A mobile JS runtime has none of those, so `CherryEmbed` cannot run directly in React Native or Dart. The supported approach on mobile: run the SDK inside a WebView on a small **host page**, and bridge wallet signing out to the native layer (Mobile Wallet Adapter on Android, a deeplink wallet on iOS).

> **Warning:** Do not point the WebView straight at `embed.cherry.fun`. The SDK's `signChallenge` bridge rejects when `window.parent === window`, so the embed must be nested in an iframe on a host page, never loaded as the top-level document.

Runnable, copy-paste examples live in the public SDK repo: [`example/react-native/`](https://github.com/cherrydotfun/chat-embed-sdk/tree/main/example/react-native) and [`example/flutter/`](https://github.com/cherrydotfun/chat-embed-sdk/tree/main/example/flutter). One shared host page serves both platforms (it auto-detects the bridge).

## Why a naive setup fails

Three separate walls, in the order people usually hit them:

1. **The SDK is DOM-only.** Importing `CherryEmbed` into React Native and calling `mount()` throws: there is no `document` or `iframe`. The SDK must live in a WebView.
2. **The embed requires a parent frame.** Loaded as the WebView's top document, the iframe-side bridge sees `window.parent === window` and never sends the `signChallenge` request, so signing never starts.
3. **There is no `window.phantom` in a mobile WebView.** On mobile the wallet lives in the native layer, so the signature must cross the WebView-to-native boundary.

## Architecture

```
Native app (wallet: MWA on Android / deeplink on iOS)
   |  inject JS  <->  message channel
   v
WebView -> host page (runs the CherryEmbed SDK, creates the iframe)
   v
iframe -> embed.cherry.fun (the chat)
```

- **Host page**: a minimal HTML page that loads the SDK bundle and calls `new CherryEmbed({ ... })`. Its `signChallengeHandler` does not sign anything itself; it forwards the challenge bytes to native and awaits the signature.
- **Native wrapper**: a WebView component that sends config down, receives sign requests, signs with the real wallet, and injects the signature back.

Both are already written for you: `CherryChatWebView.tsx` (React Native), `cherry_chat_webview.dart` (Flutter), and the shared `host.html` in the SDK repo implement the full bridge protocol.

## Bridge protocol

Native to host page (global functions on the page, called via injected JS):

| Call | Purpose |
|---|---|
| `window.__cherryReceiveConfig(json)` | Deliver config and mount / remount the chat. |
| `window.__cherrySignResult(id, signatureB64, errorOrNull)` | Resolve a pending `signChallenge`. |
| `window.__cherryCommand(method, paramsJson)` | Imperative SDK calls: `setWalletAddress`, `setToken`, `setRoom`, `setTheme`, `signOut`, `show`, `hide`. |

Host page to native (JSON messages over the platform channel):

| Message | Meaning |
|---|---|
| `{ type: 'ready' }` | Page loaded, ready for config. Native replies with `__cherryReceiveConfig`. |
| `{ type: 'sign', id, message }` | `signChallenge` fired; `message` is the base64 challenge bytes. Native signs and replies with `__cherrySignResult`. |
| `{ type: 'event', event, data }` | A forwarded SDK event (`ready`, `mounted`, `authStateChange`, `unreadCount`, `message`, `tokenExpired`, `error`, `walletConnectRequested`, `preview`, `roomChanged`). |

## Two ways to ship the host page

| | Hosted | Bundled |
|---|---|---|
| Host page lives | on your web server (`host.html`) | inside the app binary (a string) |
| WebView source | `{ uri }` / `loadRequest(url)` | `{ html }` / `loadHtmlString(html)` |
| Update the host page | redeploy web, no app release | ship an app release |
| Page origin | your https origin | none (`null`) |
| Allowed origins entry | `https://yoursite.com` | `null` (or prefer Hosted) |

Both variants still fetch the SDK bundle and the chat iframe over the network; the chat is a hosted iframe either way.

## Hosting the SDK bundle

The host page loads the SDK as a global (`window.CherryEmbedSDK`), the IIFE build (`dist/index.global.js`, ~10 KB).

- **Cherry-hosted (default):** `https://embed.cherry.fun/cherry-embed.js`. A rolling URL, same origin as the chat iframe, refreshed on each embed deploy and short-cached. Nothing to host yourself.
- **Self-hosted:** build the SDK (`npm run build`) and serve `dist/index.global.js` as `application/javascript`, next to your host page or on any CDN. Pin a hashed filename if you need a frozen version.

## Auth modes on mobile

The same [auth modes](https://portal.cherry.fun/docs/embed/authentication.md) apply, with one mobile-specific rule for the wallet-backed modes: never rely on the iframe's built-in web wallet adapter; drive signing natively through the bridge.

- **`wallet-only`**: no backend, no token. Pass `walletAddress` and wire the sign callback.
- **`app-trusted+wallet`**: your backend mints a short-lived embed token bound to the wallet; the user also signs the challenge. Pass `token` + `walletAddress` + the sign callback.
- **`app-trusted`** (zero-signature, self-serve in the portal): token only; `onSign` never fires. See the no-signing path below.

### app-trusted: the no-native-signing path

Pure `app-trusted` removes the entire wallet layer from the mobile integration. The WebView host page path still applies (the SDK is still browser-only), but everything wallet-related drops out:

- **Skip the wallet modules.** Don't copy `wallet.ts` / `wallet.dart`, and don't install the signing dependencies: no `@solana-mobile/mobile-wallet-adapter-protocol-web3js`, no `solana_mobile_client`, no deeplink wallet packages, no `<queries>` / URL-scheme platform setup. Only the WebView package is needed.
- **Skip the callbacks.** Don't pass `onSign` or `onWalletConnectRequested`; neither ever fires with a valid token.
- **Skip `walletAddress`.** The app never learns the wallet; the token's `sub` claim carries it.
- **Fetch the token from your backend** right before showing the chat and pass it in the bridge config's `token` field. The backend derives the wallet from its own authenticated session; the app sends nothing but the session credentials it already has.

```tsx
const [token, setToken] = useState<string>();

useEffect(() => {
  fetch('https://yoursite.com/api/cherry-embed-token', { method: 'POST' })
    .then((r) => r.json())
    .then(({ token }) => setToken(token));
}, []);

if (!token) return null; // mint fresh right before showing the chat

<CherryChatWebView
  source={{ html }}
  config={{ appId: 'YOUR_EMBED_ID', roomId: 'YOUR_ROOM_ID', token }}
  // No onSign, no onWalletConnectRequested: the token alone authenticates.
/>
```

`authStateChange` arrives with `true` shortly after mount (the token exchange), without any wallet round-trip. Note the mode's server-side restrictions (fail-closed room allowlist, message rate limits): a `403` or `429` there is policy, not a broken integration; see [Authentication](https://portal.cherry.fun/docs/embed/authentication.md).

## React Native

Install the WebView (plus MWA for Android signing):

```bash
npm install react-native-webview
npm install @solana-mobile/mobile-wallet-adapter-protocol-web3js @solana/web3.js
```

Copy [`CherryChatWebView.tsx`](https://github.com/cherrydotfun/chat-embed-sdk/blob/main/example/react-native/CherryChatWebView.tsx) and [`wallet.ts`](https://github.com/cherrydotfun/chat-embed-sdk/blob/main/example/react-native/wallet.ts) into your app, then render:

```tsx
import { CherryChatWebView, type CherryChatWebViewRef } from './CherryChatWebView';
import { connectWallet, signMessageWithWallet } from './wallet';

function ChatScreen() {
  const chatRef = useRef<CherryChatWebViewRef>(null);
  const [walletAddress, setWalletAddress] = useState<string>();

  return (
    <CherryChatWebView
      ref={chatRef}
      // Hosted host page; or source={{ html }} with buildCherryHostHtml()
      source={{ uri: 'https://yoursite.com/cherry-host.html' }}
      config={{
        appId: 'YOUR_EMBED_ID',
        roomId: 'YOUR_ROOM_ID',
        walletAddress, // set after the user connects
        // token: embedToken, // app-trusted+wallet only
        theme: { mode: 'dark', primaryColor: '#FF5BA8' },
      }}
      // Native signing: MWA on Android, deeplink wallet on iOS
      onSign={signMessageWithWallet}
      onWalletConnectRequested={async () => {
        const address = await connectWallet();
        setWalletAddress(address); // re-sends config, iframe starts signChallenge
      }}
      onEvent={(event, data) => {
        if (event === 'authStateChange') console.log('authenticated:', data);
      }}
    />
  );
}
```

For the bundled variant, build the page string with [`buildCherryHostHtml()`](https://github.com/cherrydotfun/chat-embed-sdk/blob/main/example/react-native/cherryHostHtml.ts) and pass `source={{ html }}`:

```tsx
const html = buildCherryHostHtml({ sdkUrl: 'https://embed.cherry.fun/cherry-embed.js' });
<CherryChatWebView source={{ html }} config={...} onSign={signMessageWithWallet} />
```

Full runnable apps: [`App.hosted.tsx`](https://github.com/cherrydotfun/chat-embed-sdk/blob/main/example/react-native/App.hosted.tsx) (app-trusted+wallet) and [`App.bundled.tsx`](https://github.com/cherrydotfun/chat-embed-sdk/blob/main/example/react-native/App.bundled.tsx) (wallet-only).

## Flutter

Same architecture, same host page, same bridge protocol; only the WebView plumbing differs:

| Concern | React Native | Flutter (`webview_flutter`) |
|---|---|---|
| Page to native | `window.ReactNativeWebView.postMessage` + `onMessage` | `JavaScriptChannel('CherryNative')` |
| Native to page | `webview.injectJavaScript(js)` | `controller.runJavaScript(js)` |
| Load hosted page | `source={{ uri }}` | `controller.loadRequest(Uri.parse(url))` |
| Load bundled page | `source={{ html }}` | `controller.loadHtmlString(html, baseUrl: ...)` |

Copy [`cherry_chat_webview.dart`](https://github.com/cherrydotfun/chat-embed-sdk/blob/main/example/flutter/lib/cherry_chat_webview.dart) and [`wallet.dart`](https://github.com/cherrydotfun/chat-embed-sdk/blob/main/example/flutter/lib/wallet.dart) into your app, then render:

```dart
CherryChatWebView(
  source: CherryChatSource.url('https://yoursite.com/cherry-host.html'),
  config: CherryChatConfig(
    appId: 'YOUR_EMBED_ID',
    roomId: 'YOUR_ROOM_ID',
    walletAddress: walletAddress, // set after the user connects
  ),
  onSign: signMessageWithWallet, // native MWA (Android) / Phantom deeplink (iOS)
  onWalletConnectRequested: connect,
  onEvent: (event, data) {
    if (event == 'authStateChange') debugPrint('authenticated: $data');
  },
)
```

Flutter-specific rules:

- **Name the `JavaScriptChannel` exactly `CherryNative`.** The shared host page tries `window.ReactNativeWebView` first, then `window.CherryNative`.
- **`JavaScriptMode.unrestricted`** is required.
- **`loadHtmlString` needs a `baseUrl`** on iOS/WKWebView so the null-origin document may load the remote SDK `<script src>`. Set it to the SDK origin (e.g. `https://embed.cherry.fun`).
- **Platform setup** (AndroidManifest `<queries>` for MWA, iOS `Info.plist` URL schemes for the deeplink wallet) is documented in the [Flutter example README](https://github.com/cherrydotfun/chat-embed-sdk/tree/main/example/flutter).

## Wiring the wallet

Implement two functions in the native layer:

- `connectWallet()`: resolves to the base58 public key.
- `signMessageWithWallet(bytes)`: resolves to the **raw 64-byte Ed25519 signature over the challenge bytes as-is**. The Cherry server verifies `ed25519.verify(signature, challengeBytes, walletPublicKey)`, so do not re-hash, prefix, or re-encode.

Android uses Mobile Wallet Adapter (`wallet.signMessages`); note MWA may return the message with the signature appended, so slice the last 64 bytes when the result is longer. iOS uses a deeplink wallet's `signMessage` (decode its base58 signature to bytes) and resolves the pending promise when the wallet redirects back into your app.

## Gotchas

- **The sign handler is registered in the host page constructor**, not after `mount()`: the first challenge can fire before a late handler attaches. The shared host page already does this.
- **60-second sign timeout.** The bridge auto-fails a `signChallenge` after 60s. Native wallet round-trips (app switch, MWA intent) fit comfortably; just don't block on your own UI longer.
- **Allowed origins.** The host page's origin must be in the embed's **Allowed origins**, else the iframe bridge drops host commands. `localhost` is always allowed for local testing; a bundled page has origin `null`.
- **Keep `domStorageEnabled` on.** The Cherry session lives in the iframe's `sessionStorage`.
- **iOS deeplinks navigate away and back.** Handle the return via your universal link handler and resolve the pending connect/sign promise there.

## Next steps

- [Authentication](https://portal.cherry.fun/docs/embed/authentication.md) · [Theming](https://portal.cherry.fun/docs/embed/theming.md) · [SDK API reference](https://portal.cherry.fun/docs/embed/api-reference.md)
- Full protocol write-up: [`docs/react-native.md`](https://github.com/cherrydotfun/chat-embed-sdk/blob/main/docs/react-native.md) in the SDK repo