Manual integration
  • 09 Mar 2023
  • Dark

Manual integration

  • Dark


Understanding the flow

SDK's headers must be included in your URL requests. To your delight, the SDK automatically intercepts URL requests from your app which sent with OkHttp client. By doing so, the SDK takes care of adding those headers to your URL requests and handling blocks response from your server, which means you don't have to do anything else.

What is included in the SDK's HTTP headers
Those HTTP headers include a token that allows your server to verify that URL requests comes from your app, which running the SDK. In addition to the token, those headers include information about the device (OS name, OS version, device model, SDK version) and identifiers which generated by the SDK.

However, you may choose to take care of them manually.

Adding SDK's HTTP headers to your URL requests

  1. Disable requests interception by setting the PXPolicy/urlRequestInterceptionType to PXPolicyUrlRequestInterceptionType/none.
    policy.urlRequestInterceptionType = PXPolicyUrlRequestInterceptionType.NONE
  2. Before sending your URL request, take HTTP headers from the SDK and add them to your request.
    val headers = PerimeterX.headersForURLRequest(null)
    // add those headers to your URL request
    HashMap<String, String> headers = PerimeterX.INSTANCE.headersForURLRequest(null);
    // add those headers to your URL request
Headers should not be empty
When no headers are returned, it means that something went wrong with the SDK integration.
Don't cache headers from the headersForURLRequest function!
You should not cache those headers from the PerimeterX/headersForURLRequest(forAppId:) function. Those headers contain a token with expiration date. The SDK manages this token to be up-to-date.
Cache headers from the perimeterxHeadersWereUpdated delegate function
You may use the PerimeterXDelegate/perimeterxHeadersWereUpdated(headers:forAppId:) function to cache those HTTP headers. However, you must ensure that you update your cache every time this function is called.

Handle block responses from your server

After receiving an error in the server's response, pass the information to SDK with the PerimeterX/handleResponse(response:data:forAppId:callback:) function.

val isHandledBySDK = PerimeterX.handleResponse(responseString, null) { result ->
    println("challenge result = $result")
boolean isHandledByPX = PerimeterX.INSTANCE.handleResponse(responseString, null, result -> {
    Log.i("tag", "challenge result = " + result);
    return null;
if (isHandledByPX) {  
    Log.i("tag", "block response was handled by PX");

If the response cannot be handled by the SDK, this function will return false. This function returns true when the response was handled by the SDK. That means that a challenge will be presented to the user. After the user solved/cancelled the challenge, the handler code will be called with the proper result. You may use this handler to retry your request.

Was this article helpful?