> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verisoul.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# React Native

> Integrating Verisoul in React Native Apps

*To run the SDK a Verisoul Project ID is required.* Schedule a call [here](https://meetings.hubspot.com/henry-legard) to get started.

## System Requirements

* React Native 0.60 or higher
* iOS 14.0 or higher
* Android API level 21 (Android 5.0) or higher
* For Expo projects: Expo SDK 45 or higher with custom development client
* SDK Size: \~90 KB (plus native iOS and Android SDK dependencies)

## Installation

#### Using NPM

```sh theme={null}
npm install @verisoul_ai/react-native-verisoul
```

#### Using Yarn

```sh theme={null}
yarn add @verisoul_ai/react-native-verisoul
```

#### Android Configuration

If an exception occurs during the build stating that the `ai.verisoul:android` package cannot be downloaded, add the following Maven repository inside your `android/build.gradle` file:

```groovy theme={null}
allprojects {
    repositories {
        // ...
        maven { url = uri("https://us-central1-maven.pkg.dev/verisoul/android") }
    }
}
```

### Expo Projects

> **Note:** Requires custom development client (not supported in Expo Go)

**1. Install expo-dev-client:**

```sh theme={null}
npx expo install expo-dev-client
```

**2. Configure `app.json`: add the plugin and set `newArchEnabled` to `true`**

```json theme={null}
{
  "expo": {
    "newArchEnabled": true,
    "plugins": ["@verisoul_ai/react-native-verisoul"]
  }
}
```

**3. Install Verisoul SDK:**

```sh theme={null}
npm install @verisoul_ai/react-native-verisoul
```

**4. Prebuild and run:**

```sh theme={null}
npx expo prebuild --clean
npx expo run:android  # or npx expo run:ios
```

## Usage

### Initialize the SDK

The `configure()` method initializes the Verisoul SDK with your project credentials. This method must be called once when your application starts.

**Parameters:**

* `environment`: The environment to use `VerisoulEnvironment.prod` for production or `VerisoulEnvironment.sandbox` for testing
* `projectId`: Your unique Verisoul project identifier

**Example:**

```js theme={null}
import Verisoul, {
  VerisoulEnvironment,
} from "@verisoul_ai/react-native-verisoul";

useEffect(() => {
  Verisoul.configure({
    environment: VerisoulEnvironment.prod, // or VerisoulEnvironment.sandbox
    projectId: "YOUR_PROJECT_ID",
  });
}, []);
```

When called, the Verisoul SDK will initialize its components, begin collecting device telemetry data, and prepare a session ID for fraud assessment.

### getSessionId()

The `getSessionID()` method returns the current session identifier after the SDK has collected sufficient device data. This session ID is required to request a risk assessment from Verisoul's API.

**Important Notes:**

* Session IDs are short-lived and expire after 24 hours
* The session ID becomes available once minimum data collection is complete (typically within seconds)
* You should send this session ID to your backend, which can then call Verisoul's API to get a risk assessment
* A new session ID is generated each time the SDK is initialized

**Example:**

```js theme={null}
const sessionId = await Verisoul.getSessionID();
```

### Provide Touch Events

Touch event data is collected and analyzed to detect automated/bot behavior by comparing touch patterns with device sensor data. This helps identify anomalies that may indicate fraud.

**React Native Setup:**

Wrap your root component with `VerisoulTouchRootView` to automatically capture touch events across both iOS and Android:

```js theme={null}
import { VerisoulTouchRootView } from "@verisoul_ai/react-native-verisoul";

function App() {
  return (
    <VerisoulTouchRootView>{/* Your app components */}</VerisoulTouchRootView>
  );
}
```

#### iOS Configuration

For iOS-specific configuration including Device Check and App Attest setup, please refer to the [iOS SDK Documentation](/integration/frontend/ios#ios-device-check).

### Error Codes

The SDK throws `VerisoulException` with the following error codes:

| Error Code                 | Description                                                                                                                                                | Recommended Action                                                                                                  |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| INVALID\_ENVIRONMENT       | The environment parameter passed to `Verisoul.configure()` is invalid. Valid values are "dev", "sandbox", or "prod".                                       | Ensure the environment parameter is exactly "dev", "sandbox", or "prod" (case-sensitive, no whitespace).            |
| SESSION\_UNAVAILABLE       | A valid session ID could not be obtained. This typically occurs when Verisoul's servers are unreachable due to network blocking or a very slow connection. | Implement exponential backoff. Prompt user to check network or disable network blocker.                             |
| WEBVIEW\_UNAVAILABLE       | WebView is not available on the device. This can occur when WebView is disabled, missing, uninstalled, or corrupted on the device.                         | Prompt user to enable WebView in settings, update Android System WebView, or switch devices.                        |
| WEBVIEW\_RENDERER\_CRASHED | The WebView renderer process crashed, typically due to low memory or resource pressure.                                                                    | Retry the request (SDK will attempt recovery), encourage users to update Android System WebView, or switch devices. |

#### Exception Structure

All errors are thrown as `VerisoulException` with the following properties:

| Property | Type       | Description                                             |
| -------- | ---------- | ------------------------------------------------------- |
| code     | String     | One of the error codes above                            |
| message  | String     | Human-readable error description                        |
| cause    | Throwable? | The underlying exception that caused the error (if any) |

## Example

For a complete working example, see the [React Native Sample App](/examples/react-native-sample-app).

## Additional Resources

* [Verisoul NPM](https://www.npmjs.com/package/@verisoul_ai/react-native-verisoul)