---
title: "An afternoon to a first session. (iOS)"
url: "https://platformdocs.coinme.com/#/build/native/ios/how-to-use"
markdown: "https://platformdocs.coinme.com/pages/build/native/ios/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: "ios"
package: "CoinmeBridge for iOS"
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

Swift Package Manager, one import, and a config built from your onboarding values. The demo keeps partnerKey and rampId in a gitignored Secrets.swift with a committed example file.

### 1. Add the package

CoinmeBridge via Swift Package Manager.

In `Package.swift`:

```swift
// Once per machine: point SwiftPM at Coinme's package registry and
// log in with the registry token from your Coinme integration contact.
//   swift package-registry set https://swift.cloudsmith.io/coinme/coinme-sdk-frontend/ --global
//   swift package-registry login https://swift.cloudsmith.io/coinme/coinme-sdk-frontend/ --username token --password "$COINME_REGISTRY_TOKEN"
// In Xcode: File > Add Package Dependencies, search "coinme.coinme-native-bridge-ios".

dependencies: [
  .package(id: "coinme.coinme-native-bridge-ios", from: "1.3.0")
]

// then, anywhere you touch the SDK
import CoinmeBridge
```

### 2. Build the config

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

In `CoinmeConfigBuilder.swift`:

```swift
var config = CoinmeConfig(
  rampId: Constants.Bridge.rampId,
  partnerKey: Secrets.Bridge.partnerKey
)
config.flowId = "landing"
config.theme = .light
config.language = "en"

config.destinationCurrency = "BTC"
config.sourceAmount = 20
config.sourceCurrency = "USD"
config.sourceAmountLock = true

config.externalSessionId = sessionId
config.externalTransactionId = UUID().uuidString

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

### 3. Create the view controller

Once. Set the delegate before the view loads.

In `OrchestratorSessionController.swift`:

```swift
let coinmeVC = CoinmeViewController(
  orchestratorURL: URL(string: "https://stage-widget.coinme.com")!,
  config: config
)
coinmeVC.delegate = self   // before viewDidLoad

// simplest: take the screen
present(coinmeVC, animated: true)

// or keep your own chrome: embed as a child
container.embed(coinmeVC, in: self)
container.showLoading()
```

### 4. Implement the delegate

Four methods. Hide the spinner on ready.

In `OrchestratorSessionController.swift`:

```swift
extension SessionController: CoinmeDelegate {
  func coinmeSessionReady(_ vc: CoinmeViewController) {
    guard vc === coinmeViewController else { return }
    container.hideLoading()
  }
  func coinmeSessionEnded(_ vc: CoinmeViewController) {
    events?.sessionEnded()
  }
  func coinme(_ vc: CoinmeViewController,
              didReceiveEvent event: CoinmeEvent) {
    switch event {
    case .closeRequested: events?.closeRequested()
    case let .transactionComplete(p):
      events?.transactionCompleted(p["transactionId"] as? String)
    case let .unknown(type, payload): log(type, payload)
    default: break
    }
  }
  func coinme(_ vc: CoinmeViewController,
              didFailWithError error: CoinmeError) {
    switch error {
    case .sessionTimeout, .webViewLoadFailed, .handshakeFailed:
      tearDown()
    default: break
    }
  }
}
```

### 5. Run

Watch the console for the ready line.

What Console shows:

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

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

> **Important:** Create the view controller once and keep it. SwiftUI's UIViewControllerRepresentable can recreate it on identity changes, which drops the session; the demo hosts it from a thin UIKit shell with child-view-controller containment for exactly this reason.

> **Device fingerprint:** From 1.3.0, `CoinmeConfig` has an optional `deviceFingerprint`: the `X-Device-Fingerprint` the embedded flow sends. Leave it `nil` and the bridge sends the shared value stored in `UserDefaults.standard` 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 iOS only the bridge uses that value today: the Coinme Risk and Vault SDKs for iOS send the fingerprint you pass them, so if your app uses them, set that same value here. From 1.3.0 the package also ships its own privacy manifest, declaring a Device ID (not linked to the user, not used for tracking, for app functionality) and UserDefaults access with reason CA92.1, which Xcode includes in your app's privacy report.

## 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 summarises the Coinme demo app for iOS and the CoinmeBridge 1.3.0 SDK. The demo places the widget inside its own native surface; a plain present() is simpler and equally supported.

- [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/ios-quick-start)
