---
name: coinme-widget-android
description: "Integrate the Coinme Widget into an Android app with the CoinmeBridge Kotlin library: add the Gradle dependency and permissions, build a CoinmeConfig, create the fragment once, implement the four-method listener, and verify the session becomes ready. Use when asked to add, embed, integrate or scaffold the Coinme widget in an Android or Kotlin app."
metadata:
  surface: "ramp"
  package: "CoinmeBridge · Kotlin"
  version: "1.3.0"
---

# Coinme Widget on Android with CoinmeBridge

## When to use this skill

The human wants the Coinme Widget inside a native Android app. For a web page use the framekit skill; for a React Native app, no skill exists yet, so follow the Android and web guides and say so.

## Which integration this is

This skill is for the **Widget / Ramp integration**: the partner embeds the Coinme Widget, and its end users become Coinme customers inside it, where sign-in, KYC, payment and receipts happen. It needs none of the Onboarding, Vault or Risk SDKs. If the human's users are to stay the human's own customers, in the human's own screens, this is the wrong skill: read [Two ways to build on Coinme](https://platformdocs.coinme.com/agents/surfaces.md) and pick a Coinme-as-a-Service skill.

## What you will produce

An app that hosts the widget in a fragment created once and kept, configured with the ramp the human was issued, with a listener that reacts to the session becoming ready, events, the session ending and failures.

## Before you start: ask the human for these

The documentation does not contain them and you cannot derive them. Stop and ask, then continue. Never write a real value into a tracked file; keep each where the row says.

| Value | What it is | Where it goes |
| --- | --- | --- |
| `COINME_REGISTRY_TOKEN` | Read-only token for the private registry that serves CoinmeBridge for Android. | A gitignored `gradle.properties` or `local.properties` entry that the repository block reads; never in a committed build file. |
| `rampId` | The Ramp the widget loads, issued at onboarding with its environment. | `local.properties` surfaced through `BuildConfig`, as the guide describes. |
| `partnerKey` | Identifies your app to the Widget in the handshake, issued alongside the ramp id. Native integrations need it; a wrong or empty value means the session never becomes ready. | Same place as the ramp id. |

## Rules for this skill

- Follow the steps in order and keep the code as written; change only identifiers the human gives you and the places marked as yours.
- Do not invent configuration fields, event names or API methods. What exists is what this skill shows plus what the installed package declares in its type definitions; check those before adding anything.
- Samples show `'your-ramp-id'` and the stage URL as literals so each stays self-contained. In the project, read both from the runtime configuration the human's build uses (for Vite, `VITE_*` variables in a gitignored `.env.local` with a committed `.env.example`), and never commit a real ramp id.
- When a step needs a value you do not have, ask; do not substitute a placeholder that could ship.
- Read the linked pages when a step is unclear; they are the source this skill was generated from.

## Read first

One Gradle dependency, one import, and a config built from your onboarding values. Keep partnerKey and rampId out of source control; local.properties and BuildConfig is the usual route.

**Important.** Create the fragment once and keep it. Configuration changes recreate Activities by default; retain the fragment across them (or handle configChanges) so the WebView and its session survive rotation.

**Device fingerprint.** From 1.3.0, `CoinmeConfig` has an optional `deviceFingerprint`: the `X-Device-Fingerprint` the embedded flow sends. Leave it null and the bridge sends the shared value stored in the SharedPreferences file `coinme_sdk` under the key `coinme.deviceFingerprint`, creating and storing one if none exists; a value you set is sent and stored as the shared value. On Android only the bridge uses that value today: the Coinme Risk and Vault SDKs for Android send the fingerprint you pass them, so if your app uses them, set that same value here.

## Procedure

### 1. Add the dependency

CoinmeBridge from the Coinme Maven repository.

In `build.gradle.kts`:

```kotlin
// settings.gradle.kts: Coinme's Maven repository, with the registry
// token from your Coinme integration contact (read it from a gitignored
// gradle.properties or the environment; never commit it).
dependencyResolutionManagement {
  repositories {
    google()
    mavenCentral()
    maven {
      url = uri("https://maven.cloudsmith.io/coinme/coinme-sdk-frontend/")
      credentials {
        username = "token"
        password = providers.gradleProperty("COINME_REGISTRY_TOKEN").get()
      }
    }
  }
}

// app/build.gradle.kts
dependencies {
  implementation("com.coinme:coinme-bridge:1.3.0")
}

// then, anywhere you touch the SDK
import com.coinme.bridge.*
```

### 2. Build the config

Identity from onboarding, then whatever you want pre-filled.

In `CoinmeConfigBuilder.kt`:

```kotlin
val config = CoinmeConfig(
  rampId = BuildConfig.COINME_RAMP_ID,
  partnerKey = BuildConfig.COINME_PARTNER_KEY
).apply {
  flowId = "landing"
  theme = CoinmeTheme.LIGHT
  language = "en"

  destinationCurrency = "BTC"
  sourceAmount = 20.0
  sourceCurrency = "USD"
  sourceAmountLock = true

  externalSessionId = sessionId
  externalTransactionId = UUID.randomUUID().toString()

  // From 1.3.0, optional: leave it null to send the fingerprint the Coinme
  // SDKs share. Set it only to the value you give another Coinme SDK.
  // deviceFingerprint = fingerprint
}
```

### 3. Create the fragment

Once. Set the listener before it attaches.

In `OrchestratorSessionController.kt`:

```kotlin
val coinmeFragment = CoinmeFragment.newInstance(
  orchestratorUrl = "https://stage-widget.coinme.com",
  config = config
)
coinmeFragment.listener = this   // before onViewCreated

supportFragmentManager.beginTransaction()
  .add(R.id.orchestrator_container, coinmeFragment, TAG)
  .commit()
container.showLoading()
```

### 4. Implement the listener

Four methods. Hide the spinner on ready.

In `OrchestratorSessionController.kt`:

```kotlin
override fun onCoinmeSessionReady(f: CoinmeFragment) {
  if (f !== coinmeFragment) return
  container.hideLoading()
}
override fun onCoinmeSessionEnded(f: CoinmeFragment) {
  events?.sessionEnded()
}
override fun onCoinmeEvent(f: CoinmeFragment, event: CoinmeEvent) {
  when (event) {
    is CoinmeEvent.CloseRequested -> events?.closeRequested()
    is CoinmeEvent.TransactionComplete ->
      events?.transactionCompleted(event.payload["transactionId"] as? String)
    is CoinmeEvent.Unknown -> log(event.type, event.payload)
    else -> Unit
  }
}
override fun onCoinmeError(f: CoinmeFragment, error: CoinmeError) {
  when (error) {
    is CoinmeError.SessionTimeout,
    is CoinmeError.WebViewLoadFailed,
    is CoinmeError.HandshakeFailed -> tearDown()
    else -> Unit
  }
}
```

### 5. Run

Watch Logcat for the ready line.

What Logcat shows:

```text
I/CoinmeBridge: Creating Orchestrator session
I/CoinmeBridge:   URL: https://stage-widget.coinme.com
I/CoinmeBridge:   Session ID: 3F1C…
I/CoinmeBridge: Orchestrator session ready

// if instead you see, after a pause:
E/CoinmeBridge: SESSION_TIMEOUT
// check partnerKey first
```

## The listener

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.

| Callback | Meaning |
| --- | --- |
| `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. |

## Verify

Run the app on a device or simulator. The session is ready when the listener's ready callback fires and the ready line appears in the Logcat; the widget rendering is not the same event. Then trigger a flow and confirm events arrive through the listener. If the session never becomes ready, work down the table below.

| Symptom | Usually means | Check |
| --- | --- | --- |
| Loads, then SESSION_TIMEOUT | The session was not accepted. Usually an empty or wrong partnerKey. | The partnerKey value first. Then that the ramp is enabled for this environment. |
| WEBVIEW_LOAD_FAILED | The URL did not load at all. | Network, the exact orchestratorUrl, and that it is not a redirect. |
| HANDSHAKE_FAILED | Messages arrived from an origin the SDK does not trust. | The URL's scheme, host and port match the deployment exactly. |
| Ready, then an empty screen | flowId points at a step, not a home. | Use "landing" and let the ramp's initial_flow decide. |

### Reading the result

**Done when:** The widget renders in the fragment and the session-ready callback fires.

**Stop and ask the human when** the Ramp ID or environment is refused, or the session never becomes ready after the troubleshooting steps.

Judge every Coinme call by its body, not its HTTP status: a refused request usually comes back as HTTP 200 with the error in the body. [Reading results](https://platformdocs.coinme.com/agents/results.md) has the rule, what each common error code asks you to do, and what to send your Coinme integration contact when something fails.

## Patterns the demo app is built on

| Pattern | Why | API |
| --- | --- | --- |
| Build once, hide and show | Loading the Orchestrator and completing the handshake takes seconds. Create the SDK view at launch, keep it for the life of the screen, and merely hide it when the panel closes. | `FragmentTransaction.add · hide/show` |
| Restart, don't rebuild | Each purchase sends a fresh config and tells the running flow to re-initialise. The web app, sign-in and bridge session are reused. Queued automatically if called before ready. | `restartTransaction(config, payload)` |
| Config from app state | One side-effect-free builder turns your order model into a CoinmeConfig. One place to audit what is sent to Coinme, and a natural home for defaults. | `CoinmeConfigBuilder.makeConfig(…)` |
| Translate events once | The SDK hands you 18 events; three mean "the session is over" and two are barcode shapes. Fold them into a small set of app events so your UI never imports the SDK. | `interface OrchestratorSessionEvents` |
| Ignore stale sessions | Every callback first checks the sender is the live session. Clearing the delegate on teardown makes this redundant, but it costs nothing and guards a callback mid-teardown. | `if (f !== coinmeFragment) return` |
| Two IDs, two lifetimes | externalSessionId is fixed for the app session; externalTransactionId is fresh per attempt. Both are attached to Coinme's logs so you can line them up with yours. | `externalSessionId · externalTransactionId` |

## Reference
- [Android quick start](https://platformdocs.coinme.com/docs/android-quick-start.md)
- [Android integration guide](https://platformdocs.coinme.com/docs/android-integration-guide.md)
- [Build: Android overview](https://platformdocs.coinme.com/pages/build/native/android/overview.md)
- [Build: Android how it works](https://platformdocs.coinme.com/pages/build/native/android/how-it-works.md)
- [Build: Android how to use](https://platformdocs.coinme.com/pages/build/native/android/how-to-use.md)
- [Build: Android patterns](https://platformdocs.coinme.com/pages/build/native/android/patterns.md)
