What is a Hybrid App

A Hybrid App uses both native URL requests and web views to communicate with your server. In the context of HUMAN, it’s crucial to ensure that both native requests and web views are synchronized to provide the expected behavior for end users.

How Do I Know if My App is a Hybrid App

Your app is considered a Hybrid App if it has ALL of the following:

1. A web view component (WKWebView on iOS or WebView on Android) that loads your website.
2. Your website is protected by HUMAN (Bot Defender or Account Defender).

On iOS, if your app uses SFSafariViewController, please let us know, and we will guide you through a specific integration.

How to Enable Hybrid App Support in My App

Integrate the SDK (Native)

You should integrate the SDK into your native app. You may choose one of the following methods:

1. Easiest Implementation
2. Basic Implementation
3. Advanced Functionality

Enable Hybrid App Support

When starting the SDK, declare your website’s root domain in the policy. This value is used both to decide which WebViews get hybrid support and as the Domain when the SDK sets hybrid cookies (_pxmd, _pxwvm).

Set the same cookie domain your Sensor uses on the website. In browser DevTools, Sensor cookies usually appear with a domain like .example.com for https://www.example.com. Use that root domain in webRootDomains — no scheme and no www prefix.

The SDK enables Hybrid App support ONLY for the specified domains. It matches the WebView host against that root and its subdomains. For example, .example.com covers example.com, www.example.com, and api.example.com.

You should pass the WebView instance to the SDK using the following functions:

• iOS: HumanSecurity.setupWebView(webView:navigationDelegate:)
• Android: HumanSecurity.setupWebView(webView:webViewClient:)

Important: Do not set the navigationDelegate (iOS) or webViewClient (Android) properties after calling the setupWebView function.

On iOS, you can enable automatic detection and setup of WKWebViews by setting HSHybridAppPolicy.automaticSetup to true. This eliminates the need to manually call setupWebView for each instance.

Example Implementation

Android

Kotlin:

1
import android.app.Application
2
import com.humansecurity.mobile_sdk.HumanSecurity
3
import com.humansecurity.mobile_sdk.main.policy.HSPolicy
4
5
class MainApplication : Application() {
6
7
    override fun onCreate() {
8
        super.onCreate()
9
        startHumanSDK()
10
    }
11
12
    private fun startHumanSDK() {
13
        try {
14
            val policy = HSPolicy().apply {
15
                // Configure the policy...
16
                automaticInterceptorPolicy.interceptorType = HSAutomaticInterceptorType.INTERCEPT_WITH_DELAYED_RESPONSE // or INTERCEPT_AND_RETRY_REQUEST
17
                hybridAppPolicy.setWebRootDomains(setOf(".example.com"), "<APP_ID>")
18
            }
19
20
            HumanSecurity.start(this, "<APP_ID>", policy)
21
        } catch (exception: Exception) {
22
            println("Exception: ${exception.message}")
23
        }
24
    }
25
}

Java:

1
import android.app.Application;
2
import android.util.Log;
3
import java.util.HashSet;
4
import com.humansecurity.mobile_sdk.HumanSecurity;
5
import com.humansecurity.mobile_sdk.main.policy.HSPolicy;
6
import com.humansecurity.mobile_sdk.main.policy.HSAutomaticInterceptorType;
7
8
public class MainApplication extends Application {
9
10
    @Override
11
    public void onCreate() {
12
        super.onCreate();
13
        startHumanSDK();
14
    }
15
16
    void startHumanSDK() {
17
        try {
18
            HSPolicy policy = new HSPolicy();
19
            // Configure the policy...
20
            policy.getAutomaticInterceptorPolicy().setInterceptorType(HSAutomaticInterceptorType.INTERCEPT_WITH_DELAYED_RESPONSE); // or INTERCEPT_AND_RETRY_REQUEST
21
22
            HashSet<String> domains = new HashSet<>();
23
            domains.add(".example.com");
24
            policy.getHybridAppPolicy().setWebRootDomains(domains, "<APP_ID>");
25
26
            HumanSecurity.INSTANCE.start(this, "<APP_ID>", policy);
27
        } catch (Exception exception) {
28
            Log.e("MainApplication", "Exception: " + exception.getMessage());
29
        }
30
    }
31
}

Kotlin (Activity):

1
import androidx.appcompat.app.AppCompatActivity
2
import android.os.Bundle
3
import android.webkit.WebView
4
import com.humansecurity.mobile_sdk.HumanSecurity
5
6
class MainActivity : AppCompatActivity() {
7
8
    override fun onCreate(savedInstanceState: Bundle?) {
9
        super.onCreate(savedInstanceState)
10
        setContentView(R.layout.activity_main)
11
12
        val webView = findViewById<WebView>(R.id.web_view)
13
        val webViewClient = MyWebViewClient()
14
        HumanSecurity.setupWebView(webView, webViewClient)
15
16
        // Load your website in the web view...
17
    }
18
}

Java (Activity):

1
import androidx.appcompat.app.AppCompatActivity;
2
import android.os.Bundle;
3
import android.webkit.WebView;
4
import android.webkit.WebViewClient;
5
import com.humansecurity.mobile_sdk.HumanSecurity;
6
7
public class MainActivity extends AppCompatActivity {
8
9
    @Override
10
    protected void onCreate(Bundle savedInstanceState) {
11
        super.onCreate(savedInstanceState);
12
        setContentView(R.layout.activity_main);
13
14
        WebView webView = findViewById(R.id.web_view);
15
        MyWebViewClient webViewClient = new MyWebViewClient();
16
        HumanSecurity.INSTANCE.setupWebView(webView, webViewClient);
17
18
        // Load your website in the web view...
19
    }
20
}

iOS

Swift:

1
import UIKit
2
import HUMAN
3
4
@main
5
class AppDelegate: UIResponder, UIApplicationDelegate {
6
7
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
8
        startHumanSDK()
9
        return true
10
    }
11
12
    func startHumanSDK() {
13
        do {
14
            let policy = HSPolicy()
15
            // Configure the policy...
16
            policy.hybridAppPolicy.set(webRootDomains: [".example.com"], forAppId: "<APP_ID>")
17
            HSAutomaticInterceptorPolicy.urlSessionRequestTimeout = 10 // Set the timeout you would like for your requests.
18
19
            try HumanSecurity.start(appId: "<APP_ID>", policy: policy)
20
        } catch {
21
            print("Error: \(error)")
22
        }
23
    }
24
}

Objective-C:

1
@import HUMAN;
2
3
@implementation AppDelegate
4
5
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
6
    [self startHumanSDK];
7
    return YES;
8
}
9
10
- (void)startHumanSDK {
11
    HSPolicy *policy = [[HSPolicy alloc] init];
12
    // Configure the policy...
13
    [policy.hybridAppPolicy setWithWebRootDomains:[NSSet setWithObject:@".example.com"] forAppId:@"<APP_ID>"];
14
    HSAutomaticInterceptorPolicy.urlSessionRequestTimeout = 10; // Set the timeout you would like for your requests.
15
16
    NSError *error = nil;
17
    [HumanSecurity startWithAppId:@"<APP_ID>" policy:policy error:&error];
18
    if (error != nil) {
19
        NSLog(@"Error: %@", error);
20
    }
21
}
22
23
@end

Explanation of the Code

1. Adding Web Root Domains:
   • Set your website’s root cookie domain (e.g., .example.com) in the policy’s webRootDomains. Confirm the value matches the Sensor cookie Domain in DevTools. Do not use www.example.com or https://….
2. Starting the SDK:
   • Initialize the SDK as early as possible on the main thread to ensure all URL requests include the necessary HTTP headers.
3. Setting Up Web Views:
   • Android: Use HumanSecurity.setupWebView(webView:webViewClient:) to set up the WebView with the SDK’s WebViewClient. Do not set the WebViewClient directly after this.
   • iOS: Use HumanSecurity.setupWebView(webView:navigationDelegate:) to set up the WKWebView with the SDK’s navigationDelegate. Do not set the navigationDelegate directly after this.

Notes:

• iOS Automatic Setup: If you enable HSHybridAppPolicy.automaticSetup, the SDK will automatically detect and set up all WKWebView instances without needing to call setupWebView for each one.
• Multiple AppIDs: If your app communicates with multiple servers having different AppIDs, use the HumanSecurity.start(appIds:policy:) function to pass an array of AppIDs and specify the relevant AppID for each API call.

Apple Pay on the Web

If your website uses Apple Pay on the Web, you should disable JavaScript evaluation by the SDK. To protect the security of Apple Pay transactions in WKWebView, Apple Pay cannot be used alongside script injection APIs (relevant for iOS 13-15). Disable JavaScript evaluation by setting the SDK’s policy accordingly.

Note: If your app targets only iOS 16 or above, you don’t need to disable JavaScript evaluation by the SDK.

Swift:

1
policy.hybridAppPolicy.allowJavaScriptEvaluation = false

Objective-C:

1
policy.hybridAppPolicy.allowJavaScriptEvaluation = NO;

External Web Views (Available from v4.0.1)

If your app uses web views that are created outside the native side of the app but are still based on Apple’s WKWebView or Android’s WebView (e.g., react-native-webview), you should enable support for them in the SDK’s policy.

Android

Kotlin:

1
policy.hybridAppPolicy.supportExternalWebViews = true

Java:

1
policy.getHybridAppPolicy().setSupportExternalWebViews(true);

iOS

Swift:

1
policy.hybridAppPolicy.supportExternalWebViews = true

Objective-C:

1
policy.hybridAppPolicy.supportExternalWebViews = YES;