> This page is for Applications Protection. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.humansecurity.com/llms.txt. # 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:** 13 and higher * **iPadOS:** 13 and higher * **visionOS:** 1 and higher * **Development:** Swift 6.0 and higher, Objective-C ### Android * **OS:** Android 6.0 (API level 23) and higher * **Development:** Kotlin 1.6.0 and higher, Java ### Other Frameworks * **React Native** * **Flutter** * **Ionic** * **gRPC** * **Expo** ## SDK v5.0 (iOS) SDK v5.0 is built with the following environments: ```swift Swift 6.1.0 iOS 26.0 iPadOS 26.0 visionOS 26.0 Minimum deployments: iOS 13 ``` ### Android ```groovy minSdkVersion 23 targetSdkVersion 36 jvmTarget = '1.8' dependencies { implementation 'org.jetbrains.kotlin:kotlin-gradle-plugin:2.3.21' implementation 'org.jetbrains.kotlin:kotlin-stdlib:2.3.21' implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2' implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2' } ``` ## Demo App For hands-on experience with the SDK, follow this [link](https://github.com/PerimeterX/px-mobile-sdk-demo-app) 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: | Android | iOS / iPadOS / visionOS | | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | [5.0.0](https://mobile-docs.perimeterx.com/human-android-sdk/v5.0.0/index.html) | [5.0.0](https://github.com/PerimeterX/human-security-ios-sdk/releases/tag/5.0.0) | | [5.0.1](https://mobile-docs.perimeterx.com/human-android-sdk/v5.0.1/index.html) | | | [5.1.0](https://mobile-docs.perimeterx.com/human-android-sdk/v5.1.0/index.html) | [5.1.0](https://github.com/PerimeterX/human-security-ios-sdk/releases/tag/5.1.0) | | [5.2.0](https://mobile-docs.perimeterx.com/human-android-sdk/v5.2.0/index.html) | [5.2.0](https://github.com/PerimeterX/human-security-ios-sdk/releases/tag/5.2.0) | | [5.3.0](https://mobile-docs.perimeterx.com/human-android-sdk/v5.3.0/index.html) | [5.3.0](https://github.com/PerimeterX/human-security-ios-sdk/releases/tag/5.3.0) | | | [5.3.1](https://github.com/PerimeterX/human-security-ios-sdk/releases/tag/5.3.1) | | [5.3.1](https://mobile-docs.perimeterx.com/human-android-sdk/v5.3.1/index.html) | [5.3.1](https://github.com/PerimeterX/human-security-ios-sdk/releases/tag/5.3.1) | | [5.3.2](https://mobile-docs.perimeterx.com/human-android-sdk/v5.3.2/index.html) | [5.3.2](https://github.com/PerimeterX/human-security-ios-sdk/releases/tag/5.3.2) | | [5.3.3](https://mobile-docs.perimeterx.com/human-android-sdk/v5.3.3/index.html) | | **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 ``` 2. **Add the Library to Your Dependencies** **Add the SDK repository to the repositories section in your project's `build.gradle` and `settings.gradle`:** ```groovy buildscript { repositories { google() mavenCentral() maven { url 'https://jfrog.humansecurity.com/artifactory/human-android-sdk/' } } } ``` ```kotlin 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`:** ```groovy dependencies { implementation 'com.humansecurity:sdk:5.3.3' } ``` ```kotlin dependencies { implementation("com.humansecurity:sdk:5.3.3") } ``` **Alternatively, add the SDK's AAR file manually:** 1. **Download the AAR File** Download the AAR file from this [link](https://jfrog.humansecurity.com/ui/native/human-android-sdk/com/humansecurity/sdk/5.3.3) or use the following command: ```bash curl -LO https://jfrog.humansecurity.com/ui/native/human-android-sdk/com/humansecurity/sdk/5.3.3/sdk-5.3.3.aar ``` 2. **Add the AAR to Your Project** Rename the downloaded file to `HUMAN-release.aar` and place it in the `libs` folder of your project. 3. **Add the Local AAR Dependency** ```groovy dependencies { implementation files('libs/HUMAN-release.aar') } ``` ```kotlin 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`. ```groovy implementation 'androidx.core:core-ktx:1.19.0' // any version (select 1.10.1 if your app has 'targetSdkVersion 33') implementation 'androidx.lifecycle:lifecycle-process:2.11.0' // min v2.6.0 (select 2.6.2 if your app has 'targetSdkVersion 33') implementation 'androidx.datastore:datastore-preferences:1.2.1' // any version (select 1.0.0 if your app targets API 33) implementation 'com.google.android.material:material:1.14.0' // min v1.10.0 (select 1.9.0 if your app has 'targetSdkVersion 33') implementation 'com.fasterxml.uuid:java-uuid-generator:5.2.0' // min v3.0.0 implementation 'io.ktor:ktor-client-okhttp:3.5.1' // min v3.0.0 ``` ```kotlin implementation("androidx.core:core-ktx:1.19.0") // any version (select 1.10.1 if your app has 'targetSdkVersion 33') implementation("androidx.lifecycle:lifecycle-process:2.11.0") // min v2.6.0 (select 2.6.2 if your app has 'targetSdkVersion 33') implementation("androidx.datastore:datastore-preferences:1.2.1") // any version (select 1.0.0 if your app targets API 33) implementation("com.google.android.material:material:1.14.0") // min v1.10.0 (select 1.9.0 if your app has 'targetSdkVersion 33') implementation("com.fasterxml.uuid:java-uuid-generator:5.2.0") // min v3.0.0 implementation("io.ktor:ktor-client-okhttp:3.5.1") // min v3.0.0 ``` The following dependencies are required only if you integrate the HUMAN Doctor App: ```groovy implementation platform('androidx.compose:compose-bom:2026.06.00') implementation 'androidx.compose.ui:ui' implementation 'androidx.compose.material3:material3' implementation 'androidx.compose.material:material-icons-extended' implementation 'androidx.compose.foundation:foundation' implementation 'androidx.activity:activity-compose:1.13.0' implementation 'androidx.lifecycle:lifecycle-runtime-compose:2.11.0' ``` ```kotlin implementation(platform("androidx.compose:compose-bom:2026.06.00")) implementation("androidx.compose.ui:ui") implementation("androidx.compose.material3:material3") implementation("androidx.compose.material:material-icons-extended") implementation("androidx.compose.foundation:foundation") implementation("androidx.activity:activity-compose:1.13.0") implementation("androidx.lifecycle:lifecycle-runtime-compose:2.11.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 ; } ``` #### iOS / iPadOS / visionOS 1. **Swift Package Manager** * **Add the Package** Add the package from the following repository: [human-security-ios-sdk](https://github.com/PerimeterX/human-security-ios-sdk) * **Recommended Repository** We recommend using the [human-security-ios-sdk-spm](https://github.com/PerimeterX/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](https://cocoapods.org/pods/HUMAN) to your `Podfile`: ```ruby platform :ios, '13.0' use_frameworks! target '' do pod 'HUMAN', '5.3.2' end ``` 3. **Add the `xcframework` File Manually** 1. **Download the SDK Repository** Download the content from the [human-security-ios-sdk](https://github.com/PerimeterX/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](https://docs.humansecurity.com/applications-and-accounts/docs/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](https://docs.humansecurity.com/applications-and-accounts/docs/native-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](https://docs.humansecurity.com/applications-and-accounts/docs/native-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](https://docs.humansecurity.com/applications-and-accounts/docs/visionos-integration-window)** * **[Challenge Presentation via Sheet](https://docs.humansecurity.com/applications-and-accounts/docs/visionos-integration-sheet)** ### Other Platforms * **[Hybrid App](https://docs.humansecurity.com/applications/react-native-integration-recommended)** * Additional integrations for apps using web views to communicate with servers. * **[React Native](https://docs.humansecurity.com/applications/react-native-integration-recommended)** * **[Flutter](https://docs.humansecurity.com/applications-and-accounts/docs/flutter-integration)** * **[Ionic](https://docs.humansecurity.com/applications-and-accounts/docs/ionic-integration)** * **[gRPC](https://docs.humansecurity.com/applications-and-accounts/docs/grpc-integration)** * **[Expo](https://docs.humansecurity.com/applications-and-accounts/docs/expo-integration)** ## 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](https://docs.humansecurity.com/applications-and-accounts/docs/how-to-verify-the-sdk-integration-in-your-app) to verify the SDK integration in your app. ## How to Test the SDK in Your App Read the [test the SDK in your app](https://docs.humansecurity.com/applications-and-accounts/docs/how-to-test-the-sdk-in-your-app) article to learn how to test SDK integration in your app.