> 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. # How to integrate the SDK in your application #### v3 ## Introducing the software documentation and the demo app! The software documentation provides elaborated information on every class, function and member in the SDK. Please choose the relevant SDK version: \| [v3.4.10](https://mobile-docs.perimeterx.com/px-android-sdk/v3.4.10/index.html) | [v3.4.9](https://mobile-docs.perimeterx.com/px-android-sdk/v3.4.9/index.html) | [v3.4.8](https://mobile-docs.perimeterx.com/px-android-sdk/v3.4.8/index.html) | [v3.4.7](https://mobile-docs.perimeterx.com/px-android-sdk/v3.4.7/index.html) | [v3.4.6](https://mobile-docs.perimeterx.com/px-android-sdk/v3.4.6/index.html) | [v3.4.5](https://mobile-docs.perimeterx.com/px-android-sdk/v3.4.5/index.html) | [v3.4.4](https://mobile-docs.perimeterx.com/px-android-sdk/v3.4.4/index.html) | [v3.4.3](https://mobile-docs.perimeterx.com/px-android-sdk/v3.4.3/index.html) | [v3.4.2](https://mobile-docs.perimeterx.com/px-android-sdk/v3.4.2/index.html) | [v3.4.1](https://mobile-docs.perimeterx.com/px-android-sdk/v3.4.1/index.html) | [v3.4.0](https://mobile-docs.perimeterx.com/px-android-sdk/v3.4.0/index.html) | [v3.3.6](https://mobile-docs.perimeterx.com/px-android-sdk/v3.3.6/index.html) | [v3.3.5](https://mobile-docs.perimeterx.com/px-android-sdk/v3.3.5/index.html) | [v3.3.4](https://mobile-docs.perimeterx.com/px-android-sdk/v3.3.4/index.html) | [v3.3.3](https://mobile-docs.perimeterx.com/px-android-sdk/v3.3.3/index.html) | [v3.3.2](https://mobile-docs.perimeterx.com/px-android-sdk/v3.3.2/index.html) | [v3.3.1](https://mobile-docs.perimeterx.com/px-android-sdk/v3.3.1/index.html) | [v3.3.0](https://mobile-docs.perimeterx.com/px-android-sdk/v3.3.0/index.html) | [v3.2.1](https://mobile-docs.perimeterx.com/px-android-sdk/v3.2.1/index.html) | [v3.2.0](https://mobile-docs.perimeterx.com/px-android-sdk/v3.2.0/index.html) | [v3.1.8](https://mobile-docs.perimeterx.com/px-android-sdk/v3.1.8/index.html) | [v3.1.7](https://mobile-docs.perimeterx.com/px-android-sdk/v3.1.7/index.html) | [v3.1.6](https://mobile-docs.perimeterx.com/px-android-sdk/v3.1.6/index.html) | [v3.1.5](https://mobile-docs.perimeterx.com/px-android-sdk/v3.1.5/index.html) | [v3.1.4](https://mobile-docs.perimeterx.com/px-android-sdk/v3.1.4/index.html) | [v3.1.3](https://mobile-docs.perimeterx.com/px-android-sdk/v3.1.3/index.html) | [v3.1.2](https://mobile-docs.perimeterx.com/px-android-sdk/v3.1.2/index.html) | [v3.1.1](https://mobile-docs.perimeterx.com/px-android-sdk/v3.1.1/index.html) | [v3.1.0](https://mobile-docs.perimeterx.com/px-android-sdk/v3.1.0/index.html) | [v3.0.6](https://mobile-docs.perimeterx.com/px-android-sdk/v3.0.6/index.html) | [v3.0.5](https://mobile-docs.perimeterx.com/px-android-sdk/v3.0.5/index.html) | [v3.0.4](https://mobile-docs.perimeterx.com/px-android-sdk/v3.0.4/index.html) | [v3.0.3](https://mobile-docs.perimeterx.com/px-android-sdk/v3.0.3/index.html) | [v3.0.2](https://mobile-docs.perimeterx.com/px-android-sdk/v3.0.2/index.html) | [v3.0.1](https://mobile-docs.perimeterx.com/px-android-sdk/v3.0.1/index.html) | [v3.0.0](https://mobile-docs.perimeterx.com/px-android-sdk/v3.0.0/index.html) | The demo app gives you a general idea on how you should implement the SDK in you app. To download, please follow those steps: 1. Open the [demo app repo](https://github.com/PerimeterX/px-mobile-sdk-demo-app). 2. Download the content of the repo. 3. Unzip the file and open the Android demo app. ## Prerequisites The following are required to install the SDK: 1. Administrative access to the HUMAN Portal to: 1. Retrieve the HUMAN application ID (AppID). 2. Set the token expiration and validity. 2. An active HUMAN Enforcer. ## Permissions and dependencies Add the following permissions to your AndroidManifest.xml file: ```markup ``` > 📘 Dependencies are added automatically > > Dependencies don't have to be added when adding the SDK via JFrog. However, they are still needed when you add the SDK manually. > 🚧 Update your OkHttp library to v4 > > If your app is using OkHttp v3, there will be a conflict that could cause unexpected errors in runtime. Notice that you should update both \`okhttp\` and \`logging-interceptor\` libraries. ## Adding HUMAN SDK to your project You can add the SDK to your project with one of the following options: **JFrog** 1. Add the following repository to your `build.gradle` and `settings.gradle`: ```groovy maven { url 'https://perimeterx.jfrog.io/artifactory/px-Android-SDK/' } ``` ```kotlin maven { url = uri("https://perimeterx.jfrog.io/artifactory/px-Android-SDK/") } ``` 2. Add the following dependency to your `build.gradle` and set the HUMAN Android SDK version: ```groovy implementation 'com.perimeterx.sdk:msdk:' ``` ```kotlin implementation("com.perimeterx.sdk:msdk:") ``` **Manual** 1. Download the AAR file from [https://perimeterx.jfrog.io/ui/repos/tree/General/px-Android-SDK](https://perimeterx.jfrog.io/ui/repos/tree/General/px-Android-SDK/com/perimeterx/sdk/msdk/3.4.10) or use the following command line: ```none curl -LO https://perimeterx.jfrog.io/artifactory/px-Android-SDK/com/perimeterx/sdk/msdk/3.4.10/msdk-3.4.10.aar ``` 2. Put the `PerimeterX-release.aar` in the libs folder of your app. 3. Add the following dependency to your `build.gradle`: ```groovy implementation files('libs/PerimeterX-release.aar') ``` 4. Add the following dependencies to your `build.gradle` file (please refer to the relevant SDK version): ```groovy implementation 'androidx.core:core-ktx:1.10.1' // max v1.10.1 implementation 'androidx.appcompat:appcompat:1.6.1' // min v1.0.0 implementation 'androidx.constraintlayout:constraintlayout:2.1.4' // min v2.0.0 implementation 'androidx.lifecycle:lifecycle-process:2.6.2' // min v2.6.0 implementation 'androidx.datastore:datastore-preferences:1.0.0' // exact v1.0.0 implementation 'com.google.android.material:material:1.9.0' // min v1.6.0 ; max v1.9.0 implementation 'com.google.android.gms:play-services-instantapps:18.0.1' // min v11.0.0 implementation 'com.fasterxml.uuid:java-uuid-generator:4.3.0' // min v3.0.0 implementation 'io.ktor:ktor-client-okhttp:3.0.1' // min v3.0.0 ``` > 🚧 Issue with R8 > > R8 is a tool that is used to shrink, secure, and optimize Android applications.\ > When using this tool it could sometimes cause an issue with ktor library which included in the SDK.\ > To prevent this issue, we recommend addting the following rule in your proguard file: > > ``` > -keepclassmembers class kotlinx.** { > volatile ; > } > ``` ## How to start the SDK Starting the SDK should be the first thing that runs in your app. Therefore, you should start it in your `Application` class: 1. Import the SDK: ```kotlin import com.perimeterx.mobile_sdk.PerimeterX import com.perimeterx.mobile_sdk.PerimeterXDelegate import com.perimeterx.mobile_sdk.main.PXPolicy ``` ```java import com.perimeterx.mobile_sdk.PerimeterX; import com.perimeterx.mobile_sdk.PerimeterXDelegate; import com.perimeterx.mobile_sdk.main.PXPolicy; ``` 2. Make your `Application` class to implement the `PerimeterXDelegate` (optional). ```kotlin class MainApplication: Application(), PerimeterXDelegate ``` ```java class MainApplication extends Application implements PerimeterXDelegate ``` 3. Create and configure the `PXPolicy` object, in the `Application`'s `onCreate` function. ```kotlin val policy = PXPolicy() // configure the policy instacne ``` ```java PXPolicy nativePolicy = new PXPolicy(); // configure the policy instacne ``` 4. It's recommended to tell the SDK which domains it should intercept. Not setting domains will cause the SDK to intercept URL requests from ALL domains, including 3rd party libraries. ```kotlin policy.setDomains(arrayListOf("my-domain.com"), "") ``` ```java ArrayList domains = new ArrayList<>(); domains.add("my-domain.com"); policy.setDomains(domains, ""); ``` 5. Call the `PerimeterX/start(application:appId:delegate:policy:)` function, with your application, AppID and the policy, in the `Application`'s `onCreate` function. This function should be called only once. ```kotlin try { PerimeterX.start(this, "", this, policy) } catch (exception: Exception) { println("failed to start. error: ${exception.message}") } ``` ```java try { PerimeterX.INSTANCE.start(this, "", this, policy); } catch (Exception exception) { Log.e("tag","failed to start. error: " + exception.getMessage()); } ``` 6. Add the HUMAN's interceptor (`PXInterceptor`) to your `HttpClient`'s **application interceptors** list **at the end**. This is required for the "Automatic Interception". OkHttp: ```kotlin private var okHttpClient: OkHttpClient = OkHttpClient.Builder() .addInterceptor(MyInterceptor()) .addInterceptor(PXInterceptor()) // MUST BE THE LAST INTERCEPTOR IN THE CHAIN .build() ``` ```java private final OkHttpClient httpClient = new OkHttpClient.Builder() .addInterceptor(new MyInterceptor()) .addInterceptor(new PXInterceptor()) // MUST BE THE LAST INTERCEPTOR IN THE CHAIN .build(); ``` ktor: ```kotlin private val httpClient: HttpClient = HttpClient(OkHttp) { engine { addInterceptor(MyInterceptor()) addInterceptor(PXInterceptor()) // MUST BE THE LAST INTERCEPTOR IN THE CHAIN } } ``` ### What happens when you start the SDK The `PerimeterX/start(appId:delegate:policy:)` function set up the session for a given AppID. It's essential to call this function as early as possible in your application and before any URL request to your server. ## Adding custom parameters You may add custom parameters for additional configuration. ```kotlin try { PerimeterX.setCustomParameters(hashMapOf("custom_param1" to "hello", "custom_param2" to "world")) } catch (exception: Exception) { println("error: ${exception.message}") } ``` ```java try { PerimeterX.INSTANCE.setCustomParameters(customParameters, null); } catch (exception: Exception) { Log.e("tag","failed to set custom parameters. error: " + exception.getMessage()); } ``` ## Summary After writing the code above, the SDK will: 1. Intercept your URL requests. 2. Add SDK's HTTP headers to those URL requests. 3. Handle block responses from the server by presenting a challenge to the user. ## Next steps Review the following topics: * **Integration verification and testing** * [How to verify the integration](/applications/android-how-to-verify-the-integration-in-your-app-with-the-sdk-v3) * [How to test your app with the SDK](/applications/android-how-to-test-you-app-with-the-sdk) * **Manual integration** * [Understanding the flow](/applications/android-manual-integration-v3#understanding-the-flow) * [Adding SDK's HTTP headers to your URL requests](/applications/android-manual-integration-v3#adding-sdks-http-headers-to-your-url-requests) * [Handle block responses from your server](/applications/android-manual-integration-v3#handle-block-responses-from-your-server) * **Handle block responses from the server** * [How to retry requests that were blocked](/applications/android-how-to-retry-requests-that-were-blocked-v3) * [Checking the error](/applications/android-handle-block-responses-from-the-server-v3#checking-the-error) * [When will you receive those errors](/applications/android-handle-block-responses-from-the-server-v3#when-will-you-receive-those-errors) * [How the SDK presents the block page to the user](/applications/android-handle-block-responses-from-the-server-v3#how-the-sdk-presents-the-block-page-to-the-user) * **React Native support** * [Integration with React Native](/applications/android-integration-with-react-native-v3) * **Hybrid App support** * [What is "Hybrid App"](/applications/android-hybrid-app-support-v3#what-is-hybrid-app) * [How to enable Hybrid App support](/applications/android-hybrid-app-support-v3#how-to-enable-hybrid-app-support) * **Account Defender** * [How to enable support for Account Defender](/applications/android-enable-support-for-account-defender-v3) * **Multiple AppIDs support** * [Integration with multiple AppIDs](/applications/android-multiple-appids-support-v3) * **Migrating from earlier SDK versions** * [From v2 to v3](/applications/android-migrating-sdk-from-v2-to-v3) * [From v1 to v2](/applications/android-migrating-sdk-from-v1-to-v2) ### Looking for earlier SDK version?[](/applications/android-how-to-integrate-the-sdk-in-your-application-v3#looking-for-earlier-sdk-version) * [SDK v2 - How to integrate the SDK in your application](/applications/android-how-to-integrate-the-sdk-in-your-application-v2) * [SDK v1 - How to integrate the SDK in your application](/applications/android-how-to-integrate-the-sdk-in-your-application-v1)