> For the complete documentation index, see [llms.txt](https://docs.swapper.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.swapper.finance/widget-integration/direct-iframe.md).

# Direct Iframe & Mobile

You can embed the widget with a plain `<iframe>`, without installing `@swapper-finance/deposit-sdk`. This is the way to go when you can't run the SDK, such as in a native mobile app's WebView, a site builder or server-rendered HTML. You give up the SDK's helpers (config validation, typed events, modal, preload) and talk to the widget over `postMessage` yourself.

## Minimal embed

```html
<iframe
  src="https://deposit.swapper.finance/?integratorId=YOUR_ID&dstChainId=8453&dstTokenAddr=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&depositWalletAddress=0xYOUR_WALLET"
  title="Swapper Deposit Widget"
  style="border: none; width: 100%; max-width: 450px; height: 560px; border-radius: 28px"
  allow="camera; clipboard-write"
  sandbox="allow-forms allow-modals allow-popups allow-popups-to-escape-sandbox allow-same-origin allow-scripts allow-top-navigation-by-user-activation"
></iframe>
```

{% hint style="warning" %}
Copy `allow` and `sandbox` exactly. They are the values the SDK sets, and each one is used: popups open the card payment, the camera serves providers' identity checks, `clipboard-write` powers the copy buttons, and `allow-top-navigation-by-user-activation` lets wallet apps open on iOS. Leave one out and part of the flow breaks.
{% endhint %}

If a required parameter is missing, the widget shows an error screen naming it.

## URL parameters

| Parameter                                                            | Value                                                                                                                                                      |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `integratorId`, `dstChainId`, `dstTokenAddr`, `depositWalletAddress` | **Required.** See [Configuration → Required](https://docs.swapper.finance/widget-integration/configuration.md#required).                                   |
| `styles`                                                             | URL-encoded JSON, e.g. `{"themeMode":"dark"}`. See [Styling](https://docs.swapper.finance/widget-integration/styling.md).                                  |
| `supportedDepositOptions`                                            | URL-encoded JSON array, e.g. `["transferCrypto","depositWithCash"]`.                                                                                       |
| `customContractCalls`                                                | URL-encoded JSON array. See [Custom Contract Calls](https://docs.swapper.finance/widget-integration/custom-contract-calls.md).                             |
| `actionLabel`                                                        | `buy` or `deposit`. See [`actionLabel`](https://docs.swapper.finance/widget-integration/configuration.md#actionlabel).                                     |
| `language`                                                           | UI language, e.g. `pl` or `pt-BR`. See [`language`](https://docs.swapper.finance/widget-integration/configuration.md#language) for the supported list.     |
| `minDepositUsd`, `maxDepositUsd`                                     | Numbers, in USD. See [Configuration → Optional](https://docs.swapper.finance/widget-integration/configuration.md#optional).                                |
| `webviewMode`                                                        | `true` inside native mobile WebViews. See [below](#mobile-webviews).                                                                                       |
| `closable`                                                           | `true` shows a close button. Tapping it sends a [`close_request`](https://docs.swapper.finance/tracking-deposits/widget-events.md#close_request) event.    |
| `flexibleHeight`                                                     | `true` sizes the home page to its content. Resize the iframe on [`resize`](https://docs.swapper.finance/tracking-deposits/widget-events.md#resize) events. |

`webviewMode`, `closable` and `flexibleHeight` are switched on by any value, so leave them out to keep them off. They are read once, on load.

Build the URL with `URLSearchParams` so the JSON values are encoded for you:

```javascript
const params = new URLSearchParams({
  integratorId: "YOUR_ID",
  dstChainId: "8453",
  dstTokenAddr: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  depositWalletAddress: "0xYOUR_WALLET",
  styles: JSON.stringify({ themeMode: "dark" }),
  supportedDepositOptions: JSON.stringify(["transferCrypto", "depositWithCash"]),
});

iframe.src = `https://deposit.swapper.finance/?${params}`;
```

## Updating the config

Once the iframe has fired `load`, post a `SWAPPER_CONFIG` message to change the config without reloading. Fields you leave out keep their current values. Here `styles`, `supportedDepositOptions` and `customContractCalls` are plain objects and arrays, not JSON strings. This is also the better channel for long `customContractCalls`, which can push a URL past its length limit.

```javascript
const WIDGET_ORIGIN = "https://deposit.swapper.finance";

iframe.contentWindow.postMessage(
  { type: "SWAPPER_CONFIG", config: { depositWalletAddress: "0xNEW_WALLET" } },
  WIDGET_ORIGIN,
);
```

Send `{ language: "de" }` the same way when your app switches language.

`webviewMode`, `closable` and `flexibleHeight` can't be changed this way. Set them in the URL.

## Listening for events

The widget posts [events](https://docs.swapper.finance/tracking-deposits/widget-events.md) to its parent window. Check the origin before you trust one:

```javascript
window.addEventListener("message", (event) => {
  if (event.origin !== WIDGET_ORIGIN) return;
  if (event.data?.type !== "SWAPPER_EVENT") return;

  const { name, payload } = event.data;
  if (name === "transaction_success") console.log("Deposit:", payload.txHash);
  if (name === "close_request") iframe.remove();
  if (name === "resize") iframe.style.height = `${payload.height}px`;
});
```

## Mobile WebViews

Add `webviewMode=true` whenever the widget runs inside a native app: iOS `WKWebView`, Android `WebView`, React Native, Flutter, or a hybrid app such as Ionic/Capacitor.

The card payment runs on the payment provider's page. In a browser the widget opens that page in a popup. WebViews block or swallow popups, and 3D Secure hand-offs to the banking app, Apple Pay and Google Pay are unreliable inside them. With `webviewMode=true` the widget shows a **Continue to&#x20;*****provider*** link instead, and your app opens it in the system browser.

**Your app has to route that link out.** The link has no `target`, so tapping it navigates the widget's frame to the provider's site. Intercept navigation to any host other than `deposit.swapper.finance` and your own, and open it in the system browser:

| Platform             | Where                                                                                                                |
| -------------------- | -------------------------------------------------------------------------------------------------------------------- |
| iOS `WKWebView`      | `webView(_:decidePolicyFor:decisionHandler:)` → `UIApplication.shared.open(url)`, then `.cancel`                     |
| Android `WebView`    | `shouldOverrideUrlLoading` → `startActivity(Intent(Intent.ACTION_VIEW, uri))`, return `true`                         |
| React Native WebView | `onShouldStartLoadWithRequest` → `Linking.openURL(url)`, return `false`                                              |
| Ionic / Capacitor    | Opens off-app navigations in the system browser by default. Keep the provider hosts out of `server.allowNavigation`. |

The navigation happens inside the iframe, not your top-level page, so make sure your handler sees sub-frame navigations too.

Keep the widget open while the user pays. When they come back to the app, the widget picks up the payment status by itself and shows the result.

Using the SDK inside a WebView? It has no `webviewMode` option. Put the flag in `iframeUrl`, and the SDK keeps it while adding the rest of the config:

```typescript
new SwapperIframe({
  // ...config
  iframeUrl: "https://deposit.swapper.finance/?webviewMode=true",
});
```

For the user's side of card payments (debit vs credit, 3D Secure, declines), see [Card Payment Best Practices](https://docs.swapper.finance/deposit-methods/fiat-onramp/card-payment-best-practices.md).
