---
title: "One session, many purchases. (Android)"
url: "https://platformdocs.coinme.com/#/build/native/android/how-it-works"
markdown: "https://platformdocs.coinme.com/pages/build/native/android/how-it-works.md"
summary: "Create the SDK view once, keep it alive, and push each new purchase into it. This page walks through what your app does, what the SDK does, and what comes back."
surface: "ramp"
platform: "android"
package: "CoinmeBridge for Android"
version: "1.3.0"
---

# One session, many purchases.

Create the SDK view once, keep it alive, and push each new purchase into it. This page walks through what your app does, what the SDK does, and what comes back.

## The pieces and who owns them

Four layers. You write the top two; the SDK and Coinme own the bottom two. The demo app keeps its UI state machine free of any SDK import by translating SDK events into a small set of app events once.

From the top layer down:

| Layer | What it does | Owner |
| --- | --- | --- |
| Your UI | Screens, state machine, purchase draft. Never imports the SDK. | You |
| Session controller | Builds CoinmeConfig, creates the SDK view once, implements the listener, folds events into app events. | You |
| `CoinmeFragment` | WebView, handshake, session-ready detection, mounting the flow, answering config requests. | SDK |
| Orchestrator | The web app that runs the flow. Merges every config it receives; re-reads transaction fields on initialise. | Coinme |

## A purchase, step by step

Pick a moment. The left side is what your app does; the right is what the SDK and Orchestrator do in response.

The page shows one moment at a time; the table lists every moment in the order of a purchase.

| Moment | Your app | Call | SDK and Orchestrator | Bridge messages |
| --- | --- | --- | --- | --- |
| Launch | Build a baseline config (identity, theme, language, no payment method) and create the SDK view off-screen so the Orchestrator is loaded before the first tap. | `CoinmeFragment.newInstance(url, config)` | The WebView loads the Orchestrator. It says hello; the SDK acknowledges with rampId and partnerKey; the config crosses; the landing flow mounts. | `handshake → handshakeAck → host.config → bridge.session.ready` |
| Ready | Hide the spinner. Nothing else: the SDK has already sent theme and language and mounted the flow. | `onCoinmeSessionReady(fragment)` | The Orchestrator is showing its landing state. Sign-in, if needed, happens inside the widget. | `bridge.session.ready` |
| Buy | Copy the user's choices into a new config (asset, amount, locks, payment method) and restart the transaction. Show the panel. | `restartTransaction(config, payload)` | The new config is merged and the flow re-initialises against it. The loaded web app, sign-in and bridge session are all reused. If the session is not ready yet the call is queued. | `host.config → host.transaction.restart` |
| Theme change | Take the config the session started with, change theme, pass it back. Safe before ready. | `updateConfig(config)` | Only theme and language are applied to a running session; transaction fields wait for the next restart. If the user changed theme inside the widget instead, you get bridge.settings.theme and should apply it natively without echoing. | `host.config ⇄ bridge.settings.theme` |
| Outcome | Close the panel on closeRequested or sessionEnded. On transactionRejected the user is already signed out; close and explain, or send a new config, as suits your app. Keep the SDK view alive. | `onCoinmeEvent(fragment, event)` | Card purchases end with transactionComplete. Cash purchases end with barcodeGenerated and the session may end; the barcode lives on. | `bridge.transaction.complete · bridge.barcode.generated · bridge.close` |
| Failure | On sessionTimeout, webViewLoadFailed or handshakeFailed, release the SDK view and tell the UI. The next purchase creates a fresh one. Permission and parsing errors: log and continue. | `onCoinmeError(fragment, error)` | Deallocating the SDK view removes the bridge message handler and lets the WebView go. There is no separate close-session call. | `SESSION_TIMEOUT · WEBVIEW_LOAD_FAILED · HANDSHAKE_FAILED` |

## What comes back

CoinmeListener has four methods. Two are session lifecycle, one carries all 18 typed events plus Unknown, and one carries session errors. Check the sender is your live session in each.

- **`onCoinmeSessionReady(fragment)`**: Handshake complete, flow mounted. Hide your spinner.
- **`onCoinmeSessionEnded(fragment)`**: Sign-out, timeout or a completed cash transaction. The fragment stays alive; close the panel.
- **`onCoinmeEvent(fragment, event)`**: 18 typed CoinmeEvent subclasses plus Unknown(type, payload). Use a sealed when so a new case fails to compile instead of being ignored.
- **`onCoinmeError(fragment, error)`**: SessionTimeout, WebViewLoadFailed and HandshakeFailed are terminal: remove the fragment. Permission and parsing errors are not.

> **Note:** Barcode events can arrive either as the typed case or as `unknown("bridge.barcode.generated")` depending on your ramp's configuration. Theme and language changes have no typed case. Fold both shapes into one app event, as the demo does.

This section shows the iOS demo app's patterns in Kotlin against the CoinmeBridge Android SDK.

- [The Bridge explainer](https://platformdocs.coinme.com/pages/explainers/bridges.md)
- [CoinmeConfig field reference](https://platformdocs.coinme.com/pages/build/index.md#config)
- [Quick start on docs.coinme.com](https://docs.coinme.com/docs/android-quick-start)
