Implementing and Testing reCAPTCHA v3 in Your Front-End

In this guide, I will walk through how to setup reCAPTCHA v3 in your front-end web application, how to test it locally, as well as some notes and considerations which I came across while implementing reCAPTCHA v3.

If you want to read on the differences between reCAPTCHA v2 and v3, check out my other article.

Simple Setup for reCAPTCHA v3

Google’s reCAPTCHA v3 docs gives a pretty good run-through of the simple implementation of reCAPTCHA v3. You can use the example from the docs to create a simple implementation like this:

To get a site key, you’ll need to register your site from the reCAPTCHA console. However, since you need to provide a domain for the reCAPTCHA configuration, your page will need to be served from somewhere.

For local development, we can set ‘localhost’ as the domain on the reCAPTCHA console and serve the page locally (more on this in the next section). But when you register your live production site, make sure it is separate to your local development site, otherwise someone could locally generate a reCAPTCHA token to use with your back-end services.

Developing and Testing reCAPTCHA on Localhost

(This section is also applicable to reCAPTCHA v2)

To develop and test your reCAPTCHA implementation locally, you’ll need to have it served to your localhost. I do this by using Express, which requires Node and NPM.

Once you’ve set up Node and NPM, go to your project directory and run

npm init
npm install express --save

Once you have installed Express, you’ll want to create a simple Express server that will serve you your HTML, as such:

Then, you can run it with

node local-server.js

Now you should be able to open your browser and go to http://localhost:3000/your-page.html and see your reCAPTCHA token being logged out to the console.

You can use something like Postman to call https://www.google.com/recaptcha/api/siteverify and verify your token.

So now you have a simple setup of reCAPTCHA that you can develop and tinker with. However, there are still a couple things left to note.

Notes, Considerations, Gotchas

While the reCAPTCHA v3 docs gives a simple and easy, there are a couple things that is not mentioned in the reCAPTCHA v3 docs.

Removing the badge

Sometimes you might not want to show the small reCAPTCHA overlay, whether its because it visually clashes with the design of your page, or for some other reason. Fortunately, removing the badge is allowed, as long as you substitute it with an alternate text disclaimer.

However, if you decide to hide it, Do Not use:

.grecaptcha-badge { display: none; }

Instead, use:

.grecaptcha-badge { visibility: hidden; }

Capturing grecaptcha Errors and Custom Timeouts

It may be useful to consider wrapping your

Default handling for anchor error

If for some reason, certain calls to Google’s services fail, such as the call to https://www.google.com/recaptcha/api2/anchor, there will be an error message appended to a<div> at the end of your html. Here is an example of what it looks like on Google’s reCAPTCHA site (note the bottom of the page):

Example of https://www.google.com/recaptcha/api2/anchor Failing, with a message at the foot of the page.

While it may look somewhat reasonable on Google’s reCAPTCHA page, it may not look as clean on your page. To improve this handling, you’ll need to use the https://www.google.com/recaptcha/api.js?render=explicit setup, which I will go through in the next section.

Explicit Render Setup for reCAPTCHA v3

This is where things gets more complicated. The explicit render setup required a bit of combined knowledge from reCAPTCHA v2 and v3. Essentially, it will look something like this:

There a few things happening here:

• Instead of the site key, we’re setting ‘explicit’ in the ‘render’ query param.
• With the explicit render, we need to pass a function to the ‘onload’ query param, which will be the callback function that runs when the reCAPTCHA API has finished loading.
• In your onload callback, you will need to call grecaptcha.render with two arguments. The first argument can either be a string of the id of the element where you want reCAPTCHA to live, or a reference to the DOM element itself. The second argument is a configuration object for reCAPTCHA. At minimum, the configuration object requires your site key and ‘size: invisible’.
• Since we are explicitly rendering our reCAPTCHA implementation, we can now also pass a callback function to handle errors in reCAPTCHA being rendered. Doing so means we will no longer have the default handling for anchor error appending a message to our DOM, as mentioned earlier.

Also, now that you have explicitly declared where to render reCAPTCHA in your DOM, if you want to hide reCAPTCHA (as per the Removing the badge section above), you will be able to easily target and hide the whole reCAPTCHA element. So instead of:

.grecaptcha-badge { visibility: none; }

You can do:

.my-recaptcha-element { visibility: hidden; }

This will make sure nothing will be displayed from the reCAPTCHA element that you aren’t expecting.

This is all for now. Thanks for reading, and I hope this has been as useful :) I will update this if I come across any other interesting considerations to keep in mind when implementing reCAPTCHA v3.

Photo by Frank Wang on Unsplash