Google reCAPTCHA V2 Invisible

reCAPTCHA by Google is a free service that protects your website from spam and abuse. It's designed to be friendly to humans, much more friendly than image-based CAPTCHA. It uses advanced risk analysis techniques to tell humans and bots apart to protect your website from spam.

The invisible reCAPTCHA badge does not require the user to click on a checkbox. Instead, it is invoked directly when the user clicks on an existing button on your site or can be invoked via a JavaScript API call. The integration requires a JavaScript callback when reCAPTCHA verification is complete. By default, only the most suspicious traffic will be prompted to solve a captcha. 

Google reCAPTCHA V2 Invisible badge

Get started

To get started with reCAPTCHA you must first have a Google account.  Once you are logged into Google go to https://www.google.com/recaptcha/admin to register your new website.  The usage of reCAPTCHA is limited to the domains that you register. It's recommended that if you have multiple domains that you register each one separately.

  1. Label - Give a meaningful, but short name that describes your site.
  2. reCAPTCHA type - Choose "reCAPTCHA v2" and then choose "Invisible reCAPTCHA badge".
  3. Domains - Enter the domain or domains that you plan to use reCAPTCHA on.
  4. Owners - this should be your Google account email
  5. Accept the reCAPTCHA Terms of service
  6. Check off the "Send alerts to owners"
  7. Click the "Submit" button.

See the Settings documentation on the Google site for more information.  

Get the API keys

Once you've registered your site you then need to get the API credentials. reCAPTCHA gives you a "Site Key" and "Secret Key"

You will need to copy those to the Google reCAPTCHA V2 Invisible configuration page in BranchCMS.

Integrate into BranchCMS

  1. In BranchCMS click on the "Site Settings" link at the upper right of the administration and then click on "Spam Protection".
  2. Then click on "Configure reCAPTCHA V2 (Invisible reCAPTCHA badge)".
  3. Copy the "Site key" value from the Google reCAPTCHA page and paste it into the "Site Key" field.
  4. Copy the "Secret key" value from the Google reCAPTCHA page and past it into the "Secret Key" field. 

Make sure that if either of those values ends in punctuation that you get the punctuation too. 

Customize the display

When you're setting up the reCAPTCHA integration you can also configure the display options. These values will be the default display choices for all places that reCAPTCHA is used throughout the site. You can, however, override them with each form that uses reCAPTCHA. 

Integrate with your form

Now that reCAPTCHA is setup for your site you can use it on your forms. By default CAPTCHA is disabled on all forms. To enable it edit the form and go to the CAPTCHA tab. 

Pick Captcha Type

Choose "Google reCAPTCHA V2 Invisible" for the "CAPTCHA Type" field. That will show you the status of the reCAPTCHA integration. 

Output the CAPTCHA in the template

There are three ways to invoke the invisible reCAPTCHA in your templates. It's a bit more involved than simply using the {{ form.captcha.tag }} variable.

Testing for CAPTCHA type

You may want to use some logic to display the reCAPTCHA in your templates if there is a chance that a different type of CAPTCHA could be chosen.

The reCAPTCHA V2 Invisible CAPTCHA type is designated by the "recaptchaV2Invisible" value for the form.captcha.type variable.

{% if form.captcha.type == 'recaptchaV2Invisible' %}
   {# Display the Google reCAPTCHA V2 Invisible here #}
{% endif %}

Setting the reCAPTCHA data attributes

There are a few ways that you can set the data attributes such as the data-callback or data-expired-callback attributes. If you set them then they are set on the <div> tag for the programatically invoke the challenge option and the <button> tag that can be used for either of the button options.

Below are examples of the three ways that the data attribute could be set.

{% set form.captcha.data.callback = 'onSubmit' %}
{% do form.captcha.data.set('expired-callback', 'expiredCallback') %}
{% do form.captcha.set('data-error-callback', 'errorCallback') %}

Automatically bind the challenge to a button

The easiest method for using the invisible reCAPTCHA widget on your page is to include the <script> tag to load the Google Javascript file and to add a few attributes to your HTML button.

The required attributes are a class name of g-recaptcha, your site key in the data-sitekey attribute, and the name of the Javascript callback function to handle completion of the CAPTCHA in the data-callback attribute.

{% set form.class = 'myForm' %}
{{ form.openTag }}
   {# Display fields #}
   {% for field in form.fields %}
     <p>{{ field.label.tag }}<br>{{ field.tag }}</p>
   {% endfor %}

   {# Set the callback function #}
   {% set form.captcha.data.callback = 'onSubmit' %}
   <p><button class="{{ form.captcha.class }}" {{ form.captcha.button.dataAttr }}>Submit</button></p>
   <script>
   function onSubmit() {
     document.querySelector('.myForm').submit();
   }
   </script>
   {{ form.captcha.js.tag }}
{{ form.closeTag }}

Programatically bind the challenge to a button

Deferring the binding can be achieved by specifying your onload callback function and adding parameters to the JavaScript resource.

{% set form.class = 'myForm' %}
{{ form.openTag }}
   {# Display fields #}
   {% for field in form.fields %}
     <p>{{ field.label.tag }}<br>{{ field.tag }}</p>
   {% endfor %}

   <p><button>Submit</button></p>
   <script>
   function onSubmit() {
     document.querySelector('.myForm').submit();
   }
   function onloadCallback() {
         grecaptcha.render(document.querySelector(".myCustomCaptcha"), {
            'sitekey': '{{ form.captcha.data.sitekey }}',
            'callback': onSubmit
         });
    }
   </script>
   {% set form.captcha.js.src = form.captcha.js.src ~ '?onload=onloadCallback&render=explicit' %}
   {{ form.captcha.js.tag }}
{{ form.closeTag }}

Programmatically invoke the challenge

Invoking the reCAPTCHA verification programmatically can be achieved by rendering the challenge in a div with an attribute data-size='invisible' and programmatically calling execute.

The {{ form.captcha.tag }} holds the HTML for the <div> tag.

This option requires that grecaptcha.execute() is called in order to validate the CAPTCHA. If that's not called then the form cannot be processed as the required reCAPTCHA value would not be submitted.

Typically the grecaptcha.execute() function is called after the form is validated with Javascript.

{% set form.class = 'myForm' %}
{{ form.openTag }}
   {# Display fields #}
   {% for field in form.fields %}
     <p>{{ field.label.tag }}<br>{{ field.tag }}</p>
   {% endfor %}

   {# Set the callback function #}
   {% set form.captcha.data.callback = 'recaptchaCallback' %}
   {% set form.captcha.button.class = form.captcha.button.class ~ ' myCustomCaptcha' %}
   <p>{{ form.captcha.button.tag }}</p>
   <script>
   function recaptchaCallback() {
     document.querySelector('.myForm').submit();
   }
   function onloadCallback() {
      grecaptcha.render(document.querySelector(".myCustomCaptcha"));
   }
   function validate(event) {
      event.preventDefault();
      if (!document.getElementById('field').value) {
        alert("You must add text to the required field");
      } else {
        grecaptcha.execute();
      }
   }
   </script>
   {% set form.captcha.js.src = form.captcha.js.src ~ '?onload=onloadCallback' %}
   {{ form.captcha.js.tag }}
{{ form.closeTag }}