Challenge Widget

The VerifiedVisitors challenge widget helps protect your site from bots, spam, and other forms of abuse. It can be integrated into web pages similarly to traditional CAPTCHAs, and does not require a full integration to function.

The challenge widget executes a non-interactive challenge which collects additional telemetry about the browser, it's environment, and visitor behaviour. If detected as automated, the visitor is then presented with an interactive challenge.

Widget configuration

Before you can deploy a widget you must create a new configuration in the widgets page. This will generate a sitekey and secret for use in client-side rendering and server-side validation respectively.

Domain validation

You can specify up to 5 hostnames for each widget. This prevents the widget from being used on unauthorised domains.

Hostnames will automatically include subdomain variations.

Example:

Hostname	Allowed domains
example.com	example.com, subdomain.example.com
app.example.com	app.example.com, subdomain.app.example.com

Client-side rendering

The VerifiedVisitors widget is managed by the JS agent. Once loaded, the widget is rendered within the element with the vv-widget class.

<script
    async
    defer
    src="https://resources.verifiedvisitors.com/vvfp.min.js"
></script>
<!-- ... -->
<div class="vv-widget" data-sitekey="YOUR_SITE_KEY"></div>

Once the challenge successfully completes, a response token is produced for use in server-side verification. This token is passed into a callback function or inserted as a hidden field when embedded in a form.

Configuration

Specifying a callback function

A callback function can be set using the data-callback attribute, which will then be invoked with the response token when the challenge successfully completes.

<!-- Implicit rendering example with callback -->
<div
    class="vv-widget"
    data-sitekey="YOUR_SITE_KEY"
    data-callback="widgetCallback"
></div>

<script>
    function widgetCallback(response) {
        console.log(`Got token: ${response}`)
    }
</script>

Embedding as part of a form

When embedded into a form, a hidden field will be appended to the form with the name vv-widget-response, and will contain the response token when the challenge is complete.

<!-- Implicit form rendering example -->
<form action="" method="POST">
    <input type="text" name="email" />
    <div class="vv-widget" data-sitekey="YOUR_SITE_KEY"></div>
    <input type="submit" value="Submit" />
</form>

Invisible mode

The widget can be made invisible by setting the data-size attribute to invisible. In this mode, the widget runs is fully passive and invisible to the end-user, and interactive challenges will not be presented.

<div class="vv-widget" data-sitekey="YOUR_SITE_KEY" data-size="invisible"></div>

onload callback

A callback can be specified to be invoked when the widget has initialised. This can be set using the onload query parameter when loading the JS Agent.

<script
    async
    defer
    src="https://resources.verifiedvisitors.com/vvfp.min.js?onload=onLoad"
></script>
<!-- ... -->
<script>
    function onLoad() {
        console.log('widget is ready!')
    }
</script>

Error handling

An error handling callback can be set using the data-error-callback attribute, which will then be invoked with an error code as the first parameter when an error occurs.

If the error callback is not set, the widget will throw an exception when an error occurs. Otherwise, the error is logged if the callback function returns a falsy result.

<div
    class="vv-widget"
    data-sitekey="YOUR_SITE_KEY"
    data-error-callback="errorCallback"
></div>
<script>
    function errorCallback(error) {
        console.error(`Got error: ${error}`)
    }
</script>

Error Code	Description
invalid-sitekey	The provided sitekey is invalid
invalid-data	The visitor sent invalid data during the challenge
challenge-expired	The visitor took too long to solve the challenge
internal-error	The challenge widget encountered an internal error

JavaScript API

The widget exposes an API on the verifiedvisitors object.

verifiedvisitors.execute()

Trigger a new widget challenge. This is automatically called after the widget has initialised, but is useful in cases where the token has expired.

verifiedvisitors.getResponse()

Returns the current response token.

Server-side validation

Response tokens must be checked with our API from your backend to ensure their validity. These can be retrieved using a callback or from the vv-widget-response field if embedded into a form.

Tokens are only valid once, and have a lifespan of 5 minutes. The sitekey associated with the response must be associated with the secret used to verify the token.

A truthy success value indicates that the visitor bearing the token has successfully completed the challenge.

curl 'https://api.verifiedvisitors.com/vac/siteverify' \
    -X POST \
    -d 'response=RESPONSE_TOKEN&secret=YOUR_SECRET'

{
    "success": boolean,         // Token is valid and challenge was completed
    "challenge_ts": timestamp,  // ISO timestamp of when the challenge was solved
    "hostname": string,         // Hostname where the challenge was solved
    "error-codes": string[]     // List of errors that occurred
}

Error codes

Error Code	Description
invalid-input-secret	Your secret key is invalid
invalid-input-response	The response token is invalid
timeout-or-duplicate	The response token has expired or was already used