---
title: "Integration Guide"
url: "https://platformdocs.coinme.com/#/docs/android-integration-guide"
markdown: "https://platformdocs.coinme.com/docs/android-integration-guide.md"
summary: "Add Coinme's cryptocurrency purchase flow to your native Android app in under 10 minutes."
surface: "ramp"
platform: "android"
package: "CoinmeBridge · Kotlin"
version: "1.3.0"
source: "https://docs.coinme.com/docs/android-integration-guide"
updated: "2026-06-11"
---

# Integration Guide

> **Version note.** The code on this page pins `1.0.0`, while the current release is `1.3.0` (this page's `version`). The page may predate that release; ask your Coinme integration contact before relying on the older pin.

## Integrate CoinmeBridge in Your Android App

Add Coinme's cryptocurrency purchase flow to your native Android app in under 10 minutes.

### TL;DR

```kotlin
import com.coinme.bridge.*

val config = CoinmeConfig(
    rampId = "your-ramp-id",
    partnerKey = "your-partner-key",
)

val fragment = CoinmeFragment.newInstance(
    orchestratorUrl = "https://widget.coinme.com",
    config = config,
)
fragment.listener = this
supportFragmentManager.beginTransaction()
    .replace(R.id.container, fragment)
    .commit()
```

Read on for the full step-by-step walkthrough.

### Prerequisites

- **Android API 24+** (Android 7.0) minimum SDK
- **Kotlin 2.2+**
- Your **rampId** and **partnerKey** (provided by Coinme)
- Your **Orchestrator URL** (e.g. `https://widget.coinme.com`)

### Step 1: Add the Dependency

Add the Cloudsmith Maven repository to your project-level `settings.gradle.kts` (your Coinme integration contact will provide the entitlement token):

```kotlin
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://maven.cloudsmith.io/coinme/coinme-sdk-frontend/")
            credentials {
                username = "token"
                password = "<ENTITLEMENT_TOKEN>"
            }
        }
    }
}
```

Then add the dependency to your app module's `build.gradle.kts`:

```kotlin
dependencies {
    implementation("com.coinme:coinme-bridge:1.0.0")
}
```

### Step 2: Add Manifest Permissions

Add these to your `AndroidManifest.xml`:

```markup
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
    android:maxSdkVersion="32" />
```

> **Runtime permissions**
>
> The SDK requests camera, location, and photo library permissions automatically when the fragment is displayed. Partners only need to declare them in the manifest.

### Step 3: Configure the Hosting Activity

The Activity that hosts `CoinmeFragment` must declare `android:configChanges` so that the WebView is not destroyed when the keyboard opens or the device rotates:

```markup
<activity android:name=".BuyActivity" android:configChanges="orientation screenSize|keyboardHidden|keyboard|screenLayout|smallestScreenSize" />
```

> **Why?**
>
> Without this, Android destroys and recreates the Activity on configuration changes. This destroys the WebView and loses the Orchestrator session state, causing UI issues such as sheets opening unexpectedly or inputs losing focus.

### Step 4: Create a Configuration

Build a `CoinmeConfig` with your credentials:

```kotlin
import com.coinme.bridge.CoinmeConfig

val config = CoinmeConfig(
    rampId = "your-ramp-id",
    partnerKey = "your-partner-key",
    environment = "prod",                // "dev", "stage", or "prod"
    destinationCurrency = "BTC",         // optional: pre-select crypto
)
```

### Step 5: Implement the Listener

Implement `CoinmeListener` to receive events and errors:

```kotlin
import com.coinme.bridge.*

class BuyActivity : AppCompatActivity(), CoinmeListener {

    override fun onCoinmeEvent(fragment: CoinmeFragment, event: CoinmeEvent) {
        when (event) {
            is CoinmeEvent.TransactionComplete -> {
                Log.d("Coinme", "Transaction succeeded")
            }
            is CoinmeEvent.TransactionFailed -> {
                Log.d("Coinme", "Transaction failed")
            }
            is CoinmeEvent.UserCancelled -> {
                finish()
            }
            is CoinmeEvent.KycRequired -> {
                Log.d("Coinme", "KYC verification required")
            }
            is CoinmeEvent.SheetOpened -> { }
            is CoinmeEvent.SheetClosed -> { }
            is CoinmeEvent.Unknown -> {
                Log.d("Coinme", "Unhandled event: ${event.type}")
            }
        }
    }

    override fun onCoinmeError(fragment: CoinmeFragment, error: CoinmeError) {
        Log.e("Coinme", "Bridge error: ${error.message}")
        finish()
    }
}
```

### Step 6: Add the Fragment

Add a container to your layout:

```markup
<!-- activity_buy.xml -->
<FrameLayout
    android:id="@+id/coinme_container"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />
```

Then add the fragment:

```kotlin
val fragment = CoinmeFragment.newInstance(
    orchestratorUrl = "https://widget.coinme.com",
    config = config,
)
fragment.listener = this

supportFragmentManager.beginTransaction()
    .replace(R.id.coinme_container, fragment)
    .commit()
```

**That's it.** `CoinmeFragment` handles the WebView, bridge handshake, and session lifecycle automatically.

### Minimal Complete Example

```kotlin
import android.os.Bundle
import android.util.Log
import androidx.appcompat.app.AppCompatActivity
import com.coinme.bridge.*

class BuyActivity : AppCompatActivity(), CoinmeListener {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_buy)

        val config = CoinmeConfig(
            rampId = "your-ramp-id",
            partnerKey = "your-partner-key",
            destinationCurrency = "BTC",
        )

        val fragment = CoinmeFragment.newInstance(
            orchestratorUrl = "https://widget.coinme.com",
            config = config,
        )
        fragment.listener = this

        supportFragmentManager.beginTransaction()
            .replace(R.id.coinme_container, fragment)
            .commit()
    }

    override fun onCoinmeEvent(fragment: CoinmeFragment, event: CoinmeEvent) {
        when (event) {
            is CoinmeEvent.TransactionComplete -> finish()
            is CoinmeEvent.UserCancelled -> finish()
            else -> { }
        }
    }

    override fun onCoinmeError(fragment: CoinmeFragment, error: CoinmeError) {
        Log.e("Coinme", "Error: ${error.message}")
        finish()
    }
}
```

### Customization

#### Permission Flags

Camera and location default to `true` to provide the full Coinme experience. Screen capture protection is on by default (`allowsCapture = false`).

| Flag | Default | What it controls | Manifest permissions required |
| --- | --- | --- | --- |
| `allowsCamera` | `true` | Camera access for KYC document/selfie capture | `CAMERA` |
| `allowsLocation` | `true` | Browser geolocation API (e.g. store finders) | `ACCESS_FINE_LOCATION`, `ACCESS_COARSE_LOCATION` |
| `allowsCapture` | `false` | When `false`, `FLAG_SECURE` prevents screen recording and screenshots | None |

To opt out:

```kotlin
val config = CoinmeConfig(
    rampId = "your-ramp-id",
    partnerKey = "your-partner-key",
    allowsCamera = false,    // Disables camera access
    allowsLocation = false,  // Disables navigator.geolocation in the WebView
    allowsCapture = true,    // Disables screen capture protection
)
```

> **Trade-offs of disabling permissions**
>
> - `allowsCamera = false`: Identity-document workflows are disabled. Your widget integration will be unavailable in jurisdictions that require documentary KYC.
> - `allowsLocation = false`: Users will not see nearby retail locations automatically and must specify their location manually.

> You need to communicate your decision about camera access and geolocation to your your Coinme integration contact so that your ramp can be properly configured. Not doing so may result in poor UX for a subset of your customers.

#### Theme and Language

```kotlin
val config = CoinmeConfig(
    rampId = "your-ramp-id",
    partnerKey = "your-partner-key",
    theme = CoinmeTheme.DARK,    // LIGHT (default) or DARK
    language = "es",              // BCP 47 tag; defaults to "en"
)
```

#### Transaction Pre-fill

Lock fields to prevent user changes:

```kotlin
val config = CoinmeConfig(
    rampId = "your-ramp-id",
    partnerKey = "your-partner-key",
    walletAddress = "bc1q...",
    walletLock = true,
    sourceAmount = 100.0,
    sourceAmountLock = true,
    destinationCurrency = "BTC",
    destinationCurrencyLock = true,
)
```

#### Metadata and Tracking

```kotlin
val config = CoinmeConfig(
    rampId = "your-ramp-id",
    partnerKey = "your-partner-key",
    metadata = CoinmeMetadata(
        source = "android-app",
        campaign = "summer-promo",
    ),
    externalSessionId = "session-abc",
    externalTransactionId = "tx-456",
)
```

### Optional Listener Methods

These have default no-op implementations:

```kotlin
override fun onCoinmeSessionReady(fragment: CoinmeFragment) {
    // Bridge handshake complete, session is active
}

override fun onCoinmeSessionEnded(fragment: CoinmeFragment) {
    // Orchestrator signaled session end
    finish()
}
```

### Troubleshooting

| Problem | Cause | Fix |
| --- | --- | --- |
| Bridge never connects | Wrong Orchestrator URL or environment | Verify the URL matches your environment (`dev`, `stage`, `prod`) |
| Events not received | Listener not set, or set after fragment added | Set `listener` **before** adding the fragment to the activity |
| Camera not working | Missing manifest permission or runtime denial | Add `CAMERA` permission and handle runtime permission request |
| Blank white screen | Network or URL error | Check `onCoinmeError` for `WebViewLoadFailed` and inspect the underlying error |
| Screen capture blocked | `allowsCapture` defaults to `false` | Set `allowsCapture = true` in config if capture is needed |
| KYC document upload fails | Missing `CAMERA` or photo library permission | Add `CAMERA`, `READ_MEDIA_IMAGES` (API 33+), and `READ_EXTERNAL_STORAGE` (API 32 and below) to manifest |
| Photo picker shows empty | Missing `READ_MEDIA_IMAGES` / `READ_EXTERNAL_STORAGE` permission | Add photo library permissions to manifest (the SDK requests them at runtime) |
| Sheets misbehave / inputs lose focus | Activity missing `android:configChanges` | Add the full `android:configChanges` attribute (orientation, screenSize, keyboard, etc.) to the hosting Activity — see Step 3 |
| Links open blank page | `target="_blank"` links open externally | This is expected behavior — external links open in the device browser |

#### Debugging with Chrome DevTools

In debug builds the SDK enables WebView debugging automatically. To inspect:

1. Open Chrome on your computer
2. Navigate to `chrome://inspect`
3. Find your device and tap **Inspect** next to the WebView
4. Use the console to see `CoinmeBridge` log messages and Orchestrator JavaScript output

### Bridge Protocol Reference

The SDK handles all protocol details internally. This section is for reference only.

#### Message Flow

```
┌─────────────┐                           ┌──────────────┐
│   Native    │                           │ Orchestrator │
│     App     │                           │   (WebView)  │
└──────┬──────┘                           └──────┬───────┘
       │                                         │
       │  1. Load Orchestrator URL               │
       │────────────────────────────────────────>│
       │                                         │
       │  2. Handshake                           │
       │<────────────────────────────────────────│
       │     { type: "handshake" }               │
       │                                         │
       │  3. HandshakeAck                        │
       │────────────────────────────────────────>│
       │     { type: "handshakeAck" }            │
       │                                         │
       │  4. bridge-session-ready                │
       │<────────────────────────────────────────│
       │     { type: "event" }                   │
       │                                         │
       │  5. updateConfig                        │
       │────────────────────────────────────────>│
       │                                         │
       │  6. mount                               │
       │────────────────────────────────────────>│
       │                                         │
```

#### Key Differences from iOS

- **Message transport:** Android uses `WebViewCompat.addWebMessageListener` with platform-enforced origin validation (falls back to `@JavascriptInterface` on older WebView versions) instead of `WKScriptMessageHandler`
- **Capture protection:** Android uses `FLAG_SECURE` on the Activity window instead of the iOS `UITextField` secure container
- **Embedding:** Fragment-based instead of ViewController-based
- **File uploads:** Handled via `WebChromeClient.onShowFileChooser` + `ActivityResultLauncher` instead of `WKUIDelegate`
