> This page is for Applications Protection. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.humansecurity.com/llms.txt. # How to integrate the SDK in your application #### v1.x ## Android SDK ### Adding the Android SDK to your project 1. Add the Android SDK Binary to Your Project.\ The official repository for hosting the HUMAN Android SDK The repository can be integrated with Maven, Gradle, or Ivy. > **Note** > > \ should be replaced with the correct version. **In Maven, run:** ```none com.perimeterx.sdk msdk pom ``` **In Gradle, run:** ```none implementation 'com.perimeterx.sdk:msdk:' ``` **In Ivy, run:** ```none ``` 2. Once the binary is added to your project, resync the build files to ensure the package is downloaded. 3. The SDK is now installed, and there should not be any build errors when compiling your application. **To import and integrate the Android SDK in an Android application edit the project's `build.gradle` file and add the following *maven* and *mavenCentral* configurations:** ```text allprojects { repositories { mavenCentral() //allows PerimeterX's Android SDK to resolve its needed dependencies from maven central maven { url "https://perimeterx.jfrog.io/artifactory/px-Android-SDK/" //PerimeterX's Artifactory repository url } } } ``` ### Adding the Required Permissions to AndroidManifest 1. In the AndroidManifest.xml add: ```none ``` XML example: ```none ``` ### Loading the PX Manager 1. Import the following classes into your Application class or the main activity: ```none import com.perimeterx.msdk.PXManager; import com.perimeterx.msdk.NewHeadersCallback; import com.perimeterx.msdk.ManagerReadyCallback; import com.perimeterx.msdk.PXResponse; import com.perimeterx.msdk.BackButtonPressedCallBack; ``` 2. In your **onCreate** method initialize the PX Manager (using your App ID): ```java private final static String PERIMETERX_APPID = "PX12345678"; @Override protected void onCreate(Bundle savedInstanceState) { PXManager.getInstance() .setNewHeadersCallback( new NewHeadersCallback() { @Override public void onNewHeaders(HashMap headers) { System.out.println("New headers called back"); } } ) .setManagerReadyCallback(new ManagerReadyCallback() { @Override public void onManagerReady(HashMap headers) { System.out.println("Manager ready called back"); } }) .start(this, PERIMETERX_APPID); } ``` ```kotlin private val PERIMETERX_APPID = "PX12345678" override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) PXManager.getInstance() .setNewHeadersCallback { println("New headers called back") } .setManagerReadyCallback { println("Manager ready called back") } .start(this, PERIMETERX_APPID) } ``` * When initializing the *PXManager* instance the *setManagerReadyCallback* is called when the first set of HTTP headers are available. * Setting the *setNewHeadersCallback* is required to ensures that the *PXManager* will notify the application that a refresh to the HTTP headers occurred. This is based on the token validity time set in the HUMAN portal. * Action in the *onNewHeaders* method is optional. (reference the code example above). ### Adding the HTTP Headers to the HTTP Requests 1. Once the PX Manager is initialized, add HTTP Headers to your network manager headers. You are now set to start your requests. 2. The HTTP headers are retrieved by calling the *httpHeaders()* method of *PXManager*. This returns a hashmap of type *Map\< String, String>*. This map can be used as is or can be iterated over. > **Note** > > It is not recommended for the application to make network calls going through PX Enforcer without PX headers. **Using Volley** To add the HTTP headers to a request in Volley you can override the getHeaders method: ```java @Override public Map getHeaders() throws AuthFailureError { return PXManager.httpHeaders(); } ``` ```kotlin @Throws(AuthFailureError::class) override fun getHeaders(): Map? { return PXManager.httpHeaders() } ``` **Using OKHttp** To add the HTTP headers to a request in OKHttp ```java Request.Builder reqBuilder = new Request.Builder().url("https://www.perimeterx.com/"); for (HashMap.Entry entry : PXManager.httpHeaders().entrySet()) { String key = entry.getKey(); String value = entry.getValue(); reqBuilder.addHeader(key, value); } ``` ```kotlin val reqBuilder: Request.Builder = OkHttpClient.Builder().url("https://www.perimeterx.com/") for (entry in PXManager.httpHeaders().entries) { val key: String = entry.key val value: String = entry.value reqBuilder.addHeader(key, value) } ``` Reference [Interceptors](https://github.com/square/okhttp/wiki/Interceptors) for advanced integration. ### Managing Requests Denied When a HTTP request is denied because of internal error, a 403 response code is sent in the HTTP response along with a JSON body encoded as a UTF-8 that is parsed and used by the Android SDK. The parsed JSON is then used to render a WebView to either challenge (with CAPTCHA) the visitor, or block the visitor from continuing in the application. When the user solves the CAPTCHA challenge they are returned to the application. If the user fails the CAPTCHA challenge they continue to be challenged until they pass the verification screen. #### Implementing the Error Handler The *PXManager* object checks the body of the returned error message by calling the *checkError()* method, and passing in the body object as a UTF-8 encoded string. This returns an object type of *PXResponse*. To check whether a *403* status code is coming from PX, run: ```java PXResponse PXResponse = PXManager.checkError(body); if (PXResponse.enforcement().name().equals("NOT_PX_BLOCK")){ //the 403 error was not sent by PX ``` ```java val response = PXManager.checkError(body) if (response.enforcement().name.equals("NOT_PX_BLOCK")) { //the 403 error was not sent by PX } ``` ```java final String body = new String(error.networkResponse.data, UTF_8); PXResponse PXResponse = PXManager.checkError(body); ``` ```kotlin val body = error.networkResponse.data.toString() val response = PXManager.checkError(body) ``` The *PXResponse* object is processed by calling the *handleResponse()* method of the *PXManager* object, and passing two arguments: *PXResponse* and *CaptchaResultCallback*. The *handleResponse()* method renders the WebView containing the CAPTCHA challenge. The *CaptchaResultCallback* must implement the *onCallback()* method. *onCallback()* is called whenever the user solves the challenge or the challenge is canceled. ```java PXManager.handleResponse(PXResponse, new CaptchaResultCallback() { @Override public void onCallback(Result result, CancelReason reason) { switch (result) { case SUCCESS: Log.i(LOG_TAG, "SUCCESS"); break; case CANCELED: Log.i(LOG_TAG, "captcha canceled due to: " + reason); break; } } }); ``` ```kotlin PXManager.handleResponse(response) { result, reason -> when (result) { CaptchaResultCallback.Result.SUCCESS -> Log.i(LOG_TAG, "SUCCESS") CaptchaResultCallback.Result.CANCELED -> Log.i( LOG_TAG, "captcha canceled due to: $reason" ) } } ``` *handleResponseSync* is the same as *handleResponse* but blocks the current thread. It can be used for implementing an Interceptor. For example: ```kotlin import com.perimeterx.msdk.* import okhttp3.Interceptor import okhttp3.Request import okhttp3.Response import kotlin.jvm.Throws import java.io.IOException internal class PXInterceptor: Interceptor { @Throws(IOException::class) override fun intercept(chain: Interceptor.Chain): Response { val request = chain.request().newBuilder().build() return proceedRequestAndResolvePXResponseIfNeeded(chain, request) } fun proceedRequestAndResolvePXResponseIfNeeded(chain: Interceptor.Chain, request: Request): Response { do { // add PX headers (remove old values if exist) val theRequest = addPXHeaders(removePXHeaders(request)) val response = chain.proceed(theRequest) val rawResponseBody = response.peekBody(Long.MAX_VALUE).string() val pxResponse = PXManager.checkError(rawResponseBody) // check if the response is NOT_PX_BLOCK if (pxResponse.enforcement() == PXResponse.EnforcementType.NOT_PX_BLOCK) { // return the response return response } return try { // handle PX's response (will show captcha screen to the user) val result = PXManager.handleResponseSync(pxResponse) // handle the captcha result when (result.captchaResult) { CaptchaResult.CAPTCHA_SUCCESS -> { // the user solved the captcha -> proceed the request again continue; } CaptchaResult.NO_CAPTCHA, CaptchaResult.CAPTCHA_CANCELED, null -> { // the user didn't solve the captcha -> crate an error responsereturn createError(response) } } } catch (e: ExecutionException) { // return error createError(response) } catch (e: InterruptedException) { // return error createError(response) } } while (Thread.currentThread().isAlive) throw IOException("current thread is dead") } fun addPXHeaders(request: Request): Request { val builder = request.newBuilder() PXManager.httpHeaders().forEach { builder.addHeader(it.key, it.value) } return builder.build() } fun removePXHeaders(request: Request): Request { val builder = request.newBuilder() PXManager.httpHeaders().forEach { builder.removeHeader(it.key) } return builder.build() } fun createError(response: Response): Response { return response.newBuilder().code(-1).build() } } ``` Depending on how your application is built, an attacker can be blocked on any network call your application makes. The attacker can be blocked while the application is loading, and the only thing the user sees is the splash screen. The attacker can be in a background thread when the application makes API calls to retrieve a session token or to request data from the server to be presented on the screen. You can choose what screen to display after the blocked user successfully solves a CAPTCHA challenge. The user can be redirected to their previous activity and retry the network calls that were blocked. The user can be returned to their previous activity and have to repeat the action that was blocked. The user can be redirected to a different screen. **Using Volley** With Volley a *Response.ErrorListener* is implemented and the *VolleyError* is passed to the the *onErrorResponse()* method. ```java new Response.ErrorListener() { @Override // Handles errors that occur due to Volley public void onErrorResponse(final VolleyError error) { final NetworkResponse networkResponse = error.networkResponse; if (networkResponse != null && networkResponse.statusCode == 403) // Check the HTTP response status code { // Retrieve body for captcha processing as a UTF 8 string. final String body = new String(error.networkResponse.data, UTF_8); PXResponse PXResponse = PXManager.checkError(body); if (PXResponse.enforcement().name().equals("NOT_PX_BLOCK")){ // Handle non PerimeterX 403 response status code } PXManager.handleResponse(PXResponse, new CaptchaResultCallback() { @Override public void onCallback(Result result, CancelReason reason) { switch (result) { case SUCCESS: Log.i(LOG_TAG, "SUCCESS"); break; case CANCELED: Log.i(LOG_TAG, "captcha canceled due to: " + reason); break; } } }); } Log.d("Volley", "Error"); results.setText(R.string.error_occurred); } } ``` \ ```kotlin Response.ErrorListener() { // Handles errors that occur due to Volley fun onErrorResponse(error: VolleyError?) { val networkResponse = error!!.networkResponse if (networkResponse != null && networkResponse.statusCode == 403) // Check the HTTP response status code { // Retrieve body for captcha processing as a UTF 8 string. val body = String(error!!.networkResponse.data, UTF_8) val response = PXManager.checkError(body) if (response.enforcement().name == "NOT_PX_BLOCK") { // Handle non PerimeterX 403 response status code } PXManager.handleResponse(response) { result, reason -> when (result) { CaptchaResultCallback.Result.SUCCESS -> Log.i(LOG_TAG, "SUCCESS") CaptchaResultCallback.Result.CANCELED -> Log.i( LOG_TAG, "captcha canceled due to: $reason" ) } } } Log.d("Volley", "Error") results.setText(R.string.error_occurred) } } ``` \ #### Handling Back Button on CAPTCHA webView When the application request is blocked by the Enforcer, the SDK takes control and a CAPTCHA page is displayed. Attackers may attempt to use Android's back button to return to the previous screen and continue malicious behavior. There is an option for you to enable or disable Android's back button functionality. By default, the SDK enables using the back button. When the back button is enabled, touching the back button returns the attacker to the previous screen. Any additional network calls cause the SDK to block the attacker again. By disabling the back button, the attacker remains on the CAPTCHA page until he solves the CAPTCHA challenge, or until he exits the application and relaunches it. When the application is relaunched, any additional network call is blocked with a CAPTCHA page. 1. To disable the back button, add the following code to the PXManager object during initialization of the SDK: ```java .setBackButtonDisabled(true) .setBackButtonPressedCallback(new BackButtonPressedCallBack(){ @Override public void onBackButtonPressed(){ Log.i(LOG_TAG, "back button pressed"); } }) ``` \ ```kotlin PXManager.getInstance().setBackButtonDisabled(true) PXManager.getInstance().setBackButtonPressedCallback { Log.i(LOG_TAG, "back button pressed"); } ``` \ 2. Inside the *onBackButtonPressed* method you can add the code of your choice to return the blocked user to his previous flow. #### WebView Integration **Added in version: v1.15.1** If your application includes a WebView, you need to allow SDK to handle the session connection between the web view and the application. To do that, after you create a web view instance (or get its reference from the view), call: ```java PXWebView.pxInit(webView, webViewClient); ``` \ ```kotlin PXWebView.pxInit(webView, webViewClient) ``` \ * The first parameter is your web view instance. * The second parameter is optional and can be NULL. If you want to receive events from the web view, you should pass your web view client instance. The SDK depends on Javascript. You should not disable Javascript in your web view's settings. #### Adding Custom Parameters Custom parameters allow you to collect and send specific app or device information to be used later for aggregations and intelligence. Using the *PXManager* **setCustomParameters()** method you can specify up to 10 custom parameters to be sent to servers on every network request. **setCustomParameters()** accepts a *Map* of type \[String, String] with all the keys beginning with *custom_param* followed by a number (1-10). The **setCustomParameters()** method is set once **before** calling the *start* method. The following example adds 2 custom parameters: ```java @Override protected void onCreate(Bundle savedInstanceState) { Map customParams = new HashMap<>(); customParams.put("custom_param1", "John Bradely"); customParams.put("custom_param2", "New York"); PXManager.getInstance() .setCustomParameters(customParams) .start(this, PERIMETERX_APPID); ``` \ ```kotlin override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val customParams: MutableMap = HashMap() customParams["custom_param1"] = "John Bradely" customParams["custom_param2"] = "New York" PXManager.getInstance().setCustomParameters(customParams) PXManager.getInstance().start(this, PERIMETERX_APPID) } ``` \ ### Support Account Defender (From version 1.16.5) The Account Defender Manager instance is retrieved by calling `PXAccountDefenderManager.getInstance(context)` with a context object. To enable the feature, a user ID must be set. That can be done by calling the `PXAccountDefenderManager.setUserID` function and providing the user ID. When the user ID is changed, the function should be called again with the updated user ID. If the user logs out, the function should be called with nil. The function should be called after the `PXManager.startWith` function. To register outgoing URL requests, call the `PXAccountDefenderManager.registerOutgoingUrlRequest` function with the URL. This function should be called only when Account Defender is enabled (user ID is set). ### User Agent Convention The application’s user agent is used to identify and differentiate between application versions. For accurate detection it is important that the user agent your application reports is informative. Here is the recommended convention: ### Doctor App The "Doctor App" is a tool to help you verify the mobile SDK integration by simulating a typical user flow in your application. To enable this feature, add the `enableDoctorCheck = true` parameter in the start method. > **Important** > > This feature is for development purposes only and should not be shipped with your application to the application store. Example: ```java PXManager.getInstance().start(this, "[YOUR_APP_ID]", true); ``` \ **Flow:** 1. Welcome screen: In this screen you select whether to start a new test or load the summary of the previous test, if one exists. 2. Instructions screen: In this screen you get detailed instructions on how the Doctor app works 3. Test selection screen: In this screen you choose which type of test to execute. Options are: a. Native app framework - test your native URL requests. b. Web view framework - test your web view's URL requests. After executing either test, you will return to this screen to be able to execute the other test or to continue and review the test results in the summary screen. ![](/_fern-img/657a4b431f571b94ec0d965986fae40894bb89bc5dd535f8da8f0cf0a705f94a.webp) 4. Summary screen: In this screen you are able to view the results of the executed tests. You can go into details regarding each test and get troubleshooting tips in case a test failed to help you analyze what is causing this issue. ![](/_fern-img/443a5009ef9a0c0378dda9b421534bfb1c744f15456a8ee9980bef9398a42301.webp) > **Important** > > When you exit the doctor app, your application will also terminate. Just remember to switch the 'enableDoctorCheck' parameter to false when you finish validating your integration with mobile SDK. ### Validating that PXManager is Loaded Properly #### Checking the ManagerReady Callback To verify that SDK is implemented correctly, print a line to the console when the *ManagerReady* callback is fired. ```java .setManagerReadyCallback(new ManagerReadyCallback() { @Override public void onManagerReady(HashMap headers) { System.out.println("Manager ready called back"); } }) ``` \ ```kotlin PXManager.getInstance().setManagerReadyCallback() { println("Manager ready called back"); } ``` \ A log line similar to the example below should be displayed in your Android Monitor window: ```none 09-28 21:13:09.776 3484-3585/com.perimeterx.example I/System.out: Manager ready called back ``` \ #### Checking With ADB Connect to the device with ADB and run **adb logcat | grep InternalManager**. This should produce the following output indicating the SDK has started and is in a ready state: ```none $ adb logcat | grep InternalManager 09-28 21:13:08.129 3484 3484 I InternalManager: SDK start() 09-28 21:13:08.227 3484 3484 I InternalManager: shouldRunCompleteSDKFlow - app version is different - new version: 1.0 09-28 21:13:08.227 3484 3484 I InternalManager: SDK shouldRunCompleteSDKFlow 09-28 21:13:08.227 3484 3484 I InternalManager: checkSDKEnabled... 09-28 21:13:08.576 3484 3511 I InternalManager: SDK is enabled on server 09-28 21:13:08.576 3484 3511 D InternalManager: Running app init activity 09-28 21:13:09.776 3484 3585 I InternalManager: SDK ready time: 1647 ``` \ #### Validating that HTTP Headers Are Part of Your Request Connections to API endpoint are inspected using a local proxy such as CharlesProxy\_. When inspecting requests look for the HTTP header named X-PX-AUTHORIZATION. > **Note** > > Requests to the perimeterx.net domain are also pinned to a specific SSL certificate and cannot be inspected with [Charles Proxy](https://www.charlesproxy.com/). If you have enabled a SSL proxy for all domains you must exclude perimeterx.net."> If this header is not present go back to the application code responsible for making the request and review to verify the headers were added to the request properly. #### Validating Denied Requests Denied requests have one of two possible actions, block or challenge, and both should be validated to ensure the request is properly handled. #### Console Developer Testing Tools Developers integrating with the Mobile SDK can be given access to the HUMAN Portal in a developer role. They then have access to the Developer section, which contains the Mobile Enforcement Verification tool. This tool allows a developer the ability to mark their requests to be denied for testing purposes. The testing tool is necessary to validate denied requests. > **Note** > > Make sure the Enforcer you are testing against is set to blocking mode before proceeding with the instructions. 1. Access the tool at [https://console.humansecurity.com/botDefender/developer](https://console.perimeterx.com/botDefender/developer). 2. Locate your test device's Visitor ID \, and click the \ Extractor button. This will launch the \ Extractor model: 3. Insert your IP address and click *Search*. This locates all \s for your APP ID. 4. Click *Select* to return to the tool with the App ID and \ fields populated 5. When the App ID and \ are available, you can start validating denied requests. #### Validating a Challenge Response To validate a challenge response: 1. Click CAPTCHA in the test tool and wait for the green toast notification to confirm you are ready to continue. 2. When the next PX token refresh occurs in your mobile application you will receive the CAPTCHA WebView. 3. To force a token refresh simply exit and relaunch the application. 4. Solve the challenge presented and verify that you are able to return to the application and continue using it. #### Validating a Blocking Response To validate a blocking response: 1. Click *Block* in the test tool and wait for the green toast notification to confirm you are ready to continue. 2. When the next PX token refresh occurs in your mobile application you will receive the block WebView. 3. To force a token refresh simply relaunch the application. Once you are blocked you cannot continue. 4. To release from blocking, exit the application, click the *Clear* button, and reload the application to verify that the clean token was received and the application is operating as expected. ### Appendix #### Configuring an Android Emulator to use Charles Proxy To configure your Android Emulator: 1. Set the HTTP proxy settings in the Wi-Fi menu. 2. In the Wi-Fi menu long press the connected network, select *Modify Network*, and fill in the proxy settings. If you are running Charles Proxy on your local machine then use the local IP (not the loopback). 3. To intercept HTTPS requests follow the guidelines at: [https://www.charlesproxy.com/documentation/using-charles/ssl-certificates](https://www.charlesproxy.com/documentation/using-charles/ssl-certificates). In Android Nougat special permissions are required to use a certificate added to the trust store. ### Deactivating the PX Mobile Sensor Remotely In certain cases, the PX Mobile Sensor (SDK) may need to be deactivated remotely, and the app run without any sensor intervention. This can be done based on any combination of the following parameters: * AppID * Operating System * Operating System Version * SDK Version * App Version To deactivate the Mobile Sensor, contact assigned to you support person. Support to allow deactivation via the Portal will be added in the future. #### Support for Full Screen on Devices with a Display Cutout The default cutout mode is set to `Never`, meaning the challenge page will not render on the cutout area: To change the behaviour to `SHORT_EDGES`, and have the page render on the entire display area, set the **setIsCutoutFullScreen()** to **true**. The **setIsCutoutFullScreen()** method is set once **before** calling the *start* method. > **Note** > > Full screen on devices with display cutouts is supported on Android version P (API level 28) and above and SDK version 1.7.0 and above. ```java @Override protected void onCreate(Bundle savedInstanceState) { PXManager.getInstance() .setIsCutoutFullScreen(true) .start(this, PERIMETERX_APPID); ``` \ ```kotlin override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) PXManager.getInstance().setIsCutoutFullScreen(true) PXManager.getInstance().start(this, PERIMETERX_APPID); } ``` \ The challenge page will now render over the entire display: ## Android SDK React Native ### Integration Adding the Android SDK to your Project: 1. Add the Android SDK Binary to Your Project with: [](/applications/android-how-to-integrate-the-sdk-in-your-application-v1)(the official repository for hosting the HUMAN Android SDK). The repository can be integrated with Maven, Gradle, or Ivy. > **Note** > > \ should be replaced with the correct version. **In Maven, run:** ```none com.perimeterx.sdk msdk pom **In Gradle, run:** ``` \ ```none implementation 'com.perimeterx.sdk:msdk:' ``` \ **In Ivy, run:** ```none ``` \ 2. Once the binary is added to your project, resync the build files to ensure the package is downloaded. **To import and integrate the Android SDK in an Android application edit the project's `build.gradle` file and add the following *maven* and *mavenCentral* configurations:** ```text allprojects { repositories { mavenCentral() //allows PerimeterX's Android SDK to resolve its needed dependencies from maven central maven { url "https://perimeterx.jfrog.io/artifactory/px-Android-SDK/" //PerimeterX's Artifactory repository url } } } ``` The SDK is now installed, and there should not be any build errors when compiling your application. ### Adding the Required Permissions to AndroidManifest In your AndroidManifest.xml add: ```none ``` **XML example:** ```none ``` ### Initializing the PX Manager 1. Import the following classes into your Application class or the main activity: ```none import com.perimeterx.msdk.ManagerReadyCallback; import com.perimeterx.msdk.NewHeadersCallback; import com.perimeterx.msdk.PXManager; ``` 2. In your **onCreate** method initialize the PX Manager (using your App ID): ```none @Override public void onCreate() { super.onCreate(); SoLoader.init(this, /* native exopackage */ false); PXManager.getInstance() .setNewHeadersCallback(new NewHeadersCallback() { @Override public void onNewHeaders(HashMap headers) { System.out.println("New headers called back"); } }) .setManagerReadyCallback(new ManagerReadyCallback() { @Override public void onManagerReady(HashMap headers) { Intent localIntent = new Intent("managerReady"); Log.i(LOG_TAG, "onManagerReady: " + headers); } }) .start(this, ""); } ``` ### Creating a Bridge For The Native Methods 1. In your project, add a new class called `PXBridge` and set it to extend `ReactContextBaseJavaModule`: ```none public class PXBridge extends ReactContextBaseJavaModule { } ``` 2. Add the class constructor: ```none public PXBridge(ReactApplicationContext reactContext) { super(reactContext); } ``` 3. Add the following methods: ```none @ReactMethod public void verifyResponse(ReadableMap body, final Promise promise) { String parsedBody; try { JSONObject convertedBody = convertMapToJson(body); parsedBody = convertedBody.toString(); } catch (JSONException e) { parsedBody = body.toString(); } PXResponse PXResponse = PXManager.checkError(parsedBody); if (PXResponse.enforcement().name().equals("NOT_PX_BLOCK")){ promise.resolve("NotPXBlock"); } else { PXManager.handleResponse(PXResponse, new ActionResultCallback() { @Override public void onSuccess() { System.out.println("onSuccess called ...."); promise.resolve("success"); } @Override public void onFailure(IOException exception) { promise.resolve("failure"); } @Override public void onBlockWindowClosed() { promise.reject("error", Block Window Closed"); } }); } } @ReactMethod public void getHttpHeaders(Promise promise) { WritableMap map = Arguments.createMap(); for (HashMap.Entry entry : PXManager.httpHeaders().entrySet()) { map.putString(entry.getKey(),entry.getValue()); } promise.resolve(map); } private static JSONObject convertMapToJson(ReadableMap readableMap) throws JSONException { JSONObject object = new JSONObject(); ReadableMapKeySetIterator iterator = readableMap.keySetIterator(); while (iterator.hasNextKey()) { String key = iterator.nextKey(); switch (readableMap.getType(key)) { case Null: object.put(key, JSONObject.NULL); break; case Boolean: object.put(key, readableMap.getBoolean(key)); break; case Number: object.put(key, readableMap.getDouble(key)); break; case String: object.put(key, readableMap.getString(key)); break; case Map: object.put(key, convertMapToJson(readableMap.getMap(key))); break; case Array: object.put(key, convertArrayToJson(readableMap.getArray(key))); break; } } return object; } private static JSONArray convertArrayToJson(ReadableArray readableArray) throws JSONException { JSONArray array = new JSONArray(); for (int i = 0; i < readableArray.size(); i++) { switch (readableArray.getType(i)) { case Null: break; case Boolean: array.put(readableArray.getBoolean(i)); break; case Number: array.put(readableArray.getDouble(i)); break; case String: array.put(readableArray.getString(i)); break; case Map: array.put(convertMapToJson(readableArray.getMap(i))); break; case Array: array.put(convertArrayToJson(readableArray.getArray(i))); break; } } return array; } @Override public String getName() { return "PXBridge"; } ``` The bridge exposes the minimal methods required for the SDK to operate: * `getHttpHeaders` - returns a JSON file containing the HTTP headers. * `verifyResponse` - verifies the 403 response and based on its content - either returns the response unchanged or calls the SDK's `handleBlockResponse` method. 4. Add a new class called `PXBridgePackage` and set it to extend `ReactPackage`: ```none public class PXBridgePackage implements ReactPackage { } ``` 5. Add the following methods to the new class: ```none @Override public List createNativeModules(ReactApplicationContext reactContext) { List modules = new ArrayList<>(); modules.add(new PXBridge(reactContext)); return modules; } @Override public List createViewManagers(ReactApplicationContext reactContext) { return Collections.emptyList(); } ``` 6. In your app's `MainApplication.java`, add the `PXBridgePackage` class to the end of the array returned by the `GetPackages()` method: ```none protected List getPackages() { return Arrays.asList( new MainReactPackage(), new PXBridgePackage() ); } ``` ### Adding the HTTP Headers to the HTTP Requests Once the PX Manager is initialized, you need to add the HTTP Headers to every network request your app is making. These headers can be retrieved by calling the `PXManager.httpHeaders()` method of the SDK, which is exposed to the JavaScript side by the bridge created in the previous step. **Using Axios** To add the  HTTP headers to every request using `Axios`, use the following example: ```none import {NativeModules} from 'react-native'; axios.interceptors.request.use(async (config) => { const pxHeaderResponse = await NativeModules.PXBridge.getHttpHeaders(); for (var prop in pxHeaderResponse) { config.headers[prop] = pxHeaderResponse[prop]; } return config; }, function (error) { throw error; }); ``` **Using Fetch** To add the HTTP headers to a `fetch` request, either add the headers directly to each request or create a wrapper like the following example: ```none async function callFetch() { const url = ' '; const pxHeaderResponse = await NativeModules.PXBridge.getHttpHeaders(); let headers = {}; for (var prop in pxHeaderResponse) { headers[prop] = pxHeaderResponse[prop]; } let result; try { result = await fetch(url,{ method: 'GET', headers: headers }) let jsonResult = await result.json(); return jsonResult; } catch (e) { throw e; } } ``` ### Managing Requests Denied When a HTTP request is denied because of internal error, a 403 response code is sent in the HTTP response along with a JSON body encoded as a UTF-8. The encoded JSON body is parsed and used by the Android SDK. The parsed JSON is then used to render a WebView to either challenge (with CAPTCHA) the visitor or block the visitor from continuing in the application. If the user solves the presented challenge they will return to the application. If the user fails the CAPTCHA challenge they continue to be challenged until they pass the verification screen. #### Implementing the Error Handler **Using Axios** The easiest way to implement the error handler is with Axios's response interceptor: ```none axios.interceptors.response.use((response) => { return response; }, async (error) => { if (error.response.status === 403) { let result = await NativeModules.PXBridge.verifyResponse(error.response.data); if (result == "NotPXBlock") { throw error; } } else { throw error; } }); ``` **Using Fetch** You can also implement the error handler using a **Fetch** based wrapper: ```none async function callFetch() { const url = ' '; const pxHeaderResponse = await NativeModules.PXBridge.getHttpHeaders(); let headers = {}; for (var prop in pxHeaderResponse) { headers[prop] = pxHeaderResponse[prop]; } let result; try { result = await fetch(url,{ method: 'GET', headers: headers }) let jsonResult = await result.json(); return jsonResult; } catch (error) { if (error.response.status === 403) { let result = await NativeModules.PXBridge.verifyResponse(error.response.data); if (result == "NotPXBlock") { throw error; } } else { throw error; } } } ``` ### Handling Back Button on Captcha webView When the application request is blocked by the Enforcer, the SDK takes control and a Captcha page is displayed. Attackers may attempt to use Android's back button to return to the previous screen and continue malicious behavior. There is an option for you to enable or disable Android's back button functionality. When the back button is enabled, touching the back button returns the attacker to the previous screen. Any additional network calls cause the SDK to block the attacker again. By disabling the back button, the attacker remains on the CAPTCHA page until he solves the Captcha challenge, or until he exits the application and relaunches it. When the application is relaunched, any additional network call is blocked with a Captcha page. By default, the SDK enables using the back button. 1. To disable the back button, add the following code to the PXManager object during initialization of the SDK: ```none .setBackButtonDisabled(true) .setBackButtonPressedCallback(new BackButtonPressedCallBack(){ @Override public void onBackButtonPressed(){ Log.i(LOG_TAG, "back button pressed"); } }) ``` 2. Inside the `onBackButtonPressed` method you can add the code of your choice to return the blocked user to his previous flow. ### Adding Custom Parameters Custom parameters allow you to collect and send specific app or device information to be used later for aggregations and intelligence. Using the `PXManager*`setCustomParameters()\` method you can specify up to 10 custom parameters to be sent to PX servers on every network request. `setCustomParameters()` accepts a `Map` of type \[String, String] with all the keys beginning with *custom_param* followed by a number (1-10). The `setCustomParameters()` method is set once **before** calling the `start` method. The following example adds 2 custom parameters: ```none @Override public void onCreate() { super.onCreate(); SoLoader.init(this, /* native exopackage */ false); Map customParams = new HashMap<>(); customParams.put("custom_param1", "John Bradely"); customParams.put("custom_param2", "New York"); PXManager.getInstance() .setCustomParameters(customParams) .start(this, ""); .. _add-the-perimeterx-http-headers-to-the-applications-http-requests: ``` ### WebView Integration **Added in version: v1.15.2** If your application includes a WebView, you need to allow the SDK to handle the session connection between the web view and the application. To do that, after you create a web view instance (or get its reference from the view), call: ```none PXWebView.pxInit(webView, webViewClient); ``` * The first parameter is your web view instance. * The second parameter is optional and can be NULL. If you want to receive events from the web view, you should pass your web view client instance. The SDK depends on Javascript. You should not disable Javascript in your web view's settings. ### Support Account Defender (From version 1.16.5) The Account Defender Manager instance is retrieved by calling `PXAccountDefenderManager.getInstance(context)` with a context object. To enable the feature, a user ID must be set. That can be done by calling the `PXAccountDefenderManager.setUserID` function and providing the user ID. When the user ID is changed, the function should be called again with the updated user ID. If the user logs out, the function should be called with nil. The function should be called after the `PXManager.startWith` function. To register outgoing URL requests, call the `PXAccountDefenderManager.registerOutgoingUrlRequest` function with the URL. This function should be called only when Account Defender is enabled (user ID is set). ### User Agent Convention The application's user agent is used to identify and differentiate between application versions. For accurate detection it is important that the user agent your application reports is informative. Here is the recommended convention: ### Doctor App The "Doctor App" is a tool to help you verify the mobile SDK integration by simulating a typical user flow in your application. To enable this feature, add the `enableDoctorCheck = true` parameter in the start method. > **Important** > > This feature is for development purposes only and should not be shipped with your application to the application store. Example: ```java [PXManager.sharedInstance startWith:@"[YOUR_APP_ID]" enableDoctorCheck:YES]; ``` **Flow:** 1. Welcome screen: In this screen you select whether to start a new test or load the summary of the previous test, if one exists. 2. Instructions screen: In this screen you get detailed instructions on how the Doctor app works 3. Test selection screen: In this screen you choose which type of test to execute. Options are: a. Native app framework - test your native URL requests. b. Web view framework - test your web view's URL requests. After executing either test, you will return to this screen to be able to execute the other test or to continue and review the test results in the summary screen. ![](/_fern-img/657a4b431f571b94ec0d965986fae40894bb89bc5dd535f8da8f0cf0a705f94a.webp) 4. Summary screen: In this screen you are able to view the results of the executed tests. You can go into details regarding each test and get troubleshooting tips in case a test failed to help you analyze what is causing this issue. ![](/_fern-img/443a5009ef9a0c0378dda9b421534bfb1c744f15456a8ee9980bef9398a42301.webp) > **Important** > > When you exit the doctor app, your application will also terminate. Just remember to switch the 'enableDoctorCheck' parameter to false when you finish validating your integration with the mobile SDK. ### Verifying Your Integration Validating that PXManager is Loaded Properly #### Checking the ManagerReady Callback To verify that SDK is implemented correctly, print a line to the console when the *ManagerReady* callback is fired. ```none .setManagerReadyCallback(new ManagerReadyCallback() { @Override public void onManagerReady(HashMap headers) { System.out.println("Manager ready called back"); } }) ``` A log line similar to the example below should be displayed in your Android Monitor window: ```none 09-28 21:13:09.776 3484-3585/com.perimeterx.example I/System.out: Manager ready called back ``` #### Checking With ADB Connect to the device with ADB and run `adb logcat | grep InternalManager`. This should produce the following output indicating the SDK has started and is in a ready state: ```none $ adb logcat | grep InternalManager 09-28 21:13:08.129 3484 3484 I InternalManager: SDK start() 09-28 21:13:08.227 3484 3484 I InternalManager: shouldRunCompleteSDKFlow - app version is different - new version: 1.0 09-28 21:13:08.227 3484 3484 I InternalManager: SDK shouldRunCompleteSDKFlow 09-28 21:13:08.227 3484 3484 I InternalManager: checkSDKEnabled... 09-28 21:13:08.576 3484 3511 I InternalManager: SDK is enabled on server 09-28 21:13:08.576 3484 3511 D InternalManager: Running app init activity 09-28 21:13:09.776 3484 3585 I InternalManager: SDK ready time: 1647 ``` #### Validating that HTTP Headers Are Part of Your Request Connections to your API endpoint can be inspected using a local proxy such as CharlesProxy\_. When inspecting requests look for the HTTP header named X-PX-AUTHORIZATION. > **Note** > > Requests to the perimeterx.net domain are also pinned to a specific SSL certificate and cannot be inspected with [Charles Proxy](https://www.charlesproxy.com/). If you have enabled SSL proxy for all domains you must exclude perimeterx.net. If this header is not present go back to the application code responsible for making the request and review to verify the headers were added to the request properly. ### Validating Denied Requests Denied requests have one of two possible actions, **block** or **challenge**, and both should be validated to ensure the request is properly handled. #### Console Developer Testing Tools Developers integrating with the PX Mobile SDK can be given access to the HUMAN Portal in a developer role. They then have access to the Developer section, which contains the Mobile Enforcement Verification tool. This tool allows a developer to mark their requests to be denied for testing purposes. The testing tool is necessary to validate denied requests. > **Note** > > Make sure the enforcer you are testing against is set to blocking mode before proceeding with the instructions. 1. Access the tool at [https://console.humansecurity.com/botDefender/admin?page=integration](https://console.perimeterx.com/botDefender/admin?page=integration). 2. Locate your test device's Visitor ID \, and click the \ Extractor button.\ This will launch the \ Extractor model 3. Insert your IP address and click *Search*.\ This locates all \s for your APP ID. 4. Click *Select* to return to the tool with the App ID and \ fields populated. 5. When the App ID and \ are available, you can start validating denied requests. #### Validating a Challenge Response To validate a challenge response: 1. Click Captcha in the test tool and wait for the green toast notification to confirm you are ready to continue. 2. When the next PX token refresh occurs in your mobile application you will receive the CAPTCHA WebView. 3. To force a token refresh simply exit and relaunch the application. 4. Solve the challenge presented and verify that you are able to return to the application and continue using it. #### Validating a Blocking Response To validate a blocking response: 1. Click *Block* in the test tool and wait for the green toast notification to confirm you are ready to continue. 2. When the next PX token refresh occurs in your mobile application you will receive the block WebView. 3. To force a token refresh simply relaunch the application. Once you are blocked you cannot continue. 4. To release from blocking, exit the application, click the *Clear* button, and reload the application to verify that the clean token was received and the application is operating as expected. ### Appendix #### Configuring an Android Emulator to use Charles Proxy To configure your Android Emulator: 1. Set the HTTP proxy settings in the Wi-Fi menu. 2. In the Wi-Fi menu long press the connected network, select *Modify Network*, and fill in the proxy settings.\ If you are running Charles Proxy on your local machine then use the local IP (not the loopback). 3. To intercept HTTPS requests follow the guidelines at:\  [https://www.charlesproxy.com/documentation/using-charles/ssl-certificates/](https://www.charlesproxy.com/documentation/using-charles/ssl-certificates/)\ In Android Nougat special permissions are required to use a certificate added to the trust store. #### Deactivating the PX Mobile Sensor Remotely In certain cases, the PX Mobile Sensor (SDK) may need to be deactivated remotely, and the app run without any sensor intervention. This can be done based on any combination of the following parameters: * AppID * Operating System * Operating System Version * SDK Version * App Version To deactivate the PX Mobile Sensor, contact your assigned focal point. Portal support to allow deactivation via the Portal will be added in the future. #### Support for Full Screen on Devices with Display Cutouts The default cutout mode is set to `Never`, meaning the challenge page will not render on the cutout area: To change the behaviour to `SHORT_EDGES`, and have the page render on the entire display area, set the **setIsCutoutFullScreen()** to **true**. The **setIsCutoutFullScreen()** method is set once **before** calling the *start* method. > **Note** > > Full screen on devices with display cutouts is supported on Android version P (API level 28) and above and the SDK version 1.7.0 and above. ```none @Override public void onCreate() { super.onCreate(); SoLoader.init(this, /* native exopackage */ false); PXManager.getInstance() .setIsCutoutFullScreen(true) .start(this, ""); ``` The challenge page will now render over the entire display