---
title: "An afternoon to a first session. (Android)"
url: "https://platformdocs.coinme.com/#/build/native/android/how-to-use"
markdown: "https://platformdocs.coinme.com/pages/build/native/android/how-to-use.md"
summary: "Add the package, build a config, create the view, set the callback, and watch for session ready. Five steps; each one is a few lines."
surface: "ramp"
platform: "android"
package: "CoinmeBridge for Android"
version: "1.3.0"
---

# An afternoon to a first session.

Add the package, build a config, create the view, set the callback, and watch for session ready. Five steps; each one is a few lines.

## From empty project to session ready

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.

### 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:

```
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
```

> **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.

## If the session never becomes ready

The widget loading visually and the session becoming ready are different events. Work down the list.

| 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. |

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)
