Overview

Welcome to HUMAN’s Mobile SDK! Our SDK is a library for both iOS and Android platforms and offers client support for Bot Defender (BD) and Account Defender (AD). This introduction covers various aspects of the SDK, including:

• Core functionalities
• How it operates

By following the best practices outlined here, you can maximize the benefits of our SDK and enhance the user experience of your mobile applications.

How does the SDK work with Bot Defender?

To let your system process your app’s requests, the SDK provides specific HTTP headers, including an encrypted token from our backend, that identifies your application. Your app must add these HTTP headers to all of its requests to your protected domains (i.e. your server behind an Enforcer), especially the X-PX-AUTHORIZATION header. This header contains the encrypted token and, most importantly, signals to our system that the request originates from a mobile app rather than a web browser.

Typically, our system identifies requests originating from your end users and allows them to proceed. Occasionally, however, the system may flag a request as suspicious, believing it to be bot-generated, and subsequently block it. In such cases, our system issues a HUMAN Challenge, which lets genuine users verify their identity. Upon successful completion of the Challenge, a new token is generated. You should then resubmit the request, including the new set of HTTP headers provided by the SDK.

To present the Challenge, simply send the block response to the SDK, which will handle multiple blocked requests simultaneously.

How does the SDK work with Account Defender?

After a user logs into your app, you should provide the SDK with their user ID to enable AD. To ensure account protection, send the request’s URL to the SDK every time your app sends a request to your server. The SDK will then notify our backend about these requests.

The Automatic Interceptor ensures the SDK processes requests automatically, eliminating the need for manual submission.

Terms and concepts

Below are common HUMAN terms and concepts you’ll encounter while integrating the Mobile SDK.

App ID

The App ID is the HUMAN identifier for your application. You may have more than one ID (for example, for development, staging, and production environments) or separate IDs per protected domain.

Always use the correct ID for the environment or domain you are calling.

Domains

Domains refers to the list of domains protected by HUMAN with an Enforcer.

• Format: Use the bare host name; do not include protocol or common prefixes.
  • Correct: example.com, api.example.com
  • Incorrect: http://example.com, https://example.com, www.example.com.
• Subdomains/leading dot: Confirm whether your organization expects a leading dot to cover subdomains (e.g. .example.com) or exact host matching, then align with your Enforcer configuration.
• Coverage: Include all API hosts that should be protected.

SDK HTTP headers

A set of HTTP headers (e.g. X-PX-AUTHORIZATION) that the SDK generates to identify the app and user session to HUMAN. Ask the SDK for headers and attach them to every request sent to a protected domain.

• If headers are missing, the request may be treated as browser traffic and receive a hard block page with no in-app challenge option.
• If headers are stale or incorrect, the system may misclassify legitimate traffic and block it when it’s not needed, increasing friction and false positives.

SDK initialization

• Call the SDK’s start method as early as possible in your app lifecycle so protection is ready immediately.
• Run the SDK’s start on the main thread (mandatory on iOS).
• Initialize once per app launch.

Challenge handling

When a protected request is blocked, the SDK presents a challenge to the user. After the user solves the challenge, the SDK obtains a fresh valid token. Your app can then retry the original request.

Integration modes

There are two ways to integrate the SDK into your networking stack:

1. Manual Integration
   1. Add SDK headers to every request going to a protected domain.
   2. Perform the request normally.
   3. Handle failure. If a request fails, check whether it indicates a block and the SDK can handle it. If yes, call the SDK to handle the response. The SDK will display a challenge to the user.
   4. When the challenge is solved (or canceled), your callback fires. If successful, you can retry the original request using the new HTTP headers provided by the SDK.
2. Interceptor (Automatic). The “Automatic Interceptor” feature streamlines integration and simplifies the workflow. When activated, this feature ensures that all outgoing requests include the necessary HTTP headers. It also handles any blocked responses without requiring modifications to your existing request code. The SDK intercepts outbound requests, adds headers automatically, and displays challenges when needed, and can even retry your original request.
   • Interceptor mode is available for native iOS and Android only. It is not supported for React Native, Expo, Flutter, etc.
     • For Android, the HSInterceptor must be the final item in your HTTP client (OkHTTP)‘s interceptor list.
   • Domain configuration is critical:
     • If domains are configured, only those are intercepted.
     • If domains are not configured, the SDK may intercept all requests and add headers.

Hybrid App solution

A Hybrid App is a mobile app where part of the user journey runs in native screens and part runs inside an in-app WebView. Both the WebView and the native code send API requests to HUMAN-protected domains.

This setup is more common than it seems: many apps use a WebView for login, account, billing, or help pages without calling the app “hybrid,” but those flows are still part of the protected experience and should be included in the Hybrid configuration.

In a Hybrid App, both the native API calls and the WebView traffic are part of the same protected experience and should share the same HUMAN setup (App ID, domains, VID behavior, etc.).

Some common examples are:

• Login or signup flows implemented as a web page shown in a WebView.
• Account pages (profile, settings, billing) opened inside the app but actually rendered as web content.
• Certain flows like multistep forms, verification, or help center pages that are hosted on your website and displayed in a WebView.

In a Hybrid App, both the native API calls and the WebView traffic are part of the same protected experience and should be synced.

What should I keep in mind for the Hybrid App setup?

The VID is a crucial component managed by HUMAN’s backend. It serves to understand client behavior. For optimal protection, it is essential that both native and web sessions share the same VID. This reduces false blocks and ensures a single challenge resolution fixes both WebView and native requests.

To synchronize native and web sessions, follow these steps:

1. Configure Web View Domains:
   • Specify the domain(s) used in your web view.
   • These domains must also be protected by HUMAN and share the same App ID as your native application.
   • You can provide only the root domain; the SDK will automatically handle subdomains.
   • Ensure the domain is set correctly, matching how cookies are configured. It should not include “http” or “www”. For example, for “https://www.example.com”, the domain should be “.example.com”.
2. For further details, refer to the Hybrid App integration guide.

Best practices and troubleshooting

We recommend testing the application with the Doctor app or portal. To ensure a smooth integration and optimal performance, adhere to the following best practices.

Error handling

Implement comprehensive error handling to gracefully manage potential issues during SDK operations.

Common issues

Checklist

• Create App IDs and map them per environment and domain.
• List protected domains with correct formatting
  • Yes: example.com or api.example.com
  • No: https://example.com or www.example.com).
• Start the SDK on the main thread at app launch (iOS only).
• Choose either Manual or Automatic Interceptor mode and configure each appropriately.
• Add the SDK’s HTTP headers all protected‑domain requests.
• Enable Hybrid (WebView) sync when applicable and configure domains for both WebView and native API.

Support and resources

For more information, refer to our detailed integration guide or contact HUMAN Support.