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:

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.
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:

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

📘

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:

maven { url 'https://perimeterx.jfrog.io/artifactory/px-Android-SDK/' }

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:

implementation 'com.perimeterx.sdk:msdk:<Version>'

implementation("com.perimeterx.sdk:msdk:<Version>")

Manual

1. Download the AAR file from https://perimeterx.jfrog.io/ui/repos/tree/General/px-Android-SDK or use the following command line:

curl -LO https://perimeterx.jfrog.io/artifactory/px-Android-SDK/com/perimeterx/sdk/msdk/3.3.3/msdk-3.3.3.aar

2. Put the PerimeterX-release.aar in the libs folder of your app.
3. Add the following dependency to your build.gradle:

implementation files('libs/PerimeterX-release.aar')

4. Add the following dependencies to your build.gradle file (please refer to the relevant SDK version):

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:2.3.4' // min v2.2.1 ; max 2.3.4

🚧

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 <fields>;
}

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:

import com.perimeterx.mobile_sdk.PerimeterX
import com.perimeterx.mobile_sdk.PerimeterXDelegate
import com.perimeterx.mobile_sdk.main.PXPolicy

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).

class MainApplication: Application(), PerimeterXDelegate

class MainApplication extends Application implements PerimeterXDelegate

3. Create and configure the PXPolicy object, in the Application's onCreate function.

val policy = PXPolicy()
// configure the policy instacne

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.

policy.setDomains(arrayListOf("my-domain.com"), "<APP_ID>")

ArrayList<String> domains = new ArrayList<>();
domains.add("my-domain.com");
policy.setDomains(domains, "<APP_ID>");

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.

try {
    PerimeterX.start(this, "<APP_ID>", this, policy)
}
catch (exception: Exception) {
    println("failed to start. error: ${exception.message}")
}

try {
    PerimeterX.INSTANCE.start(this, "<APP_ID>", 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:

private var okHttpClient: OkHttpClient = OkHttpClient.Builder()
    .addInterceptor(MyInterceptor())
    .addInterceptor(PXInterceptor()) // MUST BE THE LAST INTERCEPTOR IN THE CHAIN
    .build()

private final OkHttpClient httpClient = new OkHttpClient.Builder()
    .addInterceptor(new MyInterceptor())
    .addInterceptor(new PXInterceptor()) // MUST BE THE LAST INTERCEPTOR IN THE CHAIN
    .build();

ktor:

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.

try {
   PerimeterX.setCustomParameters(hashMapOf("custom_param1" to "hello", "custom_param2" to "world"))
}
catch (exception: Exception) {
   println("error: ${exception.message}")
}

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
  • How to test your app with the SDK
• Manual integration
  • Understanding the flow
  • Adding SDK's HTTP headers to your URL requests
  • Handle block responses from your server
• Handle block responses from the server
  • How to retry requests that were blocked
  • Checking the error
  • When will you receive those errors
  • How the SDK presents the block page to the user
• React Native support
  • Integration with React Native
• Hybrid App support
  • What is "Hybrid App"
  • How to enable Hybrid App support
• Account Defender
  • How to enable support for Account Defender
• Multiple AppIDs support
  • Integration with multiple AppIDs
• Migrating from earlier SDK versions
  • From v2 to v3
  • From v1 to v2

Looking for earlier SDK version?

• SDK v2 - How to integrate the SDK in your application
• SDK v1 - How to integrate the SDK in your application