Advanced Blocking Response (ABR)

Rendering a full challenge page for each web page block is not always the best solution. In such cases, the Advanced Blocking Response (ABR) provides an improved user experience and earlier threat blocking. When the ABR is enabled, the Enforcer normally responds with a JSON object for each blocked AJAX request. Such a JSON object contains all the information needed to render the challenge embedded in your website, whether through a popup modal, page section, or something else.

The ABR has two modes: Auto ABR or Custom ABR.

Auto ABR - In this mode, our Sensor monitors all AJAX (fetch/XHR) requests. When an ABR response is detected, the Sensor automatically loads the challenge in a modal over the webpage UI. Auto ABR has the following features:

• Requires no further development on the website.

• Allows partial customization - The challenge is rendered in a modal over the webpage UI. Only some elements of the challenge modal can be customized - colors, fonts, logo, and others.

• Is enabled by default, when the Bot Defender is integrated.

• Handles both JSON block responses and HTML block responses, when a standard block page is configured, allowing for a better coverage.

Custom ABR

• Allows to integrate the challenge in a more embedded manner, controlling where it will be rendered within the webpage UI.

• Allows advanced customization and flexibility, depending on the required user experience and flow. This is especially useful, when you want to re-create the original blocked request without reloading the page after the CAPTCHA is solved.

• Requires custom development and implementation.

Auto ABR

Auto ABR is a key piece in the HUMAN no-code integration. APIs and single page applications (SPA) are becoming more common, as compared to classic page load integrations, which either don’t include APIs and SPAs, or require custom code.
Auto ABR works as follows: The Sensor hooks to the fetch and XHR native methods in order to monitor responses that arrive from the relevant domain. After detecting an ABR response (JSON or HTML), the Sensor handles it by rendering the modal.

See the example below:

To enable/disable Auto ABR on your application, go to Product Settings > Challenge Settings > Auto ABR and set the toggle to On/Off.

Prerequisites

• Auto ABR per application is supported from Sensor version 7.6.9.

• Auto ABR is supported when using Human Challenge only.

Auto ABR FAQ

What happens, if I’ve enabled the Auto ABR, but the modal doesn’t trigger?
In case the Accept request header isn’t set in the application/JSON, or if a non-standard block page is configured, do one of the following:

• Contact your HUMAN CSE or SA

• Send us a Slack

• Email us at socsupport@humansecurity.com

Can I trigger the Auto ABR (for testing purposes)?
Yes. Customers with sensor version v8.5.3 and above can insert the following snippet in the DevTools Console on their site, allowing to trigger an Auto ABR challenge demonstrating how it looks and behaves.

window.dispatchEvent(new Event('triggerPxAutoAbrCaptchaDemo'));

Can I disable the Auto ABR on a specific path?
Yes. To disable the Auto ABR, simply set the following assignment in the Sensor snippet on the specific path/webpage you want to exclude:

window._pxMonitorAbr = false;

Add a custom script to set the assignment before injecting the Sensor script.

Can I add other domains besides my root domain to the list of handled domains for Auto ABR?
Yes. To add other domains, use the following window object to set an array of domains:

window._pxCustomAbrDomains = ['a.com', 'api.b.com'];

Also, you can add ‘localhost’ as a custom domain for local testing to be used for ABR. To do this, add the assignment in a custom script before injecting the Sensor.

window._pxCustomAbrDomains = ['localhost']

The _pxCustomAbrDomains property requires Sensor version v7.9.8 and above.

What happens after the user solves the challenge?
By default, the page is refreshed. However, you can define a custom behavior by implementing the _pxOnCaptchaSuccess callback function. For further information about the callback function, see Step 3 of Integrating Custom ABR.

Can I customize the rendered modal?
Yes. You can customize certain parameters of the modal, such as colors, fonts, logo, and others. For more information, see Challenge Page Customization and Configuration.

Do I need to change the way I handle XHR/fetch responses?
When handling 403 responses, make sure your code doesn’t redirect or refresh.

What should I pay attention to when switching from the Custom ABR to Auto ABR?

Avoid:

• Implementing the _pxOnCaptchaSuccess callback function

• Injecting the < div id="px-captcha"> element

• Handling the ABR in any way (captcha.js script injection, etc.)

Custom ABR

In cases where a custom blocking flow is required (triggering inside a specific page, configuring a custom flow, etc.), you may want to implement a custom ABR. The Advanced Blocking Response occurs when a request contains the Accept header with the value of application/JSON. A sample JSON response may look like this:

{
    "appId": String,
    "jsClientSrc": String,
    "firstPartyEnabled": Boolean,
    "vid": String,
    "uuid": String,
    "hostUrl": String,
    "blockScript": String
}

Integrating Custom ABR

To implement Custom ABR, you must create a custom challenge section that will display the Human Challenge. To display the Human Challenge, perform the following steps on your page (full page, pop-up modal template, or something else):

1. Add a div with a px-captcha ID, where you want the challenge to be rendered:
   

   JavaScriptJavaScript

   <div id="px-captcha"></div>
   

2. Handle the ABR for your xhr\fetch calls by setting the relevant window params and loading the CAPTCHA script.

   JavaScriptJavaScript

   fetch('some_url', {method: 'GET', headers: {'Accept': 'application/json'}})
       .then((response) => {
           const responseUrl = response.url;
           // here we expect a JSON response
           response.json()
               .then((data) => {
                   // add check to make sure this is ABR response (can check data\ 403 status)
                   // in case it is, handle as such
                   window._pxBlockedUrl = responseUrl; // pxBlockedUrl param is the original path on which Bot Defender flagged the user as a bot (blocked)
                   const { appId, jsClientSrc,firstPartyEnabled,vid,uuid,hostUrl, blockScript } = data;
                   window._pxAppId = appId;
                   window._pxJsClientSrc = jsClientSrc;
                   window._pxFirstPartyEnabled = firstPartyEnabled;
                   window._pxVid = vid;
                   window._pxUuid = uuid;
                   window._pxHostUrl = hostUrl;
                   const p = document.getElementsByTagName('script')[0],
                       s = document.createElement('script');
                   s.src = blockScript;
                   p.parentNode.insertBefore(s,p);
               })
       })

3. Add the callback function.

This function is activated, when the CAPTCHA is solved successfully or when it is not validated.

window._pxOnCaptchaSuccess = function(isValid) {
 // Define logic based on the isValid parameter
}

In addition, we recommend adding the _pxOnCaptchaSuccess callback function - a callback run when the CAPTCHA is solved with one param (isValid), indicating if it was solved successfully. The callback function should be added to the window object of your CAPTCHA page to react according to the CAPTCHA status. For example, you can use callback to close the modal after the CAPTCHA is successfully solved.

In some cases, upon a successful CAPTCHA solve, it can be a good idea to include a script in the callback function, which re-creates the request/s that originally received the ABR in order to ensure the expected page flow.

If the captcha is not successfully solved (isValid==false), there's no need to remove the modal, as a new captcha will be presented, giving the user another chance to solve it.

If the model is removed, the user will be stuck and unable to proceed.

If no callback function is defined, the page will reload upon a successful CAPTCHA solve, unless a "url" query-param is included in the page URL. In this case, the URL will be changed accordingly.