"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

image01

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 a change event when a user interacts with the element.

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();