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
_pxTranslationobject to your page. You must set the language to show in thewindow._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:
| Language | Value |
|---|---|
| Arabic | ar |
| Bengali | bn |
| Chinese (Simplified) | zh-CN |
| Chinese (Traditional) | zh-TW |
| Danish | da |
| Dutch | nl |
| English | en |
| French | fr |
| German | de |
| Greek | el |
| Gujarati | gu |
| Hebrew | he |
| Hindi | hi |
| Hungarain | hu |
| Indonesian | id |
| Italian | it |
| Japanese | ja |
| Korean | ko |
| Persian | fa |
| Polish | pl |
| Portuguese | pt |
| Romanian | ro |
| Russian | ru |
| Spanish | es |
| Tamil | ta |
| Thai | th |
| Vietnamese | vi-VN |
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
_pxOnMobileCaptchaSuccesscallback 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:
Updated 3 months ago