Invisible Captcha

Introduction#

You can get all the bot-blocking benefits of hCaptcha without explicitly rendering our checkbox widget. hCaptcha client/server interactions occur in the background, and the user will only be presented with a hCaptcha challenge if that user meets challenge criteria.

Invisible vs. Passive#

hCaptcha supports both invisible and passive modes, and they can be combined for a seamless user experience.

  • "Invisible" means no checkbox is used. For example, clicking Submit on a form to trigger hCaptcha token generation can use the "invisible" mode by setting this option as described below.

  • "Passive" means no visible challenge is ever shown, i.e. purely passive mechanisms for humanity verification are used. This is set via the sitekey's difficulty level.

Enterprise users can combine "Invisible" (no checkbox) configuration with "Passive" difficulty to avoid any user interruption. However, note the tradeoff: this comes at the cost of reducing the protection level compared to our active challenge modes.

For both Pro and Enterprise users, an additional hybrid mode is available:

  • "99.9% Passive" mode will selectively challenge users based on an evaluation derived from thousands of factors. This attempts to minimize challenges to real people to less than 0.1% of users while increasing the costs of an attack in virtually all cases.
info

Enterprise users: please see the Understanding Scores and Modes section for more details on configuring passive modes and selective challenges.

note

To ensure you are in compliance with the online privacy laws coming into force around the world, please include the following text and links on the page that includes an invisible hCaptcha:

This site is protected by hCaptcha and its
<a href="https://www.hcaptcha.com/privacy">Privacy Policy</a> and
<a href="https://www.hcaptcha.com/terms">Terms of Service</a> apply.

You may also wish to integrate a disclosure into your Privacy Policy similar to the one here. Note that this is not legal advice, and you should consult with counsel in the jurisdictions in which you operate if you have further questions about your specific use case.

Automatically bind the challenge to a button#

The easiest way to do this is to assign an .h-captcha class to any button or input. Like before, you must add your site key in a data-sitekey attribute assigned to the <button> element. Additionally, all of the data-* attributes are applicable here.

<button class="h-captcha" data-sitekey="your_site_key" data-callback="onSubmit">
Submit
</button>

Just as before, the response-token will be sent to the callback function upon successful completion of the hCaptcha challenge. If you attached the invisible hCaptcha to a submit button, you must specify a data-callback to handle form submission. In most cases, you will want to use the callback to manually submit the form.

<script type="text/javascript">
function onSubmit(token) {
document.getElementById('my-form').submit();
}
</script>

Programmatically bind the challenge to a button or invoke the challenge#

This works without change from the explicit rendering of the hCaptcha widget described here. The only difference is that if the data-size="invisible" is present, the widget will be rendered in the background and only presented when a challenge is required.

Programmatically invoke the challenge#

If you would prefer to invoke the hCaptcha workflow via a JavaScript trigger (in cases like a checkbox click, or a page load), you'll need to use the hcaptcha.execute(widgetID) function to trigger that process on a given widgetID.

For more information on the hcaptcha.execute function and the widgetID argument, you can read more on the JavaScript API section of the configuration page

Example#

Start hCaptcha process in defined div container, with onclick trigger on button

<html>
<head>
<script>
function onSubmit(token) {
alert('thanks ' + document.getElementById('field').value);
}
function validate(event) {
event.preventDefault();
if (!document.getElementById('field').value) {
alert('You must add text to the required field');
} else {
hcaptcha.execute();
}
}
function onload() {
var element = document.getElementById('submit');
element.onclick = validate;
}
</script>
</head>
<body>
<form>
Name: (required) <input id="field" name="field" />
<div
id="hcaptcha"
class="h-captcha"
data-sitekey="your_site_key"
data-callback="onSubmit"
data-size="invisible"
></div>
<button id="submit">submit</button>
</form>
<script>
onload();
</script>
</body>
</html>