How to integrate with a CAPTCHA provider and prevent bot submissions

Our email verification widget allows you to automatically verify email addresses on any HTML page, ensuring that only valid, deliverable emails are accepted in your contact or sign-up form. To achieve this, our widget communicates with our servers using a publishable browser app key - a sequence of alphanumeric symbols used for authentication with our API.

Since the widget operates in the browser, its credentials are intentionally available to the client; we provide several methods to control usage, including restricting IP addresses allowed to submit verifications, limiting the number of submissions per minute, hour, or day, either per IP address or globally and limiting the number of email addresses per single submission.

Starting from version 1.12, the widget can also integrate with CAPTCHA providers to ensure that email verification submissions are performed by humans only: this guards against bots using Verifalia credits or causing throttling restrictions for legitimate users. Verifalia supports the following CAPTCHAs:

• Cloudflare Turnstile
• Google reCaptcha v2
• Google reCaptcha v3
• hCaptcha

To enable bot detection, begin by entering the necessary CAPTCHA service settings (typically the secret key provided by the external CAPTCHA service) into the Bot detection interface for the user or browser app used to authenticate, in the Verifalia client area - this step is necessary to enable communication between Verifalia servers and the configured CAPTCHA service:

Follow the instructions below to connect the widget with your chosen CAPTCHA service.

Cloudflare Turnstile

To enable bot detection using Cloudflare Turnstile:

1. Register for a free Cloudflare Turnstile account at https://www.cloudflare.com/products/turnstile/, if you haven't already.
2. Enter the secret key provided by Cloudflare Turnstile into the Bot detection interface within the browser app running the widget: this key enables communication between Verifalia servers and Cloudflare.
3. Set the captcha.provider configuration property to Turnstile.
4. Add the sitekey provided by Cloudflare Turnstile to the widget configuration using the captcha.siteKey property.
5. Optionally, customize the captcha.language and captcha.containerSelector fields to suit your preferences.

The resulting code may resemble the following:

<script defer src=”...”
    data-verifalia-appkey=”...”
    data-verifalia-captcha-provider="turnstile"
    data-verifalia-captcha-siteKey="0x4AAEM1L3BICKA">
</script>

Once configured, the widget will automatically include the Cloudflare Turnstile script on the hosting page. For further information about Cloudflare Turnstile, visit: https://www.cloudflare.com/products/turnstile/

Google reCAPTCHA v2

To enable bot detection using Google reCAPTCHA v2:

1. Register for a free Google reCAPTCHA account at https://www.google.com/recaptcha/about/ if you don't already have one.
2. Enter the secret key provided by Google reCAPTCHA v2 into the Bot detection interface within the browser app running the widget: this key enables communication between Verifalia servers and Google. You can access this interface in the Verifalia client area.
3. Set the captcha.provider configuration property to reCaptcha_v2.
4. Add the sitekey provided by Google reCAPTCHA v2 to the widget configuration using the captcha.siteKey property.
5. Optionally, customize the captcha.language and captcha.containerSelector fields to suit your preferences.

The resulting code may resemble the following:

<script defer src=”...”
    data-verifalia-appkey=”...”
    data-verifalia-captcha-provider="reCaptcha_v2"
    data-verifalia-captcha-siteKey="809DKSJHDsad7987ad9shKAHLKASL">
</script>

The above step-by-step instructions apply to both checkbox reCAPTCHA and invisible reCAPTCHA.

Invisible reCAPTCHA

In addition to the aforementioned instructions, invisible reCAPTCHA also requires the following:

6. Set a CAPTCHA container element through the captcha.containerSelector field.
7. Add a data-size="invisible" attribute to the CAPTCHA container element.

The resulting code for invisible reCAPTCHA v2 may resemble the following:

<script defer src=”...”
    data-verifalia-appkey=”...”
    data-verifalia-captcha-provider="reCaptcha_v2"
    data-verifalia-captcha-siteKey="612ASG239909asdajKHDSDSAD3877823"
    data-verifalia-captcha-containerSelector="//*[@id='captcha-container']">
</script>

<div id="captcha-container" data-size="invisible"></div>

Once configured, the widget will automatically include the Google reCAPTCHA v2 script on the hosting page. For more information about Google reCAPTCHA v2, visit https://www.google.com/recaptcha/about/

Google reCAPTCHA v3

To enable bot detection using Google reCAPTCHA v3:

1. Register for a free Google reCAPTCHA account at https://www.google.com/recaptcha/about/ if you don't already have one.
2. Enter the secret key provided by Google reCAPTCHA v3 into the Bot detection interface within the browser app running the widget: you can access this interface in the Verifalia client area. This key facilitates communication between Verifalia servers and Google.
3. While in the Bot detection interface, adjust the Score threshold if necessary. reCAPTCHA v3 assigns a score ranging from 0 to 1 for each submission. A score of 0 indicates a high likelihood of being a bot, while a score of 1 suggests a high likelihood of a legitimate interaction. Submissions scoring below your threshold will be treated as robot-generated and will be aborted.
4. Set the captcha.provider configuration property to reCaptcha_v3.
5. Add the sitekey provided by Google reCAPTCHA v3 to the widget configuration using the captcha.siteKey property.
6. Optionally, customize the captcha.language and captcha.containerSelector fields to suit your preferences.

The resulting code may resemble the following:

<script defer src=”...”
    data-verifalia-appkey=”...”
    data-verifalia-captcha-provider="reCaptcha_v3"
    data-verifalia-captcha-siteKey="12ASHGD1230980SDAJSDPO2109388123">
</script>

Once configured, the widget will automatically include the Google reCAPTCHA v3 script on the hosting page. For more information about Google reCAPTCHA v3, visit https://www.google.com/recaptcha/about/

hCaptcha

To enable bot detection using hCaptcha:

1. Register for a free hCaptcha account at https://www.hcaptcha.com/ if you don't already have one.
2. Enter the secret key provided by hCaptcha into the Bot detection interface within the browser app running the widget: you can access this interface in the Verifalia client area. This key facilitates communication between Verifalia servers and hCaptcha.
3. Optionally, also enter the sitekey provided by hCaptcha in the aforementioned Bot detection interface: this step prevents tokens issued on one sitekey from being redeemed elsewhere, according to hCaptcha documentation.
4. Set the captcha.provider configuration property to hCaptcha.
5. Add the sitekey provided by hCaptcha to the widget configuration using the captcha.siteKey property.
6. Optionally, customize the captcha.language and captcha.containerSelector fields to suit your preferences.

The resulting code may resemble the following:

<script defer src=”...”
    data-verifalia-appkey=”...”
    data-verifalia-captcha-provider="hCaptcha"
    data-verifalia-captcha-siteKey="347e3460-7fcb-43c0-bb23-5431f81d3854">
</script>

Once configured, the widget will automatically include the hCaptcha script on the hosting page. For more information about hCaptcha, visit https://www.hcaptcha.com/