---
title: "Coinme Risk SDK for React Native"
url: "https://platformdocs.coinme.com/#/docs/coinme-risk-sdk-for-react-native"
markdown: "https://platformdocs.coinme.com/docs/coinme-risk-sdk-for-react-native.md"
summary: "Real-time fraud detection and risk assessment for React Native apps; a thin native-module bridge over Coinme's production iOS and Android risk SDKs, exposed as a typed JS/TS API."
surface: "caas"
platform: "reactNative"
package: "@coinme-security/risk-sdk-react-native"
version: "1.1.0"
peerDependencies: {"react":">=18","react-native":">=0.72"}
source: "https://docs.coinme.com/docs/coinme-risk-sdk-for-react-native"
updated: "2026-10-28"
---

# Coinme Risk SDK for React Native

> Real-time fraud detection and risk assessment for React Native apps; a thin native-module bridge over Coinme's production iOS and Android risk SDKs, exposed as a typed JS/TS API.

**Package:** `@coinme-security/risk-sdk-react-native` **Version:** `1.0.1` **License:** Proprietary — Coinme, Inc.

## What this SDK is

`@coinme-security/risk-sdk-react-native` is the React Native binding for the Coinme Risk Engine. It wraps Coinme's native iOS (`risk-sdk-ios`) and Android (`risk-sdk-android`) SDKs via a thin React Native native-module bridge and exposes a single typed JS/TS API that matches its sibling SDKs.

One npm package. One native module name. One consumer-facing API. If you're already using `@coinme-security/risk-sdk-js` on web or the native iOS / Android SDKs, this is the RN port of the same conceptual model:

> **setup → get session tag → update → submit data before each transaction-initiating server call**
>
>

### What it collects

The native engine collects a layered set of signals from the user's session:

- **Behavioral biometrics** — typing cadence, interaction timing, touch patterns
- **Sensor data** — motion, orientation, device pressure
- **Device context** — clipboard activity, focus patterns, screen engagement
- **Device fingerprinting** — device identifiers, network state, SIM info (Android), location (with user consent)
- **Field interactions** — text changes and focus events on tracked inputs

Those signals are flushed to Coinme's Risk Engine when you call `submitCoinmeRiskData()`. Coinme's transaction services consume the signals internally when evaluating the transactions your app initiates.

## Why does Risk SDK exist?

Coinme uses real-time behavioral risk signals as part of how we evaluate whether to process or reject a transaction. The Risk SDK is the mechanism that collects those signals on-device and correlates them — via a device fingerprint every Coinme SDK in your app shares — to the server calls they belong to.

> **Integration is required.**
>
> Partners cannot use Coinme's transactional services without integrating the Risk SDK on every surface that initiates a transaction. Transactions unsupported by risk metrics will be rejected outright.

**Your responsibilities as an integrator:**

- Send the device fingerprint the Coinme SDKs share on your own backend calls (see section 9)
- Call `submitCoinmeRiskData()` before every transaction-initiating server request (see section 12)
- Handle privacy policy disclosures and store-listing compliance (see section 14)

## How does the Risk SDK work?

```
┌──────────────────────────────────────────────────────────────┐
│  Your React Native app                                       │
│                                                              │
│  ┌────────────────────────────────────────────────────┐      │
│  │  @coinme-security/risk-sdk-react-native (JS/TS)    │      │
│  │  setupCoinmeRiskEngine / updateCoinmeRiskEngine    │      │
│  │  getPartnerSessionTag                              │      │
│  │  submitCoinmeRiskData / CoinmeTrackedTextInput     │      │
│  └───────────────────────┬────────────────────────────┘      │
│                          │ RN bridge                         │
│  ┌───────────────────────┴────────────────────────────┐      │
│  │  Native module: CoinmeRiskEngine                   │      │
│  │  ├── iOS:     risk-sdk-ios (xcframework)           │      │
│  │  └── Android: risk-sdk-android (aar)               │      │
│  └────────────────────┬───────────────────────────────┘      │
└───────────────────────┼──────────────────────────────────────┘
                        │
                        ▼
             Coinme Risk Engine  ◀── session tag + signals
                        │
                        ▼
          Consumed by Coinme's transaction
          services during evaluation of
          customer transaction requests
```

The JS layer forwards typed calls across the bridge to the native engine, which does the actual signal collection. The public API mirrors `CoinmeRiskEngine` on iOS and Android, so integration code looks the same across all three platforms.

**The signals are consumed by Coinme's internal transaction services, not returned to partners.** The SDK submits behavioral, device, and interaction data to the Risk Engine, which Coinme uses as part of its decision to process or reject a transaction. Risk scores and the underlying signals are not exposed to partner backends.

## Compatibility

| Requirement | Supported |
| --- | --- |
| Node | 20.9+ |
| React | 18+ |
| React Native | 0.72 – 0.81 (see note below) |
| iOS | 16.0+ (required by the underlying `CoinmeRiskSDK` xcframework) |
| Android | `minSdkVersion` 24+ (Android 7.0 Nougat) |
| Expo | ✅ SDK 51+ (managed workflow with `expo prebuild`) — see [Expo support](#expo-support) |

> **React Native 0.82+ is not yet supported.**
>
> The bridge targets RN's legacy (bridge) architecture; TurboModule support is planned but has not landed. RN 0.82 defaults the New Architecture ON and removes the off-switch. **Pin to 0.81 or older until TurboModule support ships.**

## Obtaining access

The Risk SDK is distributed privately. You need a **Coinme Cloudsmith entitlement token** — a single credential that authenticates three things:

1. The private npm registry at `npm.coinme.com` (for the JS package)
2. The CocoaPods repository (for the iOS native artifact)
3. The Maven repository (for the Android native artifact)

One token covers all three. If you don't already have one, ask your Coinme integration contact — this is not a self-serve credential.

Throughout this guide, the token is referred to as `CLOUDSMITH_TEAM_TOKEN`. Export it as an environment variable before any build step:

```
export CLOUDSMITH_TEAM_TOKEN=<your-token>
```

For persistence across shells, also add it to:

- `~/.gradle/gradle.properties` (covers Gradle)
- Your shell rc file (`/.zshrc`, `/.bashrc`, etc. — covers CocoaPods)

**Do not commit the token to version control.** Use CI secrets for automated builds.

## Installation

### 1. Install the npm package

The package is hosted on Coinme's private npm registry. Configure the scope before installing.

**For npm / Yarn Classic**, add to `.npmrc` at your repo root:

```bash
@coinme-security:registry=https://npm.coinme.com/coinme-security-wrapper/
//npm.coinme.com/coinme-security-wrapper/:_authToken=${CLOUDSMITH_TEAM_TOKEN}
always-auth=true
```

**For Yarn Berry (v2+)**, add to `.yarnrc.yml`:

```bash
nodeLinker: node-modules

npmScopes:
  coinme-security:
    npmRegistryServer: 'https://npm.coinme.com/coinme-security-wrapper/'
    npmAuthToken: '${CLOUDSMITH_TEAM_TOKEN}'
```

Then install:

```bash
export CLOUDSMITH_TEAM_TOKEN=<your-token>
yarn add @coinme-security/risk-sdk-react-native
# or
npm install @coinme-security/risk-sdk-react-native
```

Autolinking will discover this package automatically — you do not need to register the native module by hand on either platform.

### 2. iOS setup

Three things to do in `ios/Podfile`:

1. **Add the Cloudsmith and CocoaPods CDN sources at the very top of the file.** Use double quotes so Ruby interpolates the env var:

```bash
source "https://dl.cloudsmith.io/#{ENV['CLOUDSMITH_TEAM_TOKEN']}/coinme/coinme-sdk-mobile/cocoapods/index.git"
source "https://cdn.cocoapods.org/"
```

1. **Set the iOS deployment target.** `CoinmeRiskSDK` requires iOS 16+ and RN's default is lower:

```bash
platform :ios, '16.0'
```

1. **Disable the New Architecture** by passing `new_arch_enabled: false` to `use_react_native!` (or set `RCT_NEW_ARCH_ENABLED=0` at install time).

Inside the main `target '<AppName>' do` block, confirm `use_frameworks! :linkage => :static` is present (most modern RN templates include this).

Then install:

```bash
export CLOUDSMITH_TEAM_TOKEN=<your-token>
cd ios && pod install
```

Autolinking picks up the package's podspec automatically. You do **not** add a `pod '...'` line yourself.

### 3. Android setup

**Step 1 — Add Coinme's Cloudsmith Maven repo.**

In `android/settings.gradle` (or `.kts`), add a `dependencyResolutionManagement` block. Read the token from the environment rather than committing it:

```kotlin
def cloudsmithToken = System.getenv('CLOUDSMITH_TEAM_TOKEN') ?: ''

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    repositories {
        google()
        mavenCentral()
        maven {
            name = "CoinmeSDK"
            url = uri("https://dl.cloudsmith.io/${cloudsmithToken}/coinme/coinme-sdk-mobile/maven/")
        }
    }
}
```

> If your template uses `allprojects { repositories { … } }` in the root `build.gradle` instead of `dependencyResolutionManagement` (common on RN 0.72–0.75), add the same Maven block there.

**Step 2 — Force Kotlin 2.3.0.**

`risk-sdk-android` is compiled with Kotlin 2.3.0. React Native's Gradle plugin pins an older version, which causes this build failure:

> Module was compiled with an incompatible version of Kotlin. The binary version of its metadata is 2.3.0, expected version is 2.1.x.

In `android/build.gradle`, set `kotlinVersion` to `2.3.0`, pin the plugin explicitly, and add resolution strategies in **both** `buildscript` and `allprojects`:

```kotlin
buildscript {
    ext {
        buildToolsVersion = "35.0.0"
        minSdkVersion = 24
        compileSdkVersion = 35
        targetSdkVersion = 35
        ndkVersion = "27.1.12297006"
        kotlinVersion = "2.3.0"   // ← must be 2.3.0
    }
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath("com.android.tools.build:gradle")
        classpath("com.facebook.react:react-native-gradle-plugin")
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${kotlinVersion}")
    }
    // Force Kotlin 2.3.0 for classpath dependencies
    configurations.classpath {
        resolutionStrategy.eachDependency { details ->
            if (details.requested.group == 'org.jetbrains.kotlin') {
                details.useVersion kotlinVersion
            }
        }
    }
}

// Force Kotlin stdlib 2.3.0 for all subprojects
allprojects {
    configurations.all {
        resolutionStrategy.eachDependency { details ->
            if (details.requested.group == 'org.jetbrains.kotlin' &&
                details.requested.name.startsWith('kotlin-stdlib')) {
                details.useVersion rootProject.ext.kotlinVersion
            }
        }
    }
}

apply plugin: "com.facebook.react.rootproject"
```

> `allprojects` must be at the **root level** of `build.gradle`, not nested inside `buildscript`.

**Step 3 — Disable the New Architecture.**

In `android/gradle.properties`:

```kotlin
newArchEnabled=false
```

**Step 4 — Build.**

```bash
export CLOUDSMITH_TEAM_TOKEN=<your-token>
cd android && ./gradlew clean
```

Autolinking links the module; you do **not** add an `implementation("com.coinme:...")` line yourself.

## Platform configuration

### 1. Android permissions

Add these to `AndroidManifest.xml`:

```markup
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.USE_BIOMETRIC" />
<uses-permission android:name="android.permission.USE_FINGERPRINT" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES" />
```

**Usage reference:**

| Permission | Usage |
| --- | --- |
| `INTERNET` | Network communication for fraud detection |
| `ACCESS_COARSE_LOCATION` / `ACCESS_FINE_LOCATION` | Location signals for fraud detection |
| `ACCESS_WIFI_STATE` | WiFi name and status |
| `ACCESS_NETWORK_STATE` | Network information and state |
| `READ_PHONE_STATE` | Phone/network info (MNC, MCC, IMEI, phone number, phone type, SIM number) |
| `USE_BIOMETRIC` / `USE_FINGERPRINT` | Biometric authentication settings (Face / Fingerprint) |
| `WRITE_EXTERNAL_STORAGE` | Write data to check re-installation behavior |
| `READ_EXTERNAL_STORAGE` | External storage status, total size, free size |
| `READ_GSERVICES` | Device GSF ID (Google Services Framework ID) |

> Location and phone-state permissions are **dangerous permissions** on Android 6.0+ and require runtime permission requests. Handle the flow in your app.

### 2. Android ProGuard / R8

If you use ProGuard or R8 for code obfuscation, add these rules to `proguard-rules.pro`:

```bash
# Keep Google Play Services classes
-keep class com.google.android.gms.** { *; }
-keep class com.google.android.gms.tasks.** { *; }
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient { *; }

# Keep Sardine SDK classes
-keep class ai.sardine.** { *; }
-keepclassmembers class ai.sardine.** { *; }
```

### 3. Google Play Console requirements

Before releasing your app with the Risk SDK:

**Privacy Policy** — update your Play Store privacy policy with the following disclosure:

> For fraud protection purposes only, (1) we collect your Battery Usage, Device Identifier, Device Storage, MAC Address, and SIM information; (2) we also collect enough information to determine if you are trying to fake your current location by using a VPN, VPN apps with location spoofing, or other related tools.

**Data Safety declaration** — in the Play Console, go to **App content → Data safety** and declare these collected data types:

- **Location** (Approximate and Precise)
- **Device or other IDs** (Device ID)
- **App info and performance** (Crash logs, Diagnostics)
- **Files and docs** (for storage-related fraud detection)

> Add any other data types your app collects beyond what the SDK requires. Your Coinme integration contact may provide a Data Safety CSV you can import directly.

### 4. iOS Info.plist keys

Location permissions are required. Add to `Info.plist`:

```swift
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>We use your location to verify transactions and prevent fraud.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>We use your location to verify transactions and prevent fraud.</string>
```

If you also want Face ID signal detection:

```swift
<key>NSFaceIDUsageDescription</key>
<string>Face ID is used to verify your identity.</string>
```

**Optional iOS capabilities** (added via Xcode → Signing & Capabilities):

- **Access WiFi Information** — required for WiFi BSSID/SSID as an additional location signal. Requires location services to be enabled first.
- **iCloud + CloudKit** — enables iCloud record ID (consistent across devices on the same Apple account). If you add this capability, you must set `setCloudEntitlements: true` in the setup options. **Do not enable** `setCloudEntitlements` **without adding the CloudKit capability — the underlying native SDK will crash.**

### 5. App Store Connect requirements

Before releasing, update **App Store Connect → App Privacy**:

1. **Data Collection** — select "Yes, we collect data from this app"
2. **Location** — select Coarse and/or Precise Location. Purpose: App Functionality. Reason: "Required for fraud detection and prevention."
3. **Identifiers → Device ID** — Purpose: App Functionality. Check "Yes, device ID is linked to user identity."

**Privacy Policy** — update your App Store privacy policy with the following disclosure:

> For fraud protection purposes only, (1) we collect your Battery Usage, Device Identifier, Device Storage, and location information; (2) we also collect enough information to determine if you are trying to fake your current location by using a VPN or other location-spoofing tools.

## Quickstart

The canonical flow:

> `setupCoinmeRiskEngine` **→** `getPartnerSessionTag` **→** `updateCoinmeRiskEngine` **with the returned** `webSessionID` **→** `submitCoinmeRiskData` **→ your server call.**

```typescript
import {
  getDeviceFingerprint,
  getPartnerSessionTag,
  setupCoinmeRiskEngine,
  submitCoinmeRiskData,
  updateCoinmeRiskEngine,
} from '@coinme-security/risk-sdk-react-native';

// 1. Initialise the engine first — before any session-tag call.
await setupCoinmeRiskEngine({
  mode: 'prod',
  clientId: 'your-client-id',
  customerId: 'customer-123',
});

// 2. Right before the payment-method or order call, fetch the session tag
//    (requires the engine to be initialised). Tags live 30 minutes.
//    Partner apps use getPartnerSessionTag; it takes no auth token.
const { webSessionID } = await getPartnerSessionTag({
  partnerId: 'your-partner-id',
  customerId: 'customer-123',
  rampId: 'optional-ramp-id',
  // From 1.1.0 fingerprint is optional: the shared device fingerprint is sent for you.
});

// 3. Bind the session key to the running engine.
await updateCoinmeRiskEngine({ sessionKey: webSessionID });

// 4. Flush signals before the transaction-initiating server call.
await submitCoinmeRiskData();

// 5. Make the server call with the fingerprint every Coinme SDK sends.
await fetch('https://api.coinme.com/transactions', {
  headers: { 'x-device-fingerprint': await getDeviceFingerprint() },
  // ...
});
```

`getPartnerSessionTag` resolves its URL automatically from the `mode` you passed to `setupCoinmeRiskEngine`. It needs your partner ID and no token.

> **The Risk SDK takes no auth token from your app.**
>
> In a partner app, always get the session tag with `getPartnerSessionTag`. Never pass your partner access token (from `POST /services/authorize`) or a [Transient Auth Token](https://platformdocs.coinme.com/docs/transient-auth-token.md) to the Risk SDK.

## The fingerprint contract

The fingerprint sent with `getPartnerSessionTag` **MUST be byte-identical** to the `x-device-fingerprint` header on every other Coinme call for the same user in the same launch of your app: the calls the other Coinme SDKs make and your own backend calls. It only has to match within a launch; it is not a permanent device ID.

**Mismatched fingerprints get calls refused.** Adding a payment method and placing orders fail with `WEB_SESSION_ID_MISMATCH`.

### The SDK keeps the fingerprint for you

From release 1.1.0 you don't have to generate or store a fingerprint, and `fingerprint` is optional. The SDK uses the value you pass; otherwise the one another Coinme SDK already shared in your app; otherwise it creates one and shares it. It keeps the value in native storage, so the same value survives relaunches.

Import the Risk SDK at the top of your app's entry file (for example `index.js`), so it loads the stored value before the other Coinme SDKs need it:

```typescript
// index.js
import '@coinme-security/risk-sdk-react-native';
```

If you already have a device ID of your own, such as `getUniqueId()` from `react-native-device-info`, you can keep passing it as `fingerprint`; it becomes the shared value. Pass it to the Risk SDK before the other Coinme SDKs make a call, or pass the same value to all of them. A `:` in it is replaced with `-`.

With a release older than 1.1.0, `fingerprint` is required: pass one value to `getPartnerSessionTag` and send the same value as `x-device-fingerprint` on your other calls.

### Sending it on your own calls

`getDeviceFingerprint()` returns a Promise of the shared value. Read it in the app and send it to your server with each request; route your HTTP client through it so the value never drifts:

```typescript
// src/api/fetch.ts
import { getDeviceFingerprint } from '@coinme-security/risk-sdk-react-native';

export const apiFetch = async (url: string, init: RequestInit = {}) =>
  fetch(url, {
    ...init,
    headers: {
      ...(init.headers as Record<string, string>),
      'x-device-fingerprint': await getDeviceFingerprint(),
    },
  });
```

## Lifecycle

The three calls you need to think about:

```
App start ─▶ setupCoinmeRiskEngine      ◀── no sessionKey needed yet
                    │
                    ▼
             getPartnerSessionTag
             (returns webSessionID)
                    │
                    ▼
          updateCoinmeRiskEngine        ◀── sessionKey = webSessionID
          (also: customerId, flow, …)
                    │
                    ▼
          submitCoinmeRiskData          ◀── before every transaction-initiating call
                    │
                    ▼
             your server call
          (x-device-fingerprint header)
```

1. **Setup once per app session.** `sessionKey` is optional at setup — the native SDK auto-generates one if omitted. After calling `getPartnerSessionTag`, pass the returned `webSessionID` to `updateCoinmeRiskEngine`. Call `getPartnerSessionTag` again right before each add-payment-method call and each order: a session tag lives 30 minutes from when it was issued, and using it doesn't extend that.
2. **Update whenever context changes.**

- User logs in → `updateCoinmeRiskEngine({ customerId })`
- User starts a high-risk flow → `updateCoinmeRiskEngine({ flow: FlowType.CardTransaction })`

Cached config is merged, not replaced. The underlying native SDK auto-submits on update.

1. **Submit before every transaction-initiating server call.** Forgetting this produces no error at the SDK layer — signals are collected but never flushed — and the downstream transaction will be rejected by Coinme's services.

**On session rotation** (logout, account switch), call `clearSessionKey()` and start the cycle over with a fresh `getPartnerSessionTag`.

## Tracking user input

### `<CoinmeTrackedTextInput>` — the recommended path

A drop-in replacement for React Native's `TextInput`. Wires `onChangeText` / `onFocus` / `onBlur` to the native risk engine under a stable `riskIdentifier`, and forwards every other prop — including your own callbacks and refs — unchanged.

```typescript
import { useState } from 'react';
import { CoinmeTrackedTextInput } from '@coinme-security/risk-sdk-react-native';

export const LoginForm = () => {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');

  return (
    <>
      <CoinmeTrackedTextInput
        riskIdentifier="email"
        value={email}
        onChangeText={setEmail}
        autoCapitalize="none"
        keyboardType="email-address"
      />
      <CoinmeTrackedTextInput
        riskIdentifier="password"
        value={password}
        onChangeText={setPassword}
        secureTextEntry
      />
    </>
  );
};
```

Works in both controlled and uncontrolled mode. Your own `onChangeText` / `onFocus` / `onBlur` are still invoked.

### Raw trackers (escape hatches)

For custom components or imperative flows where `CoinmeTrackedTextInput` doesn't fit:

```typescript
import {
  trackRiskFocusChange,
  trackRiskTextChange,
} from '@coinme-security/risk-sdk-react-native';

await trackRiskTextChange('coupon_code', value);
await trackRiskFocusChange('coupon_code', true);
```

**Rules:**

- Use the same `riskIdentifier` for both the text and focus calls on a given field
- Use descriptive, stable identifiers: `"email"`, `"password"`, `"cardNumber"` — not `"input1"`
- Prefer `CoinmeTrackedTextInput` when you can — it handles the wiring for you

> **No page tracking.**
>
> The iOS and Android SDKs don't expose a page-tracking primitive, and this package matches that. There is no `trackRiskPage` or `useTrackCoinmeRiskPage` export.

## When to submit data

`submitCoinmeRiskData()` flushes the in-memory buffer of collected signals to the Risk Engine. It is what makes the signals available to Coinme's transaction services for evaluation.

### Call it before every transaction-initiating server call

Examples of calls that require a preceding `submitCoinmeRiskData()`:

- Payment and card charge endpoints
- Wallet transfers and crypto transactions
- Onboarding and KYC submissions
- Adding or updating payment methods
- Money transfers and withdrawals

If you are unsure whether a given endpoint requires risk signals, assume it does. Transactions that reach Coinme's services without correlated risk data will be rejected.

### What gets submitted

- Behavioral biometrics (typing patterns, interaction timing)
- Sensor data (motion, orientation, device position)
- Device context (clipboard, focus patterns, screen time)
- All tracked field interactions

### Operational notes

- **Safe to call multiple times** — the latest collected data is sent each time
- **Always await it** before the server call it precedes
- **Submit failures are not automatically retried** — if the call rejects, the subsequent transaction will not have correlated signals and will be rejected by Coinme's services

```typescript
try {
  await submitCoinmeRiskData();
  await processPayment();
} catch (err) {
  console.error('Risk subtumit failed', err);
  // The subsequent transaction will not have correlated signals — do not proceed.
}
```

## API reference

All exports are named. There are no default exports.

### Functions

| Export | Description |
| --- | --- |
| `setupCoinmeRiskEngine` | Initialize the native Risk Engine. `sessionKey` is optional — omit at setup, then pass the `webSessionID` from the session-tag call via `updateCoinmeRiskEngine`. |
| `updateCoinmeRiskEngine` | Merge config updates (`customerId`, `flow`, `sessionKey`, …) into the cached session. Throws if called before setup. |
| `getCoinmeRiskEngineConfig` | Returns the locally cached config. Never round-trips to native. |
| `clearSessionKey` | Clears the in-memory session key. Use on logout / account switch. |
| `submitCoinmeRiskData` | Flushes collected signals to the Risk Engine. Call before every transaction-initiating server request. |
| `getPartnerSessionTag` | Calls Coinme's public partner session-tag endpoint. URL is auto-resolved from `mode`. |
| `getDeviceFingerprint` | From 1.1.0. Returns a Promise of the device fingerprint the Coinme SDKs in your app share. |
| `getWebSessionId` | From 1.1.0. Returns the session ID to send as `webSessionId`: the `webSessionID` from the last session-tag call, or `undefined`. |
| `trackRiskTextChange` | Imperative text-change tracker. |
| `trackRiskFocusChange` | Imperative focus / blur tracker. |

### Components

| Export | Description |
| --- | --- |
| `CoinmeTrackedTextInput` | `TextInput` wrapper that tracks change / focus / blur by `riskIdentifier`. Forwards all other props unchanged. |

### Enums and types

| Type | Description |
| --- | --- |
| `FlowType` | Enum — `Onboarding`, `CardTransaction`, `CardLinking`. |
| `Mode` | `'test' \| 'prod'`. |
| `AppRegion` | `'default' \| 'eu' \| 'ca' \| 'in' \| 'au'`. Mirrors the native SDKs. |
| `RiskEngineSetupOptions` | Options for `setupCoinmeRiskEngine`: `mode`, `clientId`, `sessionKey?`, `flow?`, `customerId?`, `partnerId?`, `region?`, `enableBehaviorBiometrics?`, `enableClipboardTracking?`, `enableFieldTracking?`. |
| `RiskEngineUpdateOptions` | Partial update shape: `sessionKey?`, `flow?`, `customerId?`, … |
| `RiskEngineConfig` | Shape of the cached config returned from `getCoinmeRiskEngineConfig`. |
| `GetPartnerSessionTagOptions` | Options for `getPartnerSessionTag`: `partnerId`, `customerId`, `fingerprint?`, `rampId?`, `timeout?`, `additionalHeaders?`. |
| `SessionTagData` | `{ webSessionID: string; orgID?: string }`. |
| `CoinmeTrackedTextInputProps` | Extends React Native's `TextInputProps` with a required `riskIdentifier: string`. |

### Setup options in detail

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `mode` | `Mode` | Yes | — | `'test'` or `'prod'` |
| `clientId` | `string` | Yes | — | Your Coinme-issued client ID |
| `partnerId` | `string` | No | — | Partner identifier (distinct from `clientId`) |
| `customerId` | `string` | No | — | Customer / user identifier |
| `sessionKey` | `string` | No | auto | Session key — auto-generated if omitted |
| `flow` | `FlowType` | No | — | `Onboarding`, `CardTransaction`, or `CardLinking` |
| `region` | `AppRegion` | No | default | `default` (US), `eu`, `ca`, `au`, `in` |
| `enableBehaviorBiometrics` | `boolean` | No | `true` | Enable behavioral biometrics collection |
| `enableClipboardTracking` | `boolean` | No | `false` | Enable clipboard activity tracking |
| `enableFieldTracking` | `boolean` | No | `true` | Enable automatic field tracking |

> `clientId` and `partnerId` are **different values**. Do not use them interchangeably.

### Platform parity

This package's public API mirrors the `CoinmeRiskEngine` surface of `risk-sdk-ios` and `risk-sdk-android` — the same lifecycle, the same option names, the same two session-tag variants. If you maintain a native iOS or Android app alongside an RN app, your integration code will look the same in all three.

## Privacy & compliance

### User consent for behavior biometrics

If `enableBehaviorBiometrics` is `true` (the default), ensure users have agreed to your privacy policy **before** collecting any biometric data. This is required for GDPR, CCPA, and equivalent privacy regulations.

One way to handle this is to defer `setupCoinmeRiskEngine` until consent is recorded on first launch, or to initialise with `enableBehaviorBiometrics: false` and flip it later via `updateCoinmeRiskEngine`. The right approach depends on your app's consent flow — check with your legal and compliance teams.

### Privacy policy disclosures

Update your app's privacy policy to disclose data collection for fraud protection. The required disclosure text is in section 7.3 (Android) and section 7.5 (iOS).

### Store-listing requirements

- **Google Play** — declare data types in the Data Safety section (see section 7.3)
- **App Store** — declare data types in App Privacy (see section 7.5)

Your Coinme integration contact may provide pre-filled CSV imports for both.

## Expo support

Step-by-step instructions for adding `@coinme-security/risk-sdk-react-native` to an existing Expo app (managed workflow with `expo prebuild`).

### Prerequisites

- Expo SDK 51+
- iOS deployment target 16.0+ (set automatically by the plugin)
- Android `minSdkVersion` 24+
- `CLOUDSMITH_TEAM_TOKEN` — the Cloudsmith entitlement token provided by Coinme during onboarding. Ask your Coinme integration contact if you don't have it.

### Before you begin — export your token

Export `CLOUDSMITH_TEAM_TOKEN` once at the start of your terminal session. All subsequent commands in this guide (package install, `pod install`, Gradle build) will pick it up automatically.

```bash
export CLOUDSMITH_TEAM_TOKEN=<your-token>
```

### 1. Install the JS package

The package is hosted on a private Cloudsmith npm registry. Configure the scope before installing by adding the registry to your project's config file at the repo root.

`.npmrc` (npm / Yarn Classic):

```bash
@coinme-security:registry=https://npm.coinme.com/coinme-security-wrapper/
//npm.coinme.com/coinme-security-wrapper/:_authToken=${CLOUDSMITH_TEAM_TOKEN}
```

`.yarnrc.yml` (Yarn Berry v2+):

```yaml
nodeLinker: node-modules

npmScopes:
  coinme-security:
    npmRegistryServer: 'https://npm.coinme.com/coinme-security-wrapper/'
    npmAuthToken: '${CLOUDSMITH_TEAM_TOKEN}'
```

Then install:

```bash
yarn add @coinme-security/risk-sdk-react-native
```

### 2. Add the config plugin

Add the plugin to your Expo config. No options are required — native credentials are resolved from `CLOUDSMITH_TEAM_TOKEN` at build time, not stored in the config.

`app.json`:

```json
{
  "expo": {
    "plugins": [
      "@coinme-security/risk-sdk-react-native"
    ]
  }
}
```

`app.config.js` (if you use a dynamic config):

```javascript
export default {
  // ...
  plugins: [
    '@coinme-security/risk-sdk-react-native',
  ],
};
```

### 3. Build and run

The plugin applies all native changes automatically during prebuild. You do not need to manually edit any native files.

| Platform | What the plugin configures |
| --- | --- |
| iOS `Podfile` | Adds Cloudsmith CocoaPods source (token read at `pod install` time via `ENV.fetch`) |
| iOS `Podfile` | Sets deployment target to `16.0` |
| Android `build.gradle` | Adds Cloudsmith Maven repository (token read at build time via `System.getenv`) |
| Android `build.gradle` | Forces Kotlin 2.3.0 and adds resolution strategies |

**iOS:**

```bash
npx expo run:ios
```

**Android:**

```bash
npx expo run:android
```

These commands run `expo prebuild` (if needed), `pod install` / Gradle build, and launch on device. Because `CLOUDSMITH_TEAM_TOKEN` is already exported, no extra steps are required.

> To regenerate native directories from scratch, run `expo prebuild --clean` before `npx expo run:ios` / `npx expo run:android`.

### 4. JS integration

#### 4a. Initialization sequence

The native engine must be initialized **before** calling `getPartnerSessionTag`. Use `setupCoinmeRiskEngine` first, then fetch the session tag and update the engine with it:

```typescript
import {
  setupCoinmeRiskEngine,
  getPartnerSessionTag,
  updateCoinmeRiskEngine,
  FlowType,
} from '@coinme-security/risk-sdk-react-native';

// Step 1 — initialize the native engine
await setupCoinmeRiskEngine({
  mode: 'test', // 'test' | 'prod'
  clientId: CLIENT_ID,
  partnerId: CAAS_PARTNER_ID,
  customerId: CUSTOMER_ID,
  flow: FlowType.Onboarding,
  enableFieldTracking: true,
  enableBehaviorBiometrics: true,
});

// Step 2 — right before each add-payment-method call and each order, get the
// session tag (requires the engine to be initialized). Tags live 30 minutes.
const tag = await getPartnerSessionTag({
  partnerId: CAAS_PARTNER_ID,
  customerId: CUSTOMER_ID,
});

// Step 3 — bind the session key to the running engine
await updateCoinmeRiskEngine({ sessionKey: tag.webSessionID });
```

> `CLIENT_ID` and `CAAS_PARTNER_ID` are **different values**. Do not use them interchangeably.

#### 4b. Tracked input fields

Replace standard `TextInput` components with `CoinmeTrackedTextInput` to forward keystrokes and focus events to the native SDK:

```typescript
import { CoinmeTrackedTextInput } from '@coinme-security/risk-sdk-react-native';

<CoinmeTrackedTextInput
  riskIdentifier="email"
  keyboardType="email-address"
  autoCapitalize="none"
  placeholder="you@example.com"
  style={styles.input}
/>

<CoinmeTrackedTextInput
  riskIdentifier="password"
  secureTextEntry
  placeholder="password"
  style={styles.input}
/>
```

`riskIdentifier` is a stable string label that the SDK uses to associate events with a specific field.

### 5. Complete integration skeleton

Minimal end-to-end example — SDK calls only, no UI boilerplate. Replace the `REPLACE_ME_*` constants with your real values.

```typescript
import {
  CoinmeTrackedTextInput,
  FlowType,
  getPartnerSessionTag,
  setupCoinmeRiskEngine,
  updateCoinmeRiskEngine,
} from '@coinme-security/risk-sdk-react-native';

const CLIENT_ID = 'REPLACE_ME_CLIENT_ID';
const CAAS_PARTNER_ID = 'REPLACE_ME_CAAS_PARTNER_ID'; // distinct from CLIENT_ID
const CUSTOMER_ID = 'REPLACE_ME_CUSTOMER_ID';

// Step 1 — initialize the native engine
const handleInit = async () => {
  await setupCoinmeRiskEngine({
    mode: 'test', // 'test' | 'prod'
    clientId: CLIENT_ID,
    partnerId: CAAS_PARTNER_ID,
    customerId: CUSTOMER_ID,
    flow: FlowType.Onboarding,
    enableFieldTracking: true,
    enableBehaviorBiometrics: true,
  });
};

// Step 2 — right before each add-payment-method call and each order, fetch a
// session tag and bind it to the engine. Tags live 30 minutes.
const handleGetSessionTag = async () => {
  const tag = await getPartnerSessionTag({
    partnerId: CAAS_PARTNER_ID,
    customerId: CUSTOMER_ID,
  });
  await updateCoinmeRiskEngine({ sessionKey: tag.webSessionID });
};

// Step 3 — tracked input fields (call after step 2)
const TrackedForm = () => (
  <>
    <CoinmeTrackedTextInput
      riskIdentifier="email"
      keyboardType="email-address"
      autoCapitalize="none"
      placeholder="you@example.com"
    />
    <CoinmeTrackedTextInput
      riskIdentifier="password"
      secureTextEntry
      placeholder="password"
    />
  </>
);
```

### 6. Required values

| Value | Description |
| --- | --- |
| `CLOUDSMITH_TEAM_TOKEN` | Pulls native `CoinmeRiskSDK` binaries during pod install and Gradle sync |
| `CLIENT_ID` | Identifies your app to the Risk Engine |
| `CAAS_PARTNER_ID` | Partner identifier — distinct from `CLIENT_ID` |

## Troubleshooting

### `Native module CoinmeRiskEngine not linked`

The JS layer couldn't find `NativeModules.CoinmeRiskEngine` at runtime.

**Likely causes:**

- **You added the package but didn't rebuild the native app.**

  ```bash
  cd ios && pod install
  cd .. && yarn ios
  # and
  yarn android
  ```
- **Cloudsmith auth failing.** Check the `pod install` / Gradle sync logs. If CocoaPods or Gradle can't reach Coinme's Cloudsmith, the native module won't link. Verify `CLOUDSMITH_TEAM_TOKEN` is exported in the shell you're building from, or set in `~/.gradle/gradle.properties` for Gradle persistence.
- **New Architecture enabled.** The module is registered on the legacy bridge only. If Fabric / TurboModules is on, the runtime won't see it. Confirm `new_arch_enabled: false` in `Podfile` and `newArchEnabled=false` in `android/gradle.properties`.
- **Metro cache.** After a successful rebuild, clear Metro with `yarn start --reset-cache`.

### `Module was compiled with an incompatible version of Kotlin` (Android)

The native `risk-sdk-android` artifact is compiled with Kotlin 2.3.0, but React Native 0.81's Gradle plugin pins an older Kotlin. Force Kotlin 2.3.0 across all subprojects via `resolutionStrategy` — see section 6.3, Step 2 for the full copy-pasteable block.

**Expo:** If the error persists after applying the resolution strategy, re-run prebuild from scratch and verify the plugin ran:

```bash
expo prebuild --clean
npx expo run:android
```

Check that `android/build.gradle` contains `classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:2.3.0")` and the `// @coinme-risk-sdk:kotlin-version` marker. If those are missing, the plugin didn't run — verify `@coinme-security/risk-sdk-react-native` is listed under `plugins` in your Expo config.

### `Could not find com.coinme:risk-sdk-android`

`CLOUDSMITH_TEAM_TOKEN` is missing or wrong. Export it before building:

```bash
export CLOUDSMITH_TEAM_TOKEN=<your-token>
```

Also verify the Maven block in `android/settings.gradle` reads from the same env var.

**Expo:** Re-export and retry with:

```bash
export CLOUDSMITH_TEAM_TOKEN=<your-token>
npx expo run:android
```

### `pod install` fails with `401 Authentication required`

Token is wrong or expired. Re-export `CLOUDSMITH_TEAM_TOKEN` and run `pod install` again. If you have a stale cache from a previous failed attempt:

```bash
rm -rf ~/Library/Caches/CocoaPods ~/.cocoapods/repos
```

**Expo:** Re-export and retry with:

```bash
export CLOUDSMITH_TEAM_TOKEN=<your-token>
npx expo run:ios
```

### `KeyError: key not found: CLOUDSMITH_TEAM_TOKEN` (Expo)

`CLOUDSMITH_TEAM_TOKEN` was not set when `expo prebuild` triggered `pod install`. Export it and re-run:

```bash
export CLOUDSMITH_TEAM_TOKEN=<your-token>
npx expo run:ios
```

### `NativeModules.CoinmeRiskEngine is undefined` (Expo)

The native module didn't link during prebuild. Clean and rebuild:

```bash
# iOS
expo prebuild --clean && npx expo run:ios

# Android
expo prebuild --clean && npx expo run:android
```

### `RiskEngine is not initialized. Call setupCoinmeRiskEngine() first.`

`getPartnerSessionTag` / `updateCoinmeRiskEngine` was called before `setupCoinmeRiskEngine` completed. Always `await setupCoinmeRiskEngine(...)` first.

### My integration looks fine but transactions are being rejected

**Most common cause:** you're not calling `submitCoinmeRiskData` before your server requests. This produces no error at the SDK layer — the SDK collects signals and never flushes them — but without correlated signals, Coinme's transaction services will reject the downstream request.

**Checklist:**

1. `await submitCoinmeRiskData()` immediately before any transaction-initiating server call (checkout, payment-method link, onboarding submit, etc.)
2. Confirm every Coinme SDK and your backend calls send the same `x-device-fingerprint` (read it with `getDeviceFingerprint()`) — see section 9
3. Confirm `mode` is `'prod'` in production builds. A mismatched `mode` / `clientId` routes data to the wrong environment
4. Confirm `setupCoinmeRiskEngine` has completed (await it) before any `updateCoinmeRiskEngine` call. Parallel setup/update races can lead to overridden config

### `updateCoinmeRiskEngine` throws before I've called setup

By design. If no `sessionKey` has ever been set (via `setupCoinmeRiskEngine` or `getPartnerSessionTag`), `updateCoinmeRiskEngine` will throw. Call setup first.

## Support

For issues, questions, or feature requests, ask your Coinme integration contact.

## Device fingerprint

Coinme ties risk checks to a device ID sent as the `X-Device-Fingerprint` header. On the web and React Native you don't have to supply one.

- If you pass a fingerprint, this SDK uses it and shares it with the other Coinme SDKs in your app. Pass the same value to every Coinme SDK, or pass it to the Risk SDK first, which shares it with the others.
- If you don't, the SDK uses the one another Coinme SDK already set in your app, or creates one.
- Every Coinme SDK in your app must send the same value. If they differ, adding a payment method and placing orders fail with `WEB_SESSION_ID_MISMATCH`.
- Leaving the header out needs these releases or later: Risk SDK for Web 1.2.0, Risk SDK for React Native 1.1.0, Vault SDK for JavaScript 1.3.0, Vault SDK for React Native 1.3.0, Onboarding SDK for JavaScript & React 1.7.0, Onboarding SDK for React Native 1.2.0. With an older release, pass every Coinme SDK the same `X-Device-Fingerprint` you give the Risk SDK.
- Calls your server makes to Coinme for this user (for example orders) must send the same value. Read it in your web page or app with the SDK's `getDeviceFingerprint()` (on React Native it returns a Promise) and send it to your server with the request. Never call `getDeviceFingerprint()` on your server.
- On the web the value belongs to the browser and the site's origin, not the device: a page on another origin gets a different one.
- A `:` in the value is replaced with `-`.
- A risk session tag lives 30 minutes from when it was first issued. Fetch it right before adding a payment method or placing an order, and send the tag it returns as `webSessionId`.
