Google reCAPTCHA V3

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.

reCAPTCHA v3 allows you to verify if an interaction is legitimate without any user interaction. It is a pure JavaScript API returning a score, giving you the ability to take action in the context of your site.

Validating the request

When you call grecaptcha.execute() to validate the user Google will return a string token. That token should then be populated into a hidden form field and submitted with the form. The BranchCMS system will then verify the token by contacting Google with the reCAPTCHA API keys. Google will return a response that indicates whether or not the token validated and a score based on the information Google gathered about the request. If the score is equal to or higher than the minimum allowed score that you configure when you set up the reCAPTCHA then the form submission will be accepted. If the score is lower than the minimum score then the submission is rejected and an error message is returned to the form to indicate that the reCAPTCHA validate was not successful. 

See the Output the CAPTCHA in the template section for more information.

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 v3".
  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 V3 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 V3".
  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. 

Set the default action

Google reCAPTCHA V3 requires that an action is set when the reCAPTCHA is executed. You can set the default action to use with forms. This value is used with the Javascript code that is outputted with the {{ form.captcha.tag }} variable.

Integrate with your form

Now that reCAPTCHA is set up 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 V3" for the "CAPTCHA Type" field. That will show you the status of the reCAPTCHA integration. 

Template variables

The following template variables are available for Google reCAPTCHA V3

Variables Description
form.captcha.action

The reCAPTCHA page action to record.

You set a default action for all uses of the reCAPTCHA V3 when you configure it.

form.captcha.error

The error message if the reCAPTCHA does not validate.

form.captcha.errorCode

The error code if the reCAPTCHA does not validate.

form.captcha.failed

Boolean value on whether or not the reCAPTCHA validation failed.

form.captcha.input

The hidden form field that will hold the reCAPTCHA token to submit with the form. This has to be within the opening and closing form fields.

It will be automatically outputted with the {{ form.captcha.tag }} variable. Or, you can output it directly with the {{ form.captcha.input.tag }} variable.

If you use {{ form.captcha.input.tag }} do not also use {{ form.captcha.tag }} as the field will then be included twice.

form.captcha.isUsable

A boolean value on whether or not the reCAPTCHA V3 has been set up and enabled.

form.captcha.js

The Google reCAPTCHA Javascript file that needs to be loaded onto the page.

You can manipulate it by changing the {{ form.captcha.js.src }} value.

{% set form.captcha.js.src = form.captcha.js.src ~ '&callback=myCallback' %}

The <script> tag to output the Javascript file is automatically included in the {{ form.captcha.tag }} variable. Or, you can output it directly with the {{ form.captcha.js.tag }} variable.

If you use {{ form.captcha.js.tag }} do not also use {{ form.captcha.tag }} as that will cause the Javascript file to be loaded twice.

You can also set it to be outputted with other Javascript files.

{% do _page.addJs(form.captcha.js.src) %}

form.captcha.script

This holds the default Javascript that will be outputted with the {{ form.captcha.tag }} variable. It includes a Javascript Promise that will execute the reCAPTCHA to validate the form.

form.captcha.script.function

This holds the Javascript Promise function name that your code will need to use to call the Javascript Promise when the form is submitted. The name is randomly generated each time the page loads.

form.captcha.sitekey

This holds the Google reCAPTCHA API site key.

form.captcha.tag

This will output the default reCAPTCHA tag. It includes the hidden form field that holds the reCAPTCHA token and the Javascript Promise that will execute the reCAPTCHA.

form.captcha.type

This holds the reCAPTCHA type. For reCAPTCHA V3 the value is "recaptchaV3".

Output the CAPTCHA in the template

Google reCAPTCHA V3 is different from the other reCAPTCHA types in that it requires more manual Javascript to make it work. The {{ form.captcha.tag }} variable will output some default Javascript that can be used to integrate the CAPTCHA into your form. You can, however, do your own custom implementation if you want.

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 V3 CAPTCHA type is designated by the "recaptchaV3" value for the form.captcha.type variable.

{% if form.captcha.type == 'recaptchaV3' %}
   {# Output the Google reCAPTCHA V3 #}
{% endif %}

Use the default Javascript

The easiest method for using reCAPTCHA V3 with your form is to make use of the default output from the {{ form.captcha.tag }} variable. That will output the following:

  • A hidden form field to hold the reCAPTCHA token.
  • Some Javascript that will set up a Javascript Promise that needs to be used to execute the reCAPTCHA when the form is submitted.
{% set form.class = 'myForm' %}
{{ form.openTag }}
   {# Display fields #}
   {% for field in form.fields %}
     <p>{{ field.label.tag }}<br>{{ field.tag }}</p>
   {% endfor %}
   <p><button type="submit">Submit</button></p>
   {{ form.captcha.tag }}
{{ form.closeTag }}
<script>
/**
 * Intercept the form submit event. Then execute the reCAPTCHA and when that is successful submit the form.
 * You may want to modify this and incorporate it in your form validation.
 */
var form = document.querySelector('.myForm');
form.addEventListener('submit', function(e) {
    e.preventDefault();
    {# Call the Javascript Promise function to execute the reCAPTCHA #}
    {{ form.captcha.script.function }}(grecaptcha).then(function() {
      form.submit();
    });
});
</script>

Javascript function parameters

The Javascript Promise function that is outputted from the form.captcha.script.tag and form.captcha.tag accepts two parameters.

  1. The grecaptcha object. This required value should be available as a global variable after the Google Javascript file is included on the page. You should not have to change this value.
  2. The optional options object.

Below are the options that can be passed to the options parameter.

Option Description
action

The Google reCAPTCHA action to set. You would use this if you wanted to set the action in your Javascript. By default the default action set when the reCAPTCHA was configured in the administration is used. You could also set the action in the Twig code.

{% set form.captcha.action = 'myAction' %}

Below is how you would set the action in your Javascript.

{{ form.captcha.script.function }}(grecaptcha, {action: 'myAction'});

setField

This is a boolean value for whether or not to set the reCAPTCHA token as the value for the reCAPTCHA hidden input field. It defaults to true.  If you're using this code for a form submission then you should probably just leave this as true.

{{ form.captcha.script.function }}(grecaptcha, {setField: false});

Custom implementation

If you have unique needs for your forms you can use the different CAPTCHA template variables and your own custom Javascript to execute the reCAPTCHA. You must execute the reCAPTCHA and populate the hidden form field with the token value before the form is submitted. If you don't then the form will not validate and be processed.

{% set form.class = 'myForm' %}
{{ form.openTag }}
   {# Display fields #}
   {% for field in form.fields %}
     <p>{{ field.label.tag }}<br>{{ field.tag }}</p>
   {% endfor %}
   {{ form.captcha.input.tag }}
   <p><button type="submit">Submit</button></p>
{{ form.closeTag }}
{# Set the Javascript file to load asynchronously and to be deferred. This is optional and it helps with performance. #}
{% set form.captcha.js.async = true %}
{% set form.captcha.js.defer = true %}
{{ form.captcha.js.tag }}
<script>
/**
 * Intercept the form submit event. Then execute the reCAPTCHA and when that is successful submit the form.
 * You may want to modify this and incorporate it in your form validation.
 */
var form = document.querySelector('.myForm');
form.addEventListener('submit', function(e) {
    e.preventDefault();
    grecaptcha.execute('{{ form.captcha.sitekey }}', {action: '{{ form.captcha.action }}'}).then(function(token) {
      document.querySelector('.{{ form.captcha.input.class }}').value = token;
      form.submit();
    });
});
</script>

Including Google reCAPTCHA on other pages

Google recommends that you include the reCAPTCHA V3 code on all pages of your website so that they have more information about someone's traffic and if they are a bot.

It's recommended that when you set a custom reCAPTCHA action that is different from the default one used for the forms. That way when you're reviewing the reCAPTCHA analytics in the Google reCAPTCHA admin you can view the top actions and their scores.

A common approach is to include the code to output the reCAPTCHA V3 code in a Snippet that is outputted near the closing </body> tag. Using the Snippet centralizes the code and outputting it near the closing </body> tag helps with performance and rendering. 

Because you may be including this snippet on a page that has a form protected by Google reCAPTCHA you'll want to make sure that you're not including the Google Javascript file multiple times. Use the _page.hasJs() tag to test for the existence of some registered Javascript code. This allows you to only include the Javascript code if it hasn't already been included for a form. If the reCAPTCHA is being used to protect a form on a page then there is no reason to also include the reCAPTCHA code on the page to register a page action.

{% if _core.service.recaptchaV3.isUsable %}
    {% if _page.hasJs('recaptchaV3') == false %}
        {# You can set a custom action. #}  
      {% set _core.service.recaptchaV3.action = 'myAction' %}
      {% do _page.registerJs('recaptchaV3') %}
      {{ _core.service.recaptchaV3.js.tag }}
      {{ _core.service.recaptchaV3.script.tag }}
   {% endif %}
{% endif %}

The reCAPTCHA code is accessed through the _core.services.recaptchaV3 variable. You should only use this to include the reCAPTCHA code on a page outside of a form. Within a form you should continue to use the form.captcha variables.

The _core.services.recaptchaV3 variable is an array that holds the same information that the form.captcha variable does. The major difference is that the Javascript code to call grecaptcha.execute() is automatically run.

Including reCAPTCHA in your form and on the page

You will also want to adjust your form template code that outputs the reCAPTCHA Javascript to use a similar method of testing for existing registered Javascript code.

{% set form.class = 'myForm' %}
{{ form.openTag }}
   {# Display fields #}
   {% for field in form.fields %}
     <p>{{ field.label.tag }}<br>{{ field.tag }}</p>
   {% endfor %}
   <p><button type="submit">Submit</button></p>
   {% if _page.hasJs('recaptchaV3') == false %}
      {# Include the hidden input tag, reCAPTCHA Javascript file and the Javascript promise function #}
      {{ form.captcha.tag }}
      {% do _page.registerJs('recaptchaV3') %}
   {% else %}
      {# Only output the hidden input tag as the reCAPTCHA Javascript file and the Javascript promise function have already been included on the page. #}
      {{ form.captcha.input.tag }}
   {% endif %}
{{ form.closeTag }}
<script>
/**
 * Intercept the form submit event. Then execute the reCAPTCHA and when that is successful submit the form.
 * You may want to modify this and incorporate it in your form validation.
 */
var form = document.querySelector('.myForm');
form.addEventListener('submit', function(e) {
    e.preventDefault();
    {# Call the Javascript Promise function to execute the reCAPTCHA #}
    {{ form.captcha.script.function }}(grecaptcha).then(function() {
      form.submit();
    });
});
</script>