---
title: "One iframe, one SDK, the whole ramp."
url: "https://platformdocs.coinme.com/#/build/web/how-it-works"
markdown: "https://platformdocs.coinme.com/pages/build/web/how-it-works.md"
summary: "The widget in this demo is a full Coinme Orchestrator deployment running in an iframe. Framekit (@coinme/coinme-bridge-framekit) is the TypeScript SDK that puts it there and keeps a secure, typed message channel, the bridge, open between the host app and the widget."
surface: "ramp"
platform: "web"
package: "@coinme/coinme-bridge-framekit"
version: "1.1.2"
peerDependencies: {"react":">=18.0.0","react-dom":">=18.0.0"}
---

# One iframe, one SDK, the whole ramp.

The widget in this demo is a full Coinme Orchestrator deployment running in an iframe. **Framekit** (@coinme/coinme-bridge-framekit) is the TypeScript SDK that puts it there and keeps a secure, typed message channel, the **bridge**, open between the host app and the widget.

The web isn't the only host. Coinme ships native bridge SDKs for **iOS** (CoinmeViewController, Swift) and **Android** (CoinmeFragment, Kotlin) that embed the same Orchestrator in a WebView using the same bridge mechanics: identical protocol, handshake, rampConfig payload, and events. Integrate once conceptually, and the ramp behaves the same in a web page or a native app.

## Three layers, three responsibilities

- **Owns the page** (Your app): Layout, branding, where the widget sits, and the CoinmeConfig it is given. Nothing crypto-related runs here.
- **Owns the plumbing** (Framekit): Creates the iframe, opens a locked-down postMessage channel, runs the handshake, ships config in, surfaces events out. No HTTP, no UI. Transport only.
- **Owns the experience** (Orchestrator): The entire ramp UI (auth, KYC, payments, receipts) plus its own API calls. A separate hosted deployment per environment.

## The bridge lifecycle

1. **Iframe construction**: Framekit creates an <iframe> pointed at the Orchestrator URL you pass.
2. **Handshake**: The Orchestrator announces itself with a handshake message; framekit replies handshakeAck. Both sides now agree on protocol version and platform.
3. **Mount**: Framekit sends a mount message carrying the full rampConfig built from your CoinmeConfig: identity, prefill, locks, theme, language. Field-for-field parity with the iOS and Android bridges.
4. **Session ready**: The Orchestrator dispatches its session-ready lifecycle event. The user now drives the experience inside the iframe.
5. **Ongoing traffic**: Events flow out (transactionComplete, kycRequired, sheetOpened, ...); config patches flow in as updateConfig envelopes, live, with no iframe remount.

## What the bridge enables

- **Live config, no remount**: Change theme or language at any time, and prefill amounts, currencies and wallet addresses (or lock them) for the next transaction. Framekit diffs the config and ships only updateConfig envelopes; avoid changing transaction fields while the user is in the middle of one.
- **Theme & language control**: Flip the widget between light and dark or switch its language from the host page. The Orchestrator applies both from the bridge's rampConfig.
- **Typed events out**: Transaction outcomes, KYC prompts, and sheet open/close arrive as a typed CoinmeEvent union, so you subscribe to exactly what you need.
- **RPC across the frame**: The Orchestrator can request the current config from the host (getConfig) with correlated responses, the same pattern the native bridges use.
- **Origin-pinned security**: Framekit talks only to the Widget origin you load and ignores messages from anywhere else. Your site must also be on the embed allowlist before the Widget will run inside it.
- **One protocol, every platform**: The same bridge contract powers the iOS (CoinmeViewController) and Android (CoinmeFragment) native shells, so a ramp behaves identically in an app or an iframe.

## Transacting across the bridge, in code

This site ships a pre-built hook, **useCoinmeBridge**, that packages the send and receive sides of the bridge into typed methods:

```tsx
const bridge = useCoinmeBridge();

// receive: typed events out of the widget
useEffect(
  () => bridge.on('transactionComplete', (e) => celebrate(e)),
  [bridge.on]
);

// send: live config into the widget, no remount
bridge.setTheme('dark');
// set up the next transaction; not while the user is in the middle of one
bridge.prefillTransaction({ sourceAmount: 25, destinationCurrency: 'BTC' });

<CoinmeFrame
  ref={bridge.frameRef}
  orchestratorUrl={ORCHESTRATOR_URL}
  config={{ rampId }}
  {...bridge.frameCallbacks}
/>;
```
