"Protected by HUMAN" Challenge
The challenge widget is a Captcha tool for BotGuard for Applications customers to protect input forms.
The primary function of the widget is that it will disable/lock all buttons inside the <form>
within which it is
deployed until the user successfully toggles the widget. Once the widget is successfully toggled, all buttons inside
the form will be re-enabled, allowing for Login,Submit and functions to be used.
Checkbox Display
Detection Tag Configuration
To enable this feature, the detection tag needs to have a new argument &captcha=1
appended to the URL.
Example Detection Tag
<script src="https://[domain]/2/[ci]/clear.js?ci=[ci]&pd=acc&mo=2&spa=1&captcha=1"></script>
Placing the Challenge Widget on Page
To place the widget into a form to protect, add a <div>
with the class attribute "human-captcha".
Example Div
<div class="human-captcha"></div>
This div can contain any other attributes, as long as it is a member of this class the captcha tool will be deployed inside the scope of the div. Only the first instance of a div with this class found on page will render a challenge widget and engage the protection mechanism.
Custom Captcha
A custom Captcha can be supported. However, it must adhere to these requirements:
- Must have an
id
attribute on the element that is unique in the DOM. - The Captcha must be interactive, an event that is dispatched by the Captcha must be provided.
- For example: an
input
element dispatches achange
event when a user interacts with the element.
- For example: an
Custom Captcha Configuration
To integrate a custom Captcha Challenge, the Detection Tag includes a function to register the tag. To enable the feature, you must udpate your tag query to param to captcha=2
.
This exposes the function registerCaptcha
to the $$$
interface. In order to validate the captcha with the Detection Tag, this function must be invoked with the required id
and action
when the Captcha is rendered in the DOM. This fn returns a callback fn to invoke when the Captcha has been completed.
Register the Custom Captcha
Example of setting up a custom Captcha:
Inside the HTML, set up a Captcha as follows:
<div class="captcha">
<div class="captcha-wrapper">
<label for="control">Verify if you are human</label>
<input
name="captcha-control"
class="captcha-control"
id="captcha-control"
type="radio"
value="captchaToggle"
/>
</div>
</div>
For the Captcha challenge depicted above, invoke the following to register your Captcha:
// The unique id of the element that you expect to experience user interaction
const id = "captcha-control";
// An event that should be dispatched when a user interacts with the control
const action = "change";
// Register the Captcha, returns a callback fn to invoke when the Captcha is completed
const onComplete = window.$$$.registerCaptcha(id, action);
// ...When finished, make a call to declare that the Captcha is completed
onComplete();