---
title: "Two ways to embed the widget."
url: "https://platformdocs.coinme.com/#/explainers/bridges"
markdown: "https://platformdocs.coinme.com/pages/explainers/bridges.md"
summary: "The right choice depends on what you want your integration to do. The bridge keeps a live channel open between your app and the widget. The proxy opens no channel: it loads a fixed configuration as a URL and reports back through backend webhooks. This page lays out what that difference means, so you can pick the one that fits your goals."
---

# Two ways to embed the widget.

The right choice depends on what you want your integration to do. The **bridge** keeps a live channel open between your app and the widget. The **proxy** opens no channel: it loads a fixed configuration as a URL and reports back through backend webhooks. This page lays out what that difference means, so you can pick the one that fits your goals.

## The two integration styles, one session each

The page opens with a mode switch between the two styles and a session tape for each, drawn between your app and the widget. The switch also changes the page: with the proxy selected, the first section shows the proxy's costs and benefits instead of the bridge's capabilities, and the bridge-only sections are hidden. Both versions are given here.

### With the bridge

Link from **Your app** to **Widget**: live channel.

| Step | Kind | What happens |
| --- | --- | --- |
| 1 | user | Buy BTC |
| 2 | event | purchased → your app |
| 3 | user | Buy ETH |
| 4 | event | done → your app |

↻ one session, channel stays open

**Bridge.** A live channel stays open, so the user never leaves context. They can transact, return, and transact again, and your app sees each step as it happens.

### With the proxy

Link from **Your app** to **Widget**: no channel.

| Step | Kind | What happens |
| --- | --- | --- |
| 1 | load | Load configured URL |
| 2 | user | Buy BTC |
| 3 | end | Session ends |

no channel back; results via backend webhooks

**Proxy.** The frontend loads a configured URL with no channel back. Your app hears what it can through backend webhooks, and cannot tell on its own when the user is done.

<a id="gives"></a>

## What the bridge allows

### With the bridge

The bridge allows direct, real-time communication between your app and the Coinme widget. This real-time bi-directional communication allows tight integration between your application and the widget, dissolving the user experience boundary so the two feel like one app. The removal of this boundary enables integrations that are not possible with the bridge proxy.

- **The user never loses context**: Your app and the widget share one live session, so the user moves between them with no stops, reloads, or re-entry. The integration feels like a single app, not a handoff to a separate page.
- **Repeat transactions, light on the backend**: In the same open session the user can buy, return, and buy again. The bridge carries this on the client, so multi-transaction flows do not require new backend infrastructure.
- **Live events, both ways**: Each action reaches your app the moment it happens, including when the user has finished and wants to return to your app.

### With the proxy

With the proxy selected, this section is titled **Bridge Proxy: costs and benefits**.

The proxy is the same widget delivered a different way. Your backend creates a configured instance over REST and returns a URL your frontend loads. Choosing it is a trade, so here are both sides.

| Side | Title | Detail |
| --- | --- | --- |
| Gain | What you gain | A familiar integration model. The proxy is standard REST and an iframe or webview: your backend authenticates, configures the instance, and returns a URL. There is no client-side protocol to learn, and configuration stays on the backend, where a backend-oriented team already works. |
| Give up | What you give up | The tooling. The iOS and Android packages, the ready-made WebView, the handshake, the transport, and the regulatory and permissions coverage all apply to bridge integrations. With the proxy you load the URL yourself and own that surface. The live channel, and the capabilities that come with it: context preservation, repeat transactions without backend work, and live events. Your app hears back only through backend webhooks, and cannot tell on its own when the user is done. |

Where it fits: the proxy suits backend-heavy teams that prefer to keep integration on the backend and have limited frontend capacity. When there is frontend capacity to use the packages, the bridge is usually the lower-effort path rather than the higher one, and it keeps the capabilities above.

<a id="hybrid"></a>

## Hybrid app architecture out of the box

Shown only with the bridge selected; the proxy view hides this section.

A hybrid app is a native shell hosting web content with a channel between them. That channel is the bridge. It is built on the standard pieces every platform already provides: a script message handler on iOS, a message listener on Android, `onMessage` in a React Native WebView, and `window.postMessage` to an iframe on the web.

The Coinme bridge is that same channel with a defined message set: a handshake to open the session, then messages to configure the widget, mount a flow, and listen for events. It is a well-understood pattern, and you do not have to assemble it yourself.

| Platform | Native channel | With the Coinme bridge |
| --- | --- | --- |
| iOS | WKScriptMessageHandler + WKWebView | The same bridge channel, into a **WKWebView**. |
| Android | WebView message listener | The same bridge channel, into an **Android WebView**. |
| React Native | WebView onMessage / postMessage | The same bridge channel, into a **React Native WebView**. |
| Web | window.postMessage to an iframe | The same bridge channel, into an **iframe**, via framekit. |

<a id="built"></a>

## We provide the tooling

Shown only with the bridge selected; the proxy view hides this section.

### You do not implement the channel by hand.

The iOS, Android, React Native* and JS packages give you a ready-made bridge. Drop the package into your application and you get a ready-made view and bridge session that is ready to use.

- **WebView**: Created and configured for you, with the requirements already met.
- **Handshake**: Opened and acknowledged automatically. You wait for a ready session, nothing more.
- **Transport**: The right channel for the platform is detected and wired up.
- **Security**: The embedding requirements are satisfied by the package on setup.
- **Regulatory & permissions**: The packages carry the regulatory and permissions requirements the integration must meet, so your build satisfies them out of the box. You do not have to implement or own that surface.

You plug it in and send transactions.

\* These packages are in active development. Availability and interfaces may change before general release.

<a id="proxy"></a>

## When each fits

Both approaches put the widget in an iframe or WebView. The difference is whether a channel stays open, and that follows from what you need your app to know and do.

The **proxy** opens no channel. Your backend sets the configuration once, hands the frontend a URL to load, and receives what it can through backend webhooks. The picture is narrower: your frontend cannot tell when the user has finished and wants to return, so you trap navigation to detect it. Choose the proxy when the embed is static and backend-only, and server-side webhooks are enough.

The **bridge** keeps the channel open. Choose it when the experience depends on the user moving between your app and the widget without friction, or on your app knowing in real time what the user is doing.

<a id="compare"></a>

## Side by side

| Axis | Bridge | Proxy |
| --- | --- | --- |
| Session | Stays open, many transactions | One load, one transaction |
| Getting started | Drop in one of our packages | Point an iframe or webview at a URL |
| Between transactions | Nothing, the session continues | Mint a new URL |
| Live config updates | **Yes**, mid-session | No, fixed at mint time |
| How your app hears back | Live events on the client & backend webhooks | Backend webhooks only |
| Knowing the user is done | Delivered as an event | Not available; trap navigation |
| Other events | Delivered in real time | Not available |
| Where config is transmitted | Client, sent live | Server, baked into the URL |
| Best when | The experience should feel seamless, or repeat transactions matter | The embed is static and server-side webhooks are enough |

<a id="events"></a>

## Events and actions over the bridge

Shown only with the bridge selected; the proxy view hides this section.

The widget sends your app events as the customer moves through it, such as a completed transaction, a cash order ready to resume, or a request to close. Every Widget SDK delivers the same typed events, and [the event catalogue](https://platformdocs.coinme.com/pages/build/web/how-to-use.md) is the contract. Coinme configures which events reach your app and under what names; ask your Coinme integration contact for the ones you need.

Your app can send the widget the documented host actions, such as a new configuration to start the next transaction (see [the bridge on Build](https://platformdocs.coinme.com/pages/build/index.md#bridge)). The widget decides what each one does and ignores anything else.

Orchestrator is the embedded transaction engine. The bridge is the live channel between your app and that engine. The proxy delivers a fixed configuration as a URL.
