Integration Guide

Introduction

The HUMAN Security SDK continuously profiles and evaluates device behavior to ensure that connections to your mobile APIs and services are genuine.

This complex and detailed process only requires initializing the SDK to manage a set of secure HTTP headers. These headers are added to all HTTP and HTTPS requests made by the mobile application to the origin server and are refreshed regularly by the SDK as it profiles the end-user’s mobile device.

Products

The SDK supports the following products:

• Bot Defender
• Account Defender

Supported Environments

The SDK supports the following environments:

Apple

• iOS: 11 and higher
• iPadOS: 13 and higher
• visionOS: 1 and higher
• Development: Swift 5.5 and higher, Objective-C

Android

• OS: Android 5.0 (API level 21) and higher
• Development: Kotlin 1.6.0 and higher, Java

Other Frameworks

• React Native
• Flutter
• Ionic
• gRPC

SDK v4.1

SDK v4.1 is built with the following environments:

Android

minSdkVersion 21
targetSdkVersion 35

jvmTarget = '1.8'

dependencies {
    implementation 'org.jetbrains.kotlin:kotlin-gradle-plugin:2.1.0'
    implementation 'org.jetbrains.kotlin:kotlin-stdlib:2.1.0'
    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.1'
    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.1'
}

iOS

Swift 5.9.2
iOS 18.2
iPadOS 18.2
visionOS 2.2
Minimum deployments: iOS 12

Demo App

For hands-on experience with the SDK, follow this link to download our demo app.

Software Documentation

The software documentation provides detailed information on every class, function, and member in the SDK. Please choose the relevant SDK version:

Note: For Apple's platforms, follow these steps:

1. Download the source code (zip file).
2. Unzip the file.
3. Open the HUMAN.doccarchive file with Xcode.

What the SDK Does

The SDK integrates support for our products within your app.

Bot Defender

The SDK achieves two objectives to support Bot Defender:

• Provide HTTP Headers: Adds secure headers to your app's URL requests.
• Handle Blocked Requests: Presents a challenge to the user when requests are blocked.

Account Defender

The SDK achieves two objectives to support Account Defender:

• User Login Notification: Notifies HUMAN's backend when a user logs into the app.
• Outgoing Requests Notification: Notifies HUMAN's backend on outgoing URL requests from the app.

Prerequisites

To install the SDK, you need:

• Administrative Access to the HUMAN Portal:
  • Retrieve the HUMAN application ID (AppID).
  • Set the token expiration and validity.
• An Active HUMAN Enforcer

Adding the SDK to Your Project

Methods to Add the SDK

Android

1. Add Permissions

   Add the following permissions to your AndroidManifest.xml file:

   XML

   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
   <uses-permission android:name="android.permission.INTERNET" />
   

2. Add the Library to Your Dependencies

   Add the SDK repository to the repositories section in your project's build.gradle and settings.gradle:

   GroovyKotlin

   buildscript {
       repositories {
           google()
           mavenCentral()
           maven { url 'https://jfrog.humansecurity.com/artifactory/human-android-sdk/' }
       }
   }
   

   buildscript {
       repositories {
           google()
           mavenCentral()
           maven { url = uri("https://jfrog.humansecurity.com/artifactory/human-android-sdk/") }
       }
   }
   

   Add the SDK dependency to the dependencies section in your app's build.gradle:

   GroovyKotlin

   dependencies {
       implementation 'com.humansecurity:sdk:4.1.0'
   }
   

   dependencies {
       implementation("com.humansecurity:sdk:4.1.0")
   }
   

   Alternatively, add the SDK's AAR file manually:

   1. Download the AAR File

      Download the AAR file from this link or use the following command:

      Bash

      curl -LO https://jfrog.humansecurity.com/ui/native/human-android-sdk/com/humansecurity/sdk/4.1.0/sdk-4.1.0.aar
      

   2. Add the AAR to Your Project

      Place the HUMAN-release.aar file in the libs folder of your project.

   3. Add the Local AAR Dependency

      GroovyKotlin

      dependencies {
          implementation files('libs/HUMAN-release.aar')
      }
      

      dependencies {
          implementation(files("libs/HUMAN-release.aar"))
      }
      

   4. Add the SDK's Dependencies

      Add the following dependencies to the dependencies section in your app's build.gradle. Choose the appropriate version based on your project's targetSdkVersion.

      GroovyKotlin

      implementation 'androidx.core:core-ktx:1.15.0' // any version (select 1.10.1 if your app has 'targetSdkVersion 33')
      implementation 'androidx.lifecycle:lifecycle-process:2.8.7' // min v2.6.0 (select 2.6.2 if your app has 'targetSdkVersion 33')
      implementation 'androidx.datastore:datastore-preferences:1.1.1' // any version (select 1.0.0 if your app targets API 33)
      implementation 'com.google.android.material:material:1.12.0' // min v1.6.0 (select 1.9.0 if your app has 'targetSdkVersion 33')
      implementation 'com.fasterxml.uuid:java-uuid-generator:4.3.0' // min v3.0.0
      implementation 'io.ktor:ktor-client-okhttp:3.0.3' // min v3.0.0
      

      implementation("androidx.core:core-ktx:1.15.0") // any version (select 1.10.1 if your app has 'targetSdkVersion 33')
      implementation("androidx.lifecycle:lifecycle-process:2.8.7") // min v2.6.0 (select 2.6.2 if your app has 'targetSdkVersion 33')
      implementation("androidx.datastore:datastore-preferences:1.1.1") // any version (select 1.0.0 if your app targets API 33)
      implementation("com.google.android.material:material:1.12.0") // min v1.6.0 (select 1.9.0 if your app has 'targetSdkVersion 33')
      implementation("com.fasterxml.uuid:java-uuid-generator:4.3.0") // min v3.0.0
      implementation("io.ktor:ktor-client-okhttp:3.0.3") // min v3.0.0
      

3. Issue with R8

   R8 is a tool used to shrink, secure, and optimize Android applications. It can sometimes cause issues with the ktor library included in the SDK. To prevent this, add the following rule to your proguard file:

   proguard

   -keepclassmembers class kotlinx.** {
       volatile <fields>;
   }
   

iOS / iPadOS / visionOS

1. Swift Package Manager

   • Add the Package

     Add the package from the following repository: human-security-ios-sdk

   • Recommended Repository

     We recommend using the human-security-ios-sdk-spm repository. The main git repository is large, and Swift Package Manager downloads the full repository with all git history. This smaller repository contains a pointer to the precompiled XCFramework included in the latest HUMAN SDK release, allowing for quicker downloads.

2. CocoaPods

   • Add the HUMAN Pod

     Add the HUMAN pod to your Podfile:

     Ruby

     platform :ios, '12.0'
     use_frameworks!
     
     target '<Your App Name>' do
         pod 'HUMAN', '4.1.0'
     end
     

3. Add the xcframework File Manually

   1. Download the SDK Repository

      Download the content from the human-security-ios-sdk repository.

   2. Unzip and Add the Framework

      Unzip the file and copy the HUMAN.xcframework to your project.

   3. Integrate in Xcode

      In Xcode, add the xcframework to the "Frameworks, Libraries, and Embedded Content" section of your target.

      

Next Steps

Choose relevant articles based on your environment and requirements:

Native

• Easiest Implementation (Recommended)

  • Fast integration with minimal points.
  • SDK intercepts your URL requests.
  • Handles blocked requests.
  • Not recommended if you need to retry requests after solving challenges.
  • Not recommended if you use advanced URLSession features (authentication challenges, caching, etc.)

• Basic Implementation

  • Few integration points.
  • Handles blocked requests.
  • Notifies when a challenge is solved or cancelled.
    • Great for analytics and logs.
    • Not recommended for retrying requests after challenges.
    • Not recommended as a trigger for resending URL requests.
  • SDK does not intercept URL requests.

• Advanced Functionality

  • Handles blocked requests with challenge results (solved/cancelled).
    • Great for analytics, logs, and resending URL requests.
  • Option to automatically retry blocked requests after challenges.
  • SDK intercepts URL requests.
  • Recommended if you need to retry requests after challenges.
  • Not recommended if you use advanced URLSession features.

• visionOS:

  • Challenge Presentation via Window
  • Challenge Presentation via Sheet

Other Platforms

• Hybrid App

  • Additional integrations for apps using web views to communicate with servers.

• React Native

• Flutter

• Ionic

• gRPC

Multiple App IDs

The SDK supports multiple App IDs, which is useful when your app communicates with multiple servers protected by HUMAN, each having different App IDs.

To support multiple App IDs:

1. Call the HumanSecurity/start(appIds:policy:) function and provide all your App IDs.
2. Pass the relevant App ID to each function that requires the appId parameter. For single AppID apps, the value may be nil or null.

How to Verify the SDK Integration in Your App

Use our integration verification tool to verify the SDK integration in your app.

How to Test the SDK in Your App

Read the test the SDK in your app article to learn how to test SDK integration in your app.