Human Challenge Customizations and Configurations

Challenge Page Customization and Configuration

The following properties can be customized in the Captcha page, in the <script> tag containing the PerimeterX window object’s properties. There are several options for customizing the Challenge page, such as inserting a logo, messaging, and colors.

Here is an example of the default Challenge page:

Default Context Configuration

// default configuration for the new block page and modal (Auto-ABR)
headerText = 'Before we continue...';
headerColor = '#626364';
headerFontSize = '29px';
messageText = 'Press & Hold to confirm you are<br>a human (and not a bot).';
messageColor = '#626364';
messageFontSize = '18px';
// default configuration for the “Please try again” message
fontSize = '12px';
color = '#e50e08';

Human Challenge Language

window._pxSelectedLocale = '<languageCode>';

A list of supported language codes can be found below.

Translation Object

If you wish to set the entire Captcha page in a language other than English, add the _pxTranslation object to your page. This object should contain the language code as the key.

Localizing

There are two levels of localization available: The Challenge element or the Entire Block Page.

  • To translate the Challenge element only, set window._pxSelectedLocale = '<languageCode>'; to your desired language from the Language Codes section below.
  • To translate the entire Captcha page to a language other than English, set the _pxTranslation object to your page. You must set the language to show in the window._pxSelectedLocale = '<languageCode>';.
  • You must define the CSS Selectors according to the elements you are translating.
  • You need to add window._pxSelectedLocale = '<languageCode>'; and the object below directly to the Captcha/custom block page or using a custom JS file defined in the enforcer’s JSref property.

📘

Note

If you have a custom page, you must define the correct css selectors.

Challenge Page Object Example

window._pxSelectedLocale = 'en-US';
window._pxTranslation = {
   'en-US': [
       {
           "selector": ".px-captcha-header",
           "text":'Before we continue...'
       },
       {
           "selector": ".px-captcha-message",
           "text": "Press & Hold to confirm you are a human (and not a bot)."
       },
       {
           "selector": "span.px-captcha-report",
           "text": "Having a problem?"
       }
   ]
};
window._pxTranslation = {
    'pt-PT': [
        {
            'selector': ".page-title h1",
            "text":'Ops! Tem certeza que você não é um robô?'
        },
        {
            "selector": ".content-wrapper p:nth-of-type(1)",
            "text": "Antes que você volte a navegar na página que queria, precisamos garantir que você é uma pessoa de verdade, e não um robô ;)"
        },
        {
            "selector": ".content-wrapper p:nth-of-type(2)",
            "text": "Isso pode ter ocorrido por conta de uma dessas hipóteses:"
        },
        {
            "selector": ".content-wrapper li:nth-of-type(1)",
            "text": "Seu Javascript está desligado ou bloqueado por algum plugin ou aplicativo (exemplo: ad blocker)"
        },
        {
            "selector": ".content-wrapper li:nth-of-type(2)",
            "text": "Seu browser de internet não suporta cookies"
        },
        {
            "selector": ".content-wrapper p:nth-of-type(3)",
            "text": "Pra isso não acontecer mais, garanta que o Javascript e os Cookies estejam ativos no seu navegador e que eles não estejam bloqueados quando você estiver navegando."
        },
        {
            "selector": ".content-wrapper p:nth-of-type(4)",
            "text": "#{{refId}}"
        }
    ]
}
window._pxSelectedLocale = 'en-US';
window._pxTranslation = {
    'en-US': [
        {
            "selector": "#px-form-title",
            "text":"Report a problem"
        },
        {
            "selector": "#px-form-subtitle",
            "text":"Experiencing issues with this page? please let us know:"
        },
        {
            "selector": "#px-form-item-ref-id",
            "text":"You can contact us for assistance. You should use Ref ID"
        },
        {
            "selector": "#px-form-item-options-title",
            "text":"You can also send us your feedback:"
        },
        {
            "selector": "#px-form-item-option-1",
            "text":"I do not see where to confirm"
        },
        {
            "selector": "#px-form-item-option-2",
            "text":"I keep getting the \"Please try again\" message"
        },
        {
            "selector": "#px-form-item-option-3",
            "text":"Other (please elaborate below)"
        },
        {
            "selector": "#px-form-textarea-title",
            "text":"Experiencing other issues?"
        },
        {
            "selector": "#px-form-cancel",
            "text":"Cancel"
        },
        {
            "selector": "#px-form-submit",
            "text":"Send"
        }
    ]
};
window._pxSelectedLocale = 'pt-PT';
    window._pxTranslation = {
    'pt-PT': [
        {
            "selector": "#px-form-head span",
            "text": "Experimentando problemas? Por favor, forneça mais informações:"
        },
        {
            "selector": "#px-form div:nth-of-type(1) label",
            "text": "Eu não estou vendo nenhum elemento captcha"
        },
        {
            "selector": "#px-form div:nth-of-type(2) label",
            "text": "Eu resolvi o captcha e consegui outro"
        },
        {
            "selector": "#px-form div:nth-of-type(3) label",
            "text": "Eu tenho resolvido vários captchas, mas ainda assim não consigo acessar o site"
        },
        {
            "selector": "#px-form div:nth-of-type(4) label",
            "text": "Outro (por favor elabore)"
        },
        {
            "selector": "#px-form h4:nth-of-type(1)",
            "text": "Informação adicional:"
        },
        {
            "selector": "#px-form-submit",
            "text": "Enviar comentários"
        },
        {
            "selector": "#px-block-toggle-button",
            "text": "Comunicar um problema"
        },
        {
            "selector": "#px-form textarea",
            "text": "Experimentando outros problemas?",
            "attribute": "placeholder"
        }
    ]
}

