@humansecurity/react-native-sdk

A React Native wrapper for the Human Security SDK providing a React Native interface to enable seamless integration and access to bot defender and account defender features.

Android — Maven repository

The HUMAN Android SDK v5 is distributed via Maven. Add the HUMAN repository to your project so Gradle can resolve it.

HUMAN Android SDK 5.3.3 requires compileSdk 37 and minSdk 23. This wrapper’s Android module uses minSdk 23 to match. React Native 0.75+ apps already default to 24.

AndroidX / AGP (read this before integrating): HUMAN 5.3.3 pulls androidx.core 1.19 and lifecycle-runtime-compose 2.11. Those artifacts are built for AGP 9.1+. This wrapper does not pin or force them, so we do not override other libraries in your app.

If you do nothing on React Native 0.86 / AGP 8.12, Gradle fails the Android build (unsupported AndroidX / compileSdk), it does not crash the app at runtime after a successful install.

Pick one for AndroidX (this is not about the Gradle wrapper version):

1. Preferred: use AGP 9.1+ with compileSdk 37. You do not need the AndroidX force pins. This wrapper does not pin AGP when autolinked — the host plugin compiles the module. Standalone cd android && ./gradlew (AGP 8.7.3) is unsupported; use the example app.
2. Stay on AGP 8.12 (React Native 0.86 still does): keep your RN Gradle wrapper (the example uses Gradle 9.3.1 because that is the RN 0.86 template — it is not AGP 9.1). Then copy the pin from example/android/build.gradle allprojects into your root build.gradle, and set android.suppressUnsupportedCompileSdk=37,37.0 in gradle.properties.

allprojects {
    configurations.configureEach {
        resolutionStrategy {
            force 'androidx.core:core:1.18.0'
            force 'androidx.core:core-ktx:1.18.0'
            force 'androidx.lifecycle:lifecycle-runtime-compose:2.8.7'
            force 'androidx.lifecycle:lifecycle-runtime-compose-android:2.8.7'
        }
    }
}

Pinning only inside app/build.gradle is often not enough, because autolinking compiles this SDK as its own Gradle module.

Modern setup (settings.gradle):

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_PROJECT)
    repositories {
        maven {
            url "https://jfrog.humansecurity.com/artifactory/human-android-sdk/"
            content {
                includeGroup("com.humansecurity")
            }
        }
    }
}

Legacy setup (project-level build.gradle):

allprojects {
    repositories {
        maven {
            url "https://jfrog.humansecurity.com/artifactory/human-android-sdk/"
            content {
                includeGroup("com.humansecurity")
            }
        }
    }
}

Installation

From your terminal, run:

npm install @humansecurity/react-native-sdk

For iOS, don't forget to install pods:

cd ios && pod install && cd ..

Usage Example

import HumanSecurity from '@humansecurity/react-native-sdk';

//Display the version in a text to confirm integration:
<Text>HumanSecurity SDK Version: {HumanSecurity.sdkVersion()}</Text>;

API Documentation

The full Documentation and usage examples can be found at our official site.

The current API:

  sdkVersion(): string;
  startWithAppId(appId: string, policy?: { [key: string]: string }): Promise<void>;
  startWithAppIds(appIds: string[], policy?: { [key: string]: string }): Promise<void>;
  vid(appId: string): string | null;

  // BD functionality
  headersForURLRequest(appId?: string): Promise<{ [key: string]: string }>;
  handleResponse(response: string): Promise<HSBotDefenderChallengeResult>;
  canHandleResponse(response: string): boolean;
  challengeReferenceId(): string;
  setCustomParameters(parameters: { [key: string]: string }, appId?: string): Promise<void>;

  // Bot Defender Delegates Events
  onBotDefenderEvent: EventEmitter<BotDefenderEvent>;

  // Adding AD functions
  setUserId(userId: string | null, appId?: string): Promise<void>;
  registerOutgoingUrlRequest(url: string, appId?: string): Promise<void>;
  setAdditionalData(parameters: { [key: string]: string },appId?: string): Promise<void>;

Where BotDefenderEvent is defined as:

BotDefenderEvent {
  event:
    | 'botDefenderRequestBlocked'
    | 'botDefenderChallengeSolved'
    | 'botDefenderChallengeCancelled'
    | 'botDefenderChallengeRendered'
    | 'botDefenderChallengeRenderFailed'
    | 'botDefenderDidUpdateHeaders';
  appId: string;
  headers?: { [key: string]: string };
}

Known limitation

When a user completes a challenge but the SDK cannot confirm the pass, typically because the post-challenge token refresh failed due to a network issue, the wrapper reports the challenge as solved. Your application cannot currently distinguish this case from a confirmed pass, and a retried request may be blocked again. A dedicated outcome for this case will be exposed in the next major version.

Upgrading from 2.0.x to 3.0.0

• Host break: requires React Native 0.86.2 or later, Android compileSdk 37, and Android minSdk 23. A 2.0.1-supported app cannot build this package until the host is upgraded. Stay on 2.0.1 until then.
• The JavaScript type surface is unchanged from 2.0.x. There is no SOLVED_WITH_ERROR outcome.
• Unhandled handleResponse: a response the SDK does not handle now resolves FAILED, not CANCELLED. Hosts that branched on CANCELLED for that path must switch to FAILED.
• Android: HUMAN 5.3.3 needs compileSdk 37 and minSdk 23 (this wrapper now declares 23). This package does not force AndroidX. On React Native 0.86 / AGP 8.12, either use AGP 9.1+ or copy the example allprojects AndroidX pins (see the Android section at the top of this README). The Gradle wrapper version is not a substitute for AGP 9.1.

Old Installation of bare React Native projects

For bare React Native workflow projects that require the SDK on both the native platforms and in JavaScript, please refer to our [documentation](https://docs.humansecurity.com/applications-and-accounts/docs/react-native-integration-legacy