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 (please refer to the relevant Mobile SDK version):

implementation 'com.google.android.material:material:1.5.0'  
implementation 'com.google.android.gms:play-services-instantapps:18.0.1'
implementation 'io.ktor:ktor-client-okhttp:1.6.8'
implementation 'com.google.android.material:material:1.5.0'  
implementation 'com.google.android.gms:play-services-instantapps:18.0.1'
implementation 'io.ktor:ktor-client-okhttp:1.6.8'
implementation 'com.google.android.material:material:1.5.0'  
implementation 'com.google.android.gms:play-services-instantapps:18.0.1'
implementation 'io.ktor:ktor-client-okhttp:1.6.8'
implementation 'com.google.android.material:material:1.5.0'  
implementation 'com.google.android.gms:play-services-instantapps:18.0.1'
implementation 'io.ktor:ktor-client-okhttp:1.6.8'
implementation 'com.google.android.material:material:1.5.0'  
implementation 'com.google.android.gms:play-services-instantapps:18.0.1'
implementation 'io.ktor:ktor-client-okhttp:1.6.7'
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'

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.4.1"
implementation "androidx.lifecycle:lifecycle-extensions:2.2.0"
implementation "androidx.lifecycle:lifecycle-common-java8:2.4.1"
implementation "androidx.lifecycle:lifecycle-extensions:2.2.0"
implementation "androidx.lifecycle:lifecycle-common-java8:2.4.1"
implementation "androidx.lifecycle:lifecycle-extensions:2.2.0"
implementation "androidx.lifecycle:lifecycle-common-java8:2.4.1"
implementation "androidx.lifecycle:lifecycle-extensions:2.2.0"
implementation "androidx.lifecycle:lifecycle-common-java8:2.4.1"
implementation "androidx.lifecycle:lifecycle-extensions:2.2.0"

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.3.6'

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

You can find the full API documentation for the latest version here.
You can find API documentation for older versions below (please refer to the relevant Mobile SDK version):

https://mobile-docs.perimeterx.com/px-android-sdk/v2.2.1/index.html
https://mobile-docs.perimeterx.com/px-android-sdk/v2.2.0/index.html
https://mobile-docs.perimeterx.com/px-android-sdk/v2.1.1/index.html
https://mobile-docs.perimeterx.com/px-android-sdk/v2.1.0/index.html
https://mobile-docs.perimeterx.com/px-android-sdk/v2.0.1/index.html
https://mobile-docs.perimeterx.com/px-android-sdk/v2.0.0/index.html

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 in the Application's onCreate function. This function sets up the session for a given AppID. When the process ends, and the completion handler is called with success as true, the SDK will have an updated token from PerimeterX backend. However, while this function is working in the background, the SDK will still provide the required headers (for example, a token from a previous session if exists). It's essential to call this function as early as possible in your application and before any URL request to your server.
PerimeterX.INSTANCE.start(this, "<APP_ID>", this, false) { success ->  
  if (success) {  
    PerimeterX.INSTANCE.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.
//OkHttp:
private var okHttpClient: OkHttpClient = OkHttpClient.Builder()  
  .addInterceptor(MyInterceptor())  
  .addInterceptor(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  
  }  
}
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! 🎉 You can follow this link and download our demo app in order to see an example of integrating the SDK in an Android app.

Disable automatic 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 PerimeterX's start function, disable the automatic interception in the policy. In order that the new policy will be taken into affect, you must call the start function before setting the new policy. It's recommended to set the policy right after calling the start function to avoid unexpected behaviour. You don't have to wait until the completion handler of the start function is called, before you set the policy.
val policy = PXPolicy()  
policy.requestsInterceptedAutomaticallyEnabled = false  
PerimeterX.INSTANCE.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. The SDK should always return headers. When no headers are returned, it means that something went wrong with the SDK integration.
val headers = PerimeterX.INSTANCE.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.INSTANCE.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");  
}

Integration with React Native

The Perimeter X Android SDK can be integrated into React Native projects.

  1. Add the SDK to your Android project as described above.
  2. The automatic interceptor is not supported in React Native, so any request from the JavaScript code has to be handled manually.
  3. Disable the automatic interception as described above.
  4. Create a native module as described here.
  5. Create a function that pass the HTTP headers from the PerimeterX SDK to the JavaScript code. Here is an example:
@ReactMethod  
public void getHTTPHeaders(Callback callBack) {  
    JSONObject json = new JSONObject(PerimeterX.INSTANCE.headersForURLRequest(null));  
    callBack.invoke(json.toString());
}
  1. In your JavaScript code, send your request with those HTTP headers. Here an example:
PerimeterXModule.getHTTPHeaders(async headers => {  
  const obj = JSON.parse(headers);  
  const url = 'https://my.request.com'
  const response = await fetch(url, {  
    method: 'GET',  
    headers: obj,  
  });  
});
  1. Next, pass the response back to the native module. Here is an example:
@ReactMethod  
public void handleResponse(String response, Integer code, String url) {  
  PerimeterX.INSTANCE.handleResponse(null, response, code);
}
const json = await response.json();  
PerimeterXModule.handleResponse(JSON.stringify(json), response.status, url);

Migrating from earlier SDK version (1.x)

Start the SDK

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

In version 2.0, the start function has additional parameter:

  1. application which replace the context.
  2. delegate (PerimeterXDelegate) to handle the SDK's events.
  3. completion handler to handle the result of the start process.

Notice that the new Interceptor will be enabled in 2.0. This has effect on the integration with the SDK, which i described 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?