Set Challenge configurations

Challenge Configurations are settings that dictate the Human Challenge’s behavior. You can toggle these on in Sightline Settings, and if you need to customize them further, you can directly configure them from the Challenge JavaScript. This JavaScript should be deployed in your Enforcer’s px_js_ref configuration.

You can learn how to set up these configurations with this article.

Prerequisites

• Both Advanced Blocking Response (ABR) modes require Sensor version 8.5.3 or higher.
• If you want to customize how your Challenge looks, see Customize Challenge Look & Feel.

Enable Challenge configurations

To enable these settings, navigate to Sightline Cyberfraud Defense > Settings > Mitigation > Challenge Settings. From the Challenge Configurations tab, click each toggle to enable or disable a setting. The available settings are described below.

Auto ABR

📘

Note

If you toggle this setting off, then your Challenge will enter Custom ABR instead.

This setting lets the Challenge display automatically whenever Sightline detects suspicious API requests sent outside of the original page request. In other words, this lets the Challenge appear on a page if Sightline believes the interactions on the page, such as page clicks, are from bots rather than humans. This happens in addition to the Challenge rendering to suspected bots before they access a page.

In this mode, the HUMAN Sensor all AJAX (fetch and XHR) requests. When the Sensor detects an ABR in either JSON or HTML, it loads the Challenge over the application for the user to solve. Below is an example of the Auto ABR.

Once the user solves the Challenge, the page will refresh, and they can proceed with their flow.

Custom ABR

📘

Note

This mode is enabled if you toggle off Auto ABR.

Sometimes, you may need a custom blocking configuration so the Challenge triggers on a specific page, to create a custom flow, or some other reason. In those cases, you can use Custom ABR. This setting has the same function as the Auto ABR, but it also lets you control and customize where you render the Challenge in your application. Custom ABR requires custom development and implementation.

Similarly to Auto ABR, Custom ABR triggers when a request contains an application/json Accept header. For example, a JSON request make look like this:

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

For more on configuring a Custom ABR, see Customize Custom ABR.

Enhanced Accessibility Mode

This setting enables a more accessible version of the Human Challenge. When this is enabled, the default Challenge will appear as usual, but there will be an additional accessible option for humans to choose if they need it.

📘

Note

It may take up to 10 minutes for Enhanced Accessibility Mode to take effect.

Enhanced Accessibility Mode provides better experience to impaired individuals. It's WCAG 2.2 certified, conforms with a VPAT 2.4 report, and provides an inclusive, accessible experience to a wider range of people with disabilities. This includes accommodations for blindness and low vision, deafness and hearing loss, limited movement, speech disabilities, photosensitivity, and combinations of these, as well as some accommodation for learning disabilities and cognitive limitations.

That said, both the original and Enhanced Accessibility modes of the Challenge are ARIA compatible and provide capabilities such as:

• Text coded into the images
• Proper prompting text
• Enabled keyboard access to elements on the page

Customize Challenge configurations

Some Challenge configurations have unique customizations you can use to best fit your users’ needs.

Customize Auto ABR

Add domains

You can add other domains in addition to your root domain for Auto ABR to handle. To do so, add the following to your Sensor snippet:

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

Disable on certain paths

You can disable the ABR on certain paths by adding the following to the Sensor snippet on the specific path or webpage you want to exclude. We recommend adding a custom script to set the assignment before injecting the Sensor script.

window._pxMonitorAbr = false;

Testing

You can manually trigger the ABR by adding the following to your site:

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

You can also add localhost as a custom domain for local testing. To do so, add the assignment as a custom script before injecting the Sensor:

window._pxCustomAbrDomains = ['localhost']

Customize Custom ABR

The Custom ABR needs a custom section in your application that will display the Human Challenge. This can be a full page, modal, popup, or something else. To implement it:

1. Create a div with a px-captcha ID in the area you want the Challenge to render.

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

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

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 Sightline 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 activates when the CAPTCHA is solved successfully or when it is invalid. It must be added to the window object of your CAPTCHA page to react according to the CAPTCHA status—for example, to close the modal after the CAPTCHA is successfully solved. We recommend including a script that recreates the requests that originally received the ABR in order to ensure the expected page flow.

📘

Note

If the Challenge is not solved (that is, isValid is false), you do not need to create a script to remove the modal because a new Challenge will appear. If the model is removed, the user will be stuck and unable to proceed.

If you do not define a callback function, the page reloads when the CAPTCHA is solved unless you include a url query-param in the page URL. In this case, the URL will change accordingly.

window._pxOnCaptchaSuccess = function(isValid) { // pxOnMobileCaptchaSuccess for mobile application Challenges
    // Define logic based on the isValid parameter
}