Human Challenge default language is English (en). We support the following languages out-of-the-box:

LanguageValue
Arabicar
Afrikaansaf
Amharicam
Armenianhy
Azerbaijaniaz
Basqueeu
Bengalibn
Bulgarianbg
Catalanca
Chinese (Hong Kong)zh-HK
Chinese (Simplified)zh-CN
Chinese (Traditional)zh-TW
Croatianhr
Czechcs
Danishda
Dutchnl
English (UK)en-GB
English (US)en
Estonianet
Filipinofil
Finnishfi
Frenchfr
French (Canadian)fr-CA
Galiciangl
Georgianka
Germande
German (Austria)de-AT
German (Switzerland)de-CH
Greekel
Gujaratigu
Hebrewiw
Hindihi
Hungarainhu
Icelandicis
Indonesianid
Italianit
Japaneseja
Kannadakn
Koreanko
Laothianlo
Latvianlv
Lithuanianlt
Malayms
Malayalamml
Marathimr
Mongolianmn
Norwegianno
Persianfa
Polishpl
Portuguesept
Portuguese (Brazil)pt-BR
Portuguese (Portugal)pt-PT
Romanianro
Russianru
Serbiansr
Sinhalesesi
Slovaksk
Sloveniansl
Spanishes
Spanish (Latin America)es-419
Swahilisw
Swedishsv
Tamilta
Telugute
Thaith
Turkishtr
Ukrainianuk
Urduur
Vietnamesevi
Zuluzu

For supported reCaptcha languages, see google’s reCaptcha documentation here.

Challenge Customization

Size and Colors

Height, width, and size are in pixels.

//Container
    width = 253; // 306 in mobile
    height = 50; // 62 in mobile
    fillColor = '#21b5ea';
    backgroundColor = '#FFFFFF';
//Border
    borderColor = '#21b5ea';
    borderWidth = 1;
    borderRadius = 100;
//Text
    textColor = '#21b5ea';
    texSize = 20; // 22 in mobile
    textFont = 'Roboto, sans-serif';
    textTransform = 'none';
//Animation
    animation = true;
    checkmarkThickness = '5px'; // '6px' in mobile
    checkmarkHeight = '30px'; // '35px' in mobile
    checkmarkWidth = '11px'; // '13px' in mobile
//Container
    width = 310;
    height = 100;
    fillColor = '#393939';
    backgroundColor = '#FFFFFF'
//Border
    borderColor = '#393939';
    borderWidth = 7;
    borderRadius = 100;
//Text
    textColor = '#393939';
    texSize = 31;
    textFont = 'OpenSans, Helvetica, Arial';
    textTransform = 'uppercase';
//Animation
    animation = true;
    checkmarkThickness = '7px';
    checkmarkHeight = '40px';
    checkmarkWidth = '15px';

📘

Note

Customers who already provide a challenge customization object should note that upgrading to the new enforcer version which supports the updated challenge page may result in different outputs. For the list of supported enforcer versions see below.

