How to integrate the SDK in your application
  • 26 Sep 2023
  • Dark

How to integrate the SDK in your application

  • Dark

Article Summary


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.


The following are required to install the SDK:

  1. Administrative access to the PerimeterX Portal to:
    1. Retrieve the PerimeterX application ID (AppID).
    2. Set the token expiration and validity.
  2. An active PerimeterX 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 PerimeterX SDK to your project

You can add the SDK to your project with one of the following options:


  1. Add the following repository to your build.gradle and settings.gradle:
maven { url '' }
maven { url = uri("") }
  1. Add the following dependency to your build.gradle and set the PerimeterX Android SDK version:
implementation 'com.perimeterx.sdk:msdk:<Version>'


  1. Download the AAR file from or use the following command line:
curl -LO
  1. Put the PerimeterX-release.aar in the libs folder of your app.
  2. Add the following dependency to your build.gradle:
implementation files('libs/PerimeterX-release.aar')
  1. Add the following dependencies to your build.gradle file (please refer to the relevant SDK version):
implementation ''
implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
implementation ''
implementation ''
implementation 'io.ktor:ktor-client-core:2.2.4'
implementation 'io.ktor:ktor-client-okhttp:2.2.4'
implementation 'com.fasterxml.uuid:java-uuid-generator:4.0.1'

From v3.1, you should also add the followingdependencies:

implementation "androidx.datastore:datastore-preferences:1.0.0"
  1. The SDK depends on few AndroidX libraries. If your project does not includes AndroidX, you should add the following dependencies:
implementation 'androidx.lifecycle:lifecycle-common-java8:2.5.1'
implementation 'androidx.lifecycle:lifecycle-extensions:2.2.0'
  1. The "Doctor App" feature requires the AndroidX's fragment library. If your project does not includes AndroidX, you should add the following dependency:
implementation 'androidx.fragment:fragment:1.5.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;
  1. Make your Application class to implement the PerimeterXDelegate (optional).
class MainApplication: Application(), PerimeterXDelegate
class MainApplication extends Application implements PerimeterXDelegate
  1. 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
  1. 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(""), "<APP_ID>")
ArrayList<String> domains = new ArrayList<>();
policy.setDomains(domains, "<APP_ID>");
  1. Call the PerimeterX/start(application:appId:delegate:policy:) function, with your application, AppID and the policy, in the Application's onCreate function.
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());  
  1. Add the PerimeterX's interceptor (PXInterceptor) to your HttpClient's application interceptors list at the end. This is required for the "Automatic Interception".


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


private val httpClient: HttpClient = HttpClient(OkHttp) {  
    engine {  
        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());


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:

Looking for earlier SDK version?

Was this article helpful?