React Native

To run the SDK a Verisoul Project ID is required. Schedule a call here 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

npm install @verisoul_ai/react-native-verisoul

Using Yarn

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:

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:

npx expo install expo-dev-client

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

{
  "expo": {
    "newArchEnabled": true,
    "plugins": ["@verisoul_ai/react-native-verisoul"]
  }
}

3. Install Verisoul SDK:

npm install @verisoul_ai/react-native-verisoul

4. Prebuild and run:

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. Call configure() before you intend to retrieve a Verisoul session_id — only initialize the SDK if you plan to call the Verisoul API for that session. Parameters:

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

Example:

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. On iOS, collection begins once the app is in the foreground.

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:

const sessionId = await Verisoul.getSessionID();

On iOS, the SDK collects data only while the app is in the foreground. If getSessionID() is called while the app is in the background (for example during a silent push, background fetch, or location update), it returns once the user opens the app. A cached session is returned right away, and the timeout counts only time spent in the foreground. Don’t await getSessionID() inside background handlers or in other code that has to finish while the app is in the background.

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:

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.

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.

Additional Resources

Verisoul NPM

Overview

Integration

Signals & Scores

Action

Email Intelligence API

Verifications

System Requirements

Installation

Using NPM

Using Yarn

Android Configuration

Expo Projects

Usage

Initialize the SDK

getSessionId()

Provide Touch Events

iOS Configuration

Error Codes

Exception Structure

Example

Additional Resources

​System Requirements

​Installation

​Using NPM

​Using Yarn

​Android Configuration

​Expo Projects

​Usage

​Initialize the SDK

​getSessionId()

​Provide Touch Events

​iOS Configuration

​Error Codes

​Exception Structure

​Example

​Additional Resources

System Requirements

Installation

Using NPM

Using Yarn

Android Configuration

Expo Projects

Usage

Initialize the SDK

getSessionId()

Provide Touch Events

iOS Configuration

Error Codes

Exception Structure

Example

Additional Resources