To customize the challenge, add the Human Challenge Configuration object, whether as inline script within the block page HTML or injected via a remote script in the block page HTML (configured by the Enforcer's JSref property).

  • To add a locale not included in the Human Challenge package, add the localization code to the locale object and enter the translated text to the text line of the translation object.
  • You can customize how the Human Challenge is displayed to match the look and feel of your site.
window._<APPID>= {
  locale: <string>,
  parent: '<string>', //Optional, element id, should exists in the DOM before loading PX script
  translation: <object> // legacy
  challenge: {
      translation: {
          <locale/default>:{  //'default' entry will change the default text presented. Out-of-the-box languages support "PRESS & HOLD" default
                  btn: <translation>,
                  failed: <translation>
             }
      }
      view: <object>,
      context: <object> // mainly relevant for new block page and modal (Auto-ABR)
  }
 };
challenge: {
        translation: { //Change this if you'd like to add custom translations based on locale
           "default": { //overriding default translation
                  btn: 'Push',
                  btn_done: 'Done', //once you add a finish text, consider disabling animation on view section
                  failed: 'Try again'
             },
           "de": {
              "btn": "Drücken und halten", // Press and Hold button
              "failed": "Bitte versuchen Sie es erneut.", // Message shown in case of failure in previous solve attempt
              "ac_1":"Human Challenge erfordert eine Bestätigung. Bitte drücken und halten Sie die Taste bis zur Bestätigung", // Accessibility - Push and Hold for verification
              "ac_2":"Human Challenge abgeschlossen, bitte warten", // Accessibility - "Challenge Ended"
              "al_1":"Es scheint ein Verbindungsproblem zu geben. Stellen Sie sicher, dass Sie online sind, und aktualisieren Sie die Seite", // Alert on internet connection issue
              "al_2":"Es scheint ein Problem mit Ihrem Browser zu geben. Bitte führen Sie ein Upgrade durch, um PerimeterX Human Challenge zu laden",  // Alert on browser issue
              "btn_done": "Erledigt" //Done
          }
        },
        view: {
            preset: <number>, // available options: 0 (classic button), 1 (new design)
            width: <number/string>, //e.g: 100, '100%'
            height: <number/string>, //e.g: 80, '99%'
            padding: <string>, //e.g "5px 1em 0 2em"
            margin: <string>, //e.g "1px 1px 0 0"
            parts: <number>, //e.g 300 (default - 150)
            css: <array:string>, //e.g ["https://fonts.googleapis.com/css?family=Acme&display=swap"]
            backgroundColor: <string>,//e.g "#FF0033"
            fillColor: <string>,//e.g "#FF0033"
            borderColor: <string>,//e.g "#FF0033"
            borderWidth: <number>,//e.g 7
            borderRadius: <number>,//e.g 10
            buttonBorderWidthOnFocus: <number>,//e.g 10
            textColor: <string>,//e.g "#FF33DD"
            texSize: <number>,//e.g 15
            textFont: <string>, // "Acme"
            fontWeight: <number/string>, //example: 100, 'bold'
            animation: <boolean>, //e.g. true
            checkmarkThickness: <string>, //e.g. "4px"
            checkmarkHeight: <string>, //e.g. "20px"
            checkmarkWidth: <string>, //e.g. "8px"
            targetColor: <string>, //e.g. "#FF00FF"
            textTransform: <string> //e.g. "none"
        },
        context: { // mainly relevant for new block page and modal (Auto-ABR)
            logoImgSrc: <string>, //e.g: 'https://www.perimeterx.com/logos/perimeterx.svg' (note: will replace the header options, see below)
            headerText: <string>, //e.g: 'Human verification'
            headerColor: <string>, //e.g: '​​#FF0000'
            headerFontSize: <string>, //e.g: '30px'
            messageText: <string>, //e.g: 'Please verify you are a human'
            messageColor: <string>, //e.g: '#0000FF'
            messageFontSize: <string>, //e.g: '20px'
            failed: { // custom options for the “Please try again” message
                  fontSize: <string>, //e.g: '14px'
                  color: <string>, //e.g: '#888888'
            }
        }
}

See the customization object example below:

window['_' + window._pxAppId] = {
    challenge: {
        context: {
            logoImgSrc: 'https://www.perimeterx.com/logos/perimeterx.svg',
            messageText: 'Please verify you are a human',
            messageColor: '#C71028',
            messageFontSize: '28px',
        },
        translation: {
            "default": {
                btn: 'Press and Hold',
            },
        },
        view: {
            fillColor: "#C71028",
            backgroundColor: "#EEEEEE",
            borderColor: "#000000",
            borderRadius: 10,
            borderWidth: 2,
            css: ["https://fonts.googleapis.com/css?family=Acme&display=swap"],
            textFont: "Acme",
            textColor: "#000000",
            texSize: 22
        }
    }
};

Which results with:

Configuration

Callback Function

Add the _pxOnCaptchaSuccess callback function to the window object (mostly used for [Advanced Blocking Response (ABR)](https://docs.perimeterx.com/pxconsole/docs/advanced-blocking-response implementation). The function is called when the Challenge is solved, and returns a single parameter indicating if it was solved successfully or not:

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

📘

Note

If you wish to add the callback to a mobile app challenge (for example, React Native webview), use the _pxOnMobileCaptchaSuccess callback instead of _pxOnCaptchaSuccess. The callback signature and usage are identical.

Post solve behavior

After a valid Captcha solve, if the callback function is defined, we will simply call it. In case the callback function is not defined, the Captcha will execute its default behavior, which usually means a simple page reload. The only exception is when a "url" query-param is included in the page URL, in which case the page will change its URL instead (relative URL is supported). Note that the value of the "url" param is expected to be in base64 (e.g. "https://www.example.com?url=YWJj" will redirect to "https://www.example.com/abc").

Captcha Form

The Captcha form allows your customers to report an issue they are having solving the challenge. The Captcha form is included in the PerimeterX default Block Pages.

To localize the form, refer to the Localizing section.

Enforcers

The updated challenge page is supported on the following enforcer versions:


Did this page help you?