React Native Integration (Recommended)

You can integrate the SDK into a React Native project. This article explains how to integrate and implement the HUMAN React Native Wrapper into a React Native app.

Integrate the HUMAN React Native wrapper

1. In the terminal from the command line, run:

$
npm install @humansecurity/react-native-sdk

2. If your app uses iOS, navigate to the ios folder and install pods.

$
cd ios 
$
pod install

HUMAN React Native API

The HUMAN Security React Native Wrapper API offers the following functions:

1
export declare class HumanSecurity {
2
    static sdkVersion(): string;
3
    static startWithAppId(appId: string, policy?: HSPolicy): Promise<void>;
4
    static startWithAppIds(appIds: string[], policy?: HSPolicy): Promise<void>;
5
    static vid(appId: string): string | null;
6
    static BD: {
7
        headersForURLRequest(appId?: string): Promise<{ [key: string]: string }>;
8
        canHandleResponse(response: string): boolean;
9
        handleResponse(response: string): Promise<HSBotDefenderChallengeResult>;
10
        challengeReferenceId(): string;
11
        setCustomParameters(parameters: { [key: string]: string }, appId?: string): Promise<void>;
12
        onBotDefenderEvent(fn: BotDefenderEventCallback): EventSubscription;
13
    };
14
    static AD: {
15
        setUserId(userId: string | null, appId?: string): Promise<void>;
16
        registerOutgoingUrlRequest(url: string, appId?: string): Promise<void>;
17
        setAdditionalData(parameters: { [key: string]: string }, appId?: string): Promise<void>;
18
    };
19
}

Start the SDK

The most important step is to start the SDK as early as possible in your app flow. If your app sends a URL request to your server before the SDK starts, the attached headers won’t include the latest updated tokens. As a result, HUMAN’s Enforcer could block the request, and the SDK won’t present a challenge to the user. Be sure to start the SDK only once.

To start the SDK, call startWithAppId in your main entry point (App.tsx) or at the starting point of your app where you register and initialize one-time services. It’s better to start the SDK outside of any UI component to avoid lifecycle issues.

1
import HumanSecurity from '@humansecurity/react-native-sdk';
2
3
// Initialize the SDK once on app startup
4
(() => {
5
  HumanSecurity.startWithAppId("<APP_ID>") // update with your own app ID
6
    .then(() => {
7
      console.log("SDK started successfully");
8
    })
9
    .catch((error) => {
10
      console.error("Error starting the SDK:", error);
11
    });
12
})();

Policy options

Currently, the HSPolicy class includes two settings:

1. hybridAppPolicy: Use this if your app operates in hybrid mode, meaning it has a WebView that loads a site also protected by HUMAN and running its sensor. In this case, configure all relevant website domains with the app ID.
2. detectionPolicy: This setting lets you configure whether the SDK can send touch and motion events, either touch only or both touch and motion, to the server to improve detection. By default, it’s off, and you can choose to enable it.

For example:

1
import HumanSecurity, { HSPolicy } from '@humansecurity/react-native-sdk';
2
3
(() => {
4
  const policy = {
5
    hybridAppPolicy: {
6
      webRootDomains: {
7
        "<APP_ID>": ["my-domain.com"], // update with your own app ID and domain
8
      },
9
    },
10
    detectionPolicy: {
11
      allowTouchDetection: true,
12
      allowDeviceMotionDetection: true,
13
    },
14
  };
15
16
  HumanSecurity.startWithAppId("<APP_ID>", policy) // update with your own app ID
17
    .then(() => {
18
      console.log("SDK started successfully with policy");
19
    })
20
    .catch((error) => {
21
      console.error("Error starting the SDK with policy:", error);
22
    });
23
})();

Here’s what the code includes:

1. We start the SDK as soon as possible and only once. You can move this code to a different function or file and export it as long as it’s only called once.
2. The startWithAppId function of the SDK is called with the following parameters:
   • Your application ID
   • The policy object, if needed
3. In the second example, an HSPolicy instance configures the SDK’s behavior. This object defines settings such as hybridAppPolicy.webRootDomains, indicating that the app uses WebViews containing pages from a domain also protected by HUMAN Security, which is considered hybrid mode. Additionally, detectionPolicy is configured to send touch and motion data. If these parameters aren’t needed, you can just omit the policy.

Bot Defender integration

Add the SDK’s HTTP headers to your URL requests and handle blocked requests

• The SDK provides HTTP headers that your app must add to URL requests. It’s essential to include these headers in every request.
• You shouldn’t cache these HTTP headers. They contain a token with an expiration date, and the SDK keeps it up to date. Ensure the code isn’t cached so that each request triggers a call to the HumanSecurity module.
• The SDK can handle the blocked request and present a challenge to the user.
• Ensure that arguments are passed correctly to the wrapper. For example, when using axios, you might need to call JSON.stringify(error.response?.data) before passing the response body to the SDK. Additionally, in Axios, the catch block handles blocked responses because it indicates a failed request.

The following are examples using either a fetch API or using axios.

1
import HumanSecurity, { HSBotDefenderChallengeResult } from '@humansecurity/react-native-sdk';
2
3
public static async fetchData(url: string): Promise<any> {
4
    try {
5
        const headers = HumanSecurityManager.getHeaders();
6
7
        const response = await fetch(url, { method: 'GET', headers });
8
        const statusCode = response.status;
9
        const responseText = await response.text();
10
11
        if (statusCode === 200) {
12
            return { status: statusCode, data: responseText };
13
        }
14
15
        if (HumanSecurityManager.canHandleResponse(responseText)) {
16
            const result = await HumanSecurityManager.handleResponse(responseText);
17
            // If challenge was solved, retry the request.
18
            return { challengeResult: HSBotDefenderChallengeResult[result] };
19
        }
20
21
        throw new Error(`Unhandled response - Status: ${statusCode}`);
22
    } catch (error) {
23
        throw error instanceof Error ? error : new Error('Unknown error occurred');
24
    }
25
}

Here’s what the code includes:

1. The SDK provides HTTP headers.
2. The HTTP headers are added to the URL requests.
3. The URL request is sent.
4. In case of an error, the response is sent to the SDK, which checks if it’s a blocked request by calling canHandleResponse. If canHandleResponse returns true, handleResponse is called to present the challenge to the user.
5. The challenge result HSBotDefenderChallengeResult can be one of the following:
   • SOLVED: The user successfully completed the challenge.
   • CANCELED: The user dismissed or failed to complete the challenge.
   • FAILED: The SDK was unable to handle the response, usually indicating that something wasn’t passed correctly to the handleResponse function.

Note that you can await handleResponse, but if you do, you would be waiting until the user solves the challenge. You can also continue your flow and handle the result in the .then block.

What to do when a request is blocked

• Handle it as a failure. Your app should treat the blocked request as a failure. However, keep in mind that your app’s UI will be shown again after the user has solved or canceled the challenge. If the request was triggered by a user action, you should make it clear that the user may try again.
• Use the promise result to write analytics, logs, etc.
• You may use the returned promise to retry the original request when appropriate. Consider the following:
  • The promise returns out of the original request’s scope. Make sure you handle that case correctly.
  • The user might cancel the challenge. In this case, you shouldn’t retry the request because it would be blocked again.
  • The retry attempt might fail. Don’t assume it will be successful.

Understanding the block response

When HUMAN’s Enforcer blocks a request, it returns a JSON string in the response body with status code 403. This body contains metadata for the SDK. For example:

1
{
2
  "vid": "928d7ab3-9cf1-11ee-a624-b802520f369f",
3
  "uuid": "fd01e6d6-9cf2-11ee-808c-acde48001122",
4
  "page": "...",
5
  "appId": "PXj9y4Q8Em",
6
  "action": "captcha",
7
  "collectorUrl": "https://collector-pxj9y4q8em.perimeterx.net"
8
}

Your app should pass the entire JSON as response in a string format to the SDK. Otherwise, the SDK won’t present a challenge to the user.

1
HumanSecurity.BD.handleResponse(response: string): Promise<HSBotDefenderChallengeResult>

Set custom parameters for Bot Defender (optional)

You can set custom parameters to configure HUMAN’s backend with additional values. To do so:

• Set those parameters as an object in JavaScript using keys in the format custom_param_[x], where [x] is a number between 1 and 10.
• Call setCustomParameters after calling startWithAppId.

For example:

1
import HumanSecurity from '@humansecurity/react-native-sdk';
2
3
const setCustomParams = () => {
4
  const parameters = { custom_param_1: 'value1', custom_param_2: 'value2' };
5
6
  HumanSecurity.BD.setCustomParameters(parameters, appId)
7
    .then(() => {
8
      setCustomParamsResult('Custom Parameters Set Successfully');
9
    })
10
    .catch((error) => {
11
      setCustomParamsResult('Failed to Set Custom Parameters: ' + error);
12
    });
13
};

Bot Defender delegates

Bot Defender provides several delegates, or callbacks, to notify about events related to headers and challenges. These callbacks are mainly intended for analytics and statistics rather than for taking specific actions. In the Expo library, these callbacks work as events.

To listen for Bot Defender events, subscribe to the onBotDefenderEvent listener. The received event will be of type BotDefenderEvent and can be handled as needed.

1
useEffect(() => {
2
  const subscription = HumanSecurity.BD.onBotDefenderEvent((event) => {
3
    console.log(
4
      `[HumanSdk] Event received: ${event.event} | AppID: ${event.appId} | Headers: ${JSON.stringify(event.headers)}`
5
    );
6
  });
7
  return () => {
8
    subscription.remove();
9
  };
10
}, []);

BotDefenderEvent structure and event options

Only the botDefenderDidUpdateHeaders event provides headers. The rest have the app ID.

1
export interface BotDefenderEvent {
2
  event:
3
    | 'botDefenderRequestBlocked'
4
    | 'botDefenderChallengeSolved'
5
    | 'botDefenderChallengeCancelled'
6
    | 'botDefenderChallengeRendered'
7
    | 'botDefenderChallengeRenderFailed'
8
    | 'botDefenderDidUpdateHeaders';
9
  appId: string;
10
  headers?: { [key: string]: string };
11
}

Account Defender integration

Enable Account Defender in your app

To enable Account Defender, you should set the UserID of your current logged-in user in the SDK. When the user logs out, make sure to call the function with null to clear the user ID. For example:

1
import HumanSecurity from '@humansecurity/react-native-sdk';
2
3
const setUserId = (userId: string) => {
4
  HumanSecurity.AD.setUserId(userID, "<APP_ID>") // update with your app ID
5
    .then(() => {
6
      setUserIdResult('User ID Set Successfully');
7
    })
8
    .catch((error) => {
9
      setUserIdResult('Failed to Set User ID: ' + error);
10
    });
11
};
12
13
function onUserLoggedOut() {
14
  try {
15
    HumanSecurity.AD.setUserId(null, "<APP_ID>"); // update with your app ID
16
  } catch (error) {
17
    console.log(`Exception: ${error.message}`);
18
  }
19
}

Notify HUMAN’s backend on outgoing URL requests from the app

To let Account Defender protect the user’s account, your app must provide the SDK with outgoing URL requests. This should be done after you set the user ID.

1
import HumanSecurity from "@humansecurity/react-native-sdk";
2
3
...
4
   // In your sendAPIRequest function
5
6
    const headers = await HumanSecurity.BD.headersForURLRequest(appId);
7
8
    // Add this for account defender
9
      HumanSecurity.AD.registerOutgoingUrlRequest(url, appId).catch((error) => {
10
      console.log('Error registering outgoing url request: ', error);
11
    });
12
13
    const response = await fetch(url, {
14
      method: "GET",
15
      headers,
16
    });
17
18
...

You should call the HumanSecurity.AD.registerOutgoingUrlRequest(url: string, appId?: string): Promise<void> function before sending the URL request. If you’re using a custom HttpClient service, add this function to the request interceptor.

Set additional data (optional)

You can set additional data to configure HUMAN’s backend with extra parameters. To do so, call HumanSecurity.AD.setAdditionalData(parameters: { [key: string]: string }, appId?: string): Promise<void> after calling HumanSecurity.startWithAppId(appId: string, policy?: HSPolicy): Promise<void>.

For example:

1
import HumanSecurity from "@humansecurity/react-native-sdk";
2
3
const setAdditionalData = async () => {
4
  const parameters = { key1: 'value1', key2: 'value2' };
5
  HumanSecurity.AD.setAdditionalData(parameters, appId).then(
6
    () => {
7
      setAdditionalDataResult('Additional Data Set Successfully');
8
    },
9
    (error) => {
10
      setAdditionalDataResult('Failed to Set Additional Data' + error);
11
    }
12
  );
13
};

Simulate a challenge

You can simulate a challenge to test the integration. To do so, follow the steps in our help article.