Installing the SDK

Prerequisites

The following are required to install the PerimeterX Android 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.

Integration

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" />

Add the following dependencies to your build.gradle file:

implementation 'com.google.android.material:material:1.4.0'  
implementation 'com.google.android.gms:play-services-instantapps:18.0.0'
implementation 'io.ktor:ktor-client-okhttp:1.6.7'

Integrating via JFrog

Add the following repository to your build.gradle and settings.gradle:

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

Add the following dependency to your build.gradle and set the PerimeterX Android SDK version:

implementation 'com.perimeterx.sdk:msdk:[PERIMETERX_ANDROID_SDK_VERSION]'

Integrating Manually

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

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

Implementation

In your Application's onCreate:

  1. Import the SDK.
import com.perimeterx.mobile_sdk.PerimeterX
import com.perimeterx.mobile_sdk.PerimeterXDelegate
import com.perimeterx.mobile_sdk.PerimeterX
import com.perimeterx.mobile_sdk.PerimeterXDelegate
  1. Make the Application class to implement the PerimeterXDelegate.
class MainApplication: Application(), PerimeterXDelegate
class MainApplication extends Application implements PerimeterXDelegate
  1. Verify the SDK's version.
println("SDK version: ${PerimeterX.INSTANCE.sdkVersion()}")
System.out.println("SDK version: " + PerimeterX.INSTANCE.sdkVersion());
  1. Call the PerimeterX's start function with your AppID.
PerimeterX.start(this, "<APP_ID>", this, false) { success ->  
  if (success) {  
  PerimeterX.vid(appId)?.let { vid ->  
    println("PerimeterX is ready (vid = ${vid})")  
                              }   
  else {  
    // make sure to start the sdk again when it fails (network issue, etc.)  
  }
}
PerimeterX.INSTANCE.start(this, "<APP_ID>", this, false, success -> {  
  if (success) {  
    String vid = PerimeterX.INSTANCE.vid(appId);  
    if (vid != null) {  
      System.out.println("PerimeterX is ready (vid = " + vid + ")");  
    }
  }
  else {  
    // make sure to start the sdk again when it fails (network issue, etc.)
  }
  return null;  
});
  1. Add the PerimeterX's interceptor (PXInterceptor) to your HttpClient's interceptors list at the end. This is required for the automatic interception.
1. OkHttp:
private var okHttpClient: OkHttpClient = OkHttpClient.Builder()  
  .addInterceptor(MyInterceptor())  
  .addInterceptor(PXInterceptor()) // MUST BE THE LAST INTERCEPTOR IN THE CHAIN  
  .build()

2. ktor:
private val httpClient: HttpClient = HttpClient(OkHttp) {  
  engine {  
    addInterceptor(MyInterceptor())  
      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  
  .build();
  1. That's it! 🎉

Enable manual interception

The SDK automatically intercepts HTTP requests and adds relevant HTTP headers. However, you can disable this and add those HTTP headers manually.

  1. After calling the start function, disable the automatic interception in the policy.
val policy = PXPolicy()  
policy.requestsInterceptedAutomaticallyEnabled = false  
PerimeterX.setPolicy(policy, null)
PXPolicy nativePolicy = new PXPolicy();  
policy.setRequestsInterceptedAutomaticallyEnabled(false);  
PerimeterX.INSTANCE.setPolicy(policy, null);
  1. Before sending your URL request, take HTTP headers from the SDK and add them to your request.
val headers = PerimeterX.headersForURLRequest()
HashMap<String, String> headers = PerimeterX.INSTANCE.headersForURLRequest(null);
  1. After receiving an error in the response, pass the information to SDK.
val isHandledByPX = PerimeterX.handleResponse(null, responseString, response.code)  
if (isHandledByPX) {  
println("block response was handled by PX")  
}
boolean isHandledByPX = PerimeterX.INSTANCE.handleResponse(null, responseString, response.code());  
    if (isHandledByPX) {  
        Log.i("tag", "block response was handled by PX");  
    }

Migrating from earlier SDK version (1.x)

Start the SDK

In version 1.x, the start function is called with 2 parameters: AppId and enableDoctorCheck (the later was added in 1.16.0).

In version 2.0, the start function has another parameter: delegate (PerimeterXDelegate) to handle the SDK's events. Notice that the new Interceptor will be enabled in 2.0. This has effect on the integration with the SDK, which will be described later in this document.

Set custom parameters

In version 1.x, the set custom parameters function is called with the dictionary parameter only.

In version 2.0, the setCustomParameters function has another optional param: the AppID. This is required only when using multiple AppIDs.

Get VID

In version 1.x, the get VID function is called without any parameters.

In version 2.0, the vid function has another optional param: the AppID. This is required only when using multiple AppIDs.

Get HTTP headers

In version 1.x, the get HTTP headers function is called without any parameters.

In version 2.0, the headersForURLRequest function has another optional param: the AppID. This is required only when using multiple AppIDs. Please note that now this function should NOT be used when the interceptor is enabled.

🚧

Important

The Get HTTP headers function should NOT be used when the interceptor is enabled.

Check error and handle response

In version 1.x, a function is called to get the PX's error response from the request's response which called another function to handle the PX's error response.

In version 2.0 the flow is as following:

  1. If the interceptor is enabled, simply check whether the request was blocked with the isRequestBlockedError function.

  2. If the interceptor is disabled, use the PerimeterX SDK to handle the response with the handleResponse function. If it was a blocked response, the SDK will handle it and the function will return true.

Other functions

All other functions existing in version 1.x were removed from the SDK's API in version 2.0.


Did this page help you?