Introduction

The React Native ArkoseLabs SDK lets you integrate Arkose Labs' bot mitigation and fraud prevention solution into your React Native apps using native function calls for Android and iOS. This guarantees seamless integration with Arkose's full interactive challenges for detection and enforcement, without the extended wait times for separate mobile solutions.

This page covers the Mobile SDK for React Native. If you are developing for Android or iOS natively, see the Mobile SDK for Android page and Mobile SDK for iOS page.

Arkose Mobile SDK for React Native:

• Wraps Arkose's Advanced Enforcement Challenge in native Android/iOS "web views".
• Ensures 1-to-1 feature availability between the native Android/iOS SDKs and the React Native SDK.
• Integrates with your apps through a React Native Bridge.
• Handles errors and challenge interactions through callback events.
• Complies with Arkose Internal Security guidelines.
• Complies with Google Play Store and Apple App Store guidelines for seamless integration.
• Is fully compatible with new Enforcement Challenge-API (EC-API) releases.
• Supports minimum Android OS version 5.0 and iOS version 12.0.

Mobile SDK High Level Design

Architecture

The SDK uses a React Native Bridge to enable communication between the React Native JavaScript layer and the native iOS/Android SDKs. All existing detection and challenge features on our native Android/iOS SDKs are also available in the React Native SDK.

Security

The SDK is reviewed by Arkose Labs Security and complies with the respective guidelines of the Apple App Store and Google Play Store. The SDK ensures secure handling of challenges and user interactions, adhering to industry standards for data protection and safety.

Performance

We created the Arkose Labs Mobile SDKs with stability and performance in mind. Their use has no significant impact on the host application’s performance.

Installation

Follow the steps below to set up the ArkoseLabs SDK for React Native in your host application. These steps apply to both iOS and Android, covering detection and enforcement components.

Prerequisites

Ensure you have the following installed:

• React Native: Follow the React Native Documentation guide to set up your environment for iOS and Android.
• Xcode (for iOS development).
• Android Studio (for Android development).
• For the full end-to-end Arkose setup, you must also complete the standard Arkose Server-Side setup instructions.

Steps for Integration

Step 1: Download the SDK .tgz File

The Arkose Labs Mobile SDKs are available via the Mobile SDK's Support page. Please talk with your CSM (Customer Success Manager) about your intended usage and request access.

Download the SDK .tgz file from the appropriate source and place it inside the app/lib directory of your project.

Step 2: Clean the Environment

Before setting up the app, clean up any existing dependencies and previous builds:

# Remove node_modules and lock files
rm -rf node_modules
rm package-lock.json
npm cache clean --force

Step 3: Install Dependencies

Install the necessary dependencies for the app:

npm install

Step 4: Install SDK .tgz File

There are two options for installing the SDK:

Option 1: Using npm install directly

You can directly install the SDK .tgz file with the following command:

npm install ./lib/react-native-arkoselabs-2.12.0.tgz

This assumes the .tgz file is placed in the lib directory of your project.

Option 2: Manually Editing package.json

Alternatively, you can modify the package.json file to include the SDK as a local dependency. Add the following line to the dependencies section of your package.json:

"react-native-arkoselabs": "file:./lib/react-native-arkoselabs-2.12.0.tgz"

Then, run the following command to install dependencies:

npm install

Setup Instructions - iOS

Step 1: Clean iOS Environment

Before setting up the iOS-specific configuration, clean the environment to remove old dependencies and builds:

# For iOS, clean the Pods
cd ios
pod deintegrate
pod cache clean --all
rm Podfile.lock
cd ..

Step 2: Update Podspec

Modify the react-native-arkoselabs.podspec file located at app/node_modules/react-native-arkoselabs/react-native-arkoselabs.podspec to point to the correct location of the .tgz file:

s.source = { :http => 'file:///{project-location}/app/lib/react-native-arkoselabs-x.x.x.tgz' }

Make sure you replace the x.x.x with the appropriate version of the ArkoseLabs React Native SDK.

Replace {project-location} with the absolute path to your project. For example, if your project is located at /Users/yourname/projects/, the path would be:

s.source = { :http => 'file:///Users/yourname/projects/app/lib/react-native-arkoselabs-x.x.x.tgz' }

Step 3: Modify Podfile

After target 'YourProject' do in the app/ios/Podfile, make sure you add this line to include the pod:

pod 'react-native-arkoselabs', :podspec => '../node_modules/react-native-arkoselabs'

Then, install the iOS Pods:

cd ios
pod install
cd ..

Step 4: Link the SDK to Your App

Link the ArkoseLabs framework in Xcode:

1. Open the iOS workspace in Xcode by running the following command:
2. In Xcode, link the ArkoseLabs framework in both the Pods project settings and the YourProject settings.
3. Set Embed Settings:
   1. Pods → react-native-arkoselabs module: Link the ArkoseLabsKit.xcframework and set it to "Do Not Embed".
   2. In YourProject module: Link the ArkoseLabsKit.xcframework and set it to "Embed & Sign". (if required)

Step 5: Run the App

Start the development server with a reset cache to avoid common issues:

npx react-native start --reset-cache

If you encounter a Watchman error (e.g., "EMFILE: too many open files, watch"), clear the Watchman watches:

watchman watch-del-all

After starting the server, press i in the terminal to run the app on iOS. If a scheme error occurs:

• Open Xcode and delete Settings → Locations → Derived Data.
• Clean the build folder in Xcode:
  Shift + Command + K
• Rebuild the app in Xcode:
  Command + B
• Run the app again:
  Command + R

Setup Instructions - Android

Step 1: Clean Android Environment

Before setting up the Android-specific configuration, clean the environment to remove old dependencies and builds:

# For Android, remove Arkose local maven
cd android
./gradlew clean
rm -rf arkoseLib
cd ..

Step 2: Configure Android Maven Publish Plugin

In the project-level build.gradle file, add the following configuration:

apply plugin: "maven-publish"
publishing {
  publications {
    arkoseAar(MavenPublication) {
      groupId = 'com.arkoselabs'
      artifactId = 'android-sdk'
      version = '2.12.0'
      artifact("../node_modules/react-native-arkoselabs/android/libs/ArkoseLabsSDK.aar")
    }
  }
  repositories {
    maven {
      url = uri("$rootDir/arkoseLib")
    }
  }
}
tasks.register("publishArkoseLib") {
  dependsOn("publishArkoseAarPublicationToMavenRepository")
  group = "publishing"
  description = "Publishes the Arkose Labs SDK to the local Maven repository in /arkoseLib"
}

Step 3: Publish the Maven Artifact

Run the following command in your terminal:

cd android
./gradlew publishArkoseLib
cd ..

The published file will be located in the arkoseLib folder under your project’s root directory (rootDir), which is where the project-level build.gradle or settings.gradle file is located.

This step is important for syncing the Arkose dependencies in the app-level build.gradle file.

Step 4: Configure Maven Repository

In the settings.gradle file, add the following configuration above rootProject.name = 'YourProject':

dependencyResolutionManagement {  
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)  
    repositories {  
        google()  
        mavenCentral()  
        maven {
          url uri("$rootDir/arkoseLib")
        }  
    }  
}  

Step 5: Add Arkose SDK Dependencies

In the app-level build.gradle file, add the following lines to the dependencies block:

// Arkose SDK
implementation 'com.arkoselabs:android-sdk:2.12.0'  

Step 6: Steps for Gradle Versions Below 8.5 (Optional)

If the automatic linking does not happen in Gradle versions below 8.5, follow these additional steps:

1. In the settings.gradle of the project, add the following line after include ':app':

   include ':react-native-arkoselabs'
   project(':react-native-arkoselabs').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-arkoselabs/android')
   

2. In the app-level build.gradle, add the following implementation line under the dependencies section:

   // Arkose SDK
   implementation project(':react-native-arkoselabs')  // Add this line
   implementation 'com.arkoselabs:android-sdk:2.12.0'
   

3. In the app's src/.../MainApplication, insert the following line inside the PackageList(this) block:

   override val reactNativeHost: ReactNativeHost =
       object : DefaultReactNativeHost(this) {
           override fun getPackages(): List<ReactPackage> =
               PackageList(this).packages.apply {
                   // Packages that cannot be autolinked yet can be added manually here, for example:
                   // add(MyReactNativePackage())
                   add(RNArkoseManagerPackage())  // Add this line
               }
           override fun getJSMainModuleName(): String = "index"
           override fun getUseDeveloperSupport(): Boolean = BuildConfig.DEBUG
           override val isNewArchEnabled: Boolean = BuildConfig.IS_NEW_ARCHITECTURE_ENABLED
           override val isHermesEnabled: Boolean = BuildConfig.IS_HERMES_ENABLED
       }
   

Step 7: Sync your project with Gradle files

In Android Studio, go to the toolbar, click on File, and then select Sync Project with Gradle Files.

Step 8: Run the App

Start the development server with a reset cache to avoid common issues:

npx react-native start --reset-cache

If you encounter a Watchman error (e.g., "EMFILE: too many open files, watch"), clear the Watchman watches:

watchman watch-del-all

After starting the server, press a in the terminal to run the app on Android. If you encounter Gradle or JDK-related errors, open the project in Android Studio:

• Ensure the development server is running.
• Sync Gradle files.
• Clean, build and run the app directly from Android Studio.

Code Snippets

Initialize SDK

Here’s how you initialize the ArkoseLabs SDK with configuration settings. This setup is crucial for using any of the SDK's features.

import { ArkoseEvents, ArkoseManager } from "../node_modules/react-native-arkoselabs/src";
const arkoseConfig = {
  apiKey: 'your-api-key',              // Your API key from Arkose Labs
  apiBaseUrl: '<Actual API Base URL>', // Optional: Set the API base URL
  language: '',                         // Optional: Set language
  clientAPIRetryCount: 0,               // Optional: Number of retries on client-side errors
  styleTheme: '',                       // Optional: Set style theme
};
const initializeArkose = () => {
  ArkoseManager.initialize(arkoseConfig);
};

Show Enforcement Challenge

To show the enforcement challenge, use the following function. It also accepts optional parameters like the cancelButtonTitle or resetButtonTitle, which are applicable only on iOS.

import { ArkoseEvents, ArkoseManager } from "../node_modules/react-native-arkoselabs/src";
import { Platform } from "react-native";
// Define conditional enforcement parameters based on the platform
const enforcementParams = Platform.OS === "ios" ? {
  cancelButtonTitle: "Cancel", // Only for iOS
  resetButtonTitle: "Reset",  // Only for iOS
} : {};
// Function to show the enforcement challenge
const showEnforcementChallenge = () => {
  ArkoseManager.showEnforcementChallenge(enforcementParams);
};
// Example usage:
<Button onPress={showEnforcementChallenge} title="Show Challenge" />

Arkose Events

The SDK emits several events that can be used to track the state of the challenge and other operations. Here are the available events:

import { ArkoseEvents, ArkoseManager } from "../node_modules/react-native-arkoselabs/src";
import React from "react";
import { Alert } from "react-native";
React.useEffect(() => {
  // Optional: Set log level for informational logs
  ArkoseManager.setLogLevel("info");
  // Add event listeners
  ArkoseEvents.addListener("onReady", () => console.log("SDK is ready to trigger the challenge"));
  ArkoseEvents.addListener("onShow", () => console.log("Challenge is starting to show"));
  ArkoseEvents.addListener("onShown", () => console.log("Challenge is fully rendered"));
  ArkoseEvents.addListener("onHide", () => console.log("Challenge has been hidden"));
  ArkoseEvents.addListener("onSuppress", () => console.log("Challenge is suppressed"));
  ArkoseEvents.addListener("onCompleted", (result) => {
    console.log("Challenge completed successfully", result);
    Alert.alert("Challenge Completed", JSON.stringify(result));
  });
  ArkoseEvents.addListener("onFailed", (result) => {
    console.log("Challenge failed", result);
    Alert.alert("Challenge Failed", JSON.stringify(result));
  });
  ArkoseEvents.addListener("onError", (result) => {
    console.error("An error occurred during the challenge", result);
    Alert.alert("Error", JSON.stringify(result));
  });
  ArkoseEvents.addListener("onWarning", (result) => {
    console.warn("A warning was triggered", result);
  });
  ArkoseEvents.addListener("onResize", (result) => {
    console.log("Challenge resized", result);
  });
}, []);

Note that Arkose’s detection component is part of our overall Arkose Bot Manager platform. Thus the names of some methods and variables refer only to enforcement when actually dealing with detection as well. Unless otherwise specified, the configuration components apply to both detection and enforcement components, although perhaps in different ways as specified.

ArkoseConfig Configuration

References

• React Native Documentation
  Official guide for setting up and developing React Native apps.
• Arkose Labs SDK Documentation
  Comprehensive documentation for integrating Arkose Labs' bot mitigation and fraud prevention.
• Android Mobile SDK
  Documentation for integrating Arkose Labs' Android SDK.
• iOS Mobile SDK
  Documentation for integrating Arkose Labs' iOS SDK.