Recaptcha3 plugin

Show and validate a Google reCAPTCHA v3
Use the Recaptcha plugin if you are still using Google reCAPTCHA v2

Usage

To use it, you need to register a site and secret keys at reCaptcha admin page.
The following piece of code is the starting point to use the Recaptcha3 plugin:
<html>
<head>
<link rel="stylesheet" href="/vendors/@form-validation/umd/styles/index.min.css" />
</head>
<body>
<form id="demoForm" method="POST">
...
<!-- Prepare a container to show the captcha -->
<div id="captchaContainer"></div>
</form>
<script src="https://cdnjs.cloudflare.com/ajax/libs/es6-shim/0.35.3/es6-shim.min.js"></script>
<script src="/vendors/@form-validation/umd/bundle/popular.min.js"></script>
<script src="/vendors/@form-validation/umd/plugin-recaptcha3/index.min.js"></script>
<script>
document.addEventListener('DOMContentLoaded', function(e) {
FormValidation.formValidation(
document.getElementById('demoForm'),
{
fields: {
...
},
plugins: {
...,
recaptcha3: new FormValidation.plugins.Recaptcha3({
action: ...,
backendVerificationUrl: ...,
element: 'captchaContainer',
language: ...,
message: ...,
siteKey: ...,
}),
},
}
);
});
</script>
</body>
</html>
The sample code above assumes that the FormValidation files are placed inside the vendors directory. You might need to change the path depending on where you place them on the server.

Options

(* denotes a required parameter)
OptionTypeDescription
action *StringThe page action
backendVerificationUrl *StringThe URL of your back-end that verifies the captcha via reCAPTCHA API
element *StringThe ID of element showing the captcha
languageStringThe language code defined by reCAPTCHA
message *StringThe invalid message that will be shown in case the captcha is not valid
minimumScoreNumberA minimum score, between 0 and 1. By default, it's set as 0. The backend verification will be treated as invalid if the returned score doesn't exceed this option. For more information, see the interpreting the score page
siteKey *StringThe site key provided by Google

Using the npm packages

If you are using a bundler such as Webpack, Rollup, Parcel or Vite, etc., to bundle your application, then it's recommended to use the FormValidation NPM packages.
  • Install the packages:
$ npm install @form-validation/bundle
$ npm install @form-validation/plugin-recaptcha3
  • Import and use the Recaptcha3 plugin:
import { formValidation } from '@form-validation/bundle/popular';
import { Recaptcha3 } from '@form-validation/plugin-recaptcha3';
formValidation(
document.getElementById('demoForm'),
{
fields: {
...
},
plugins: {
recaptcha3: new Recaptcha3({
...
}),
...
},
}
);

Basic example

For testing purpose, the back-end verification always indicates that the captcha is valid.
Recaptcha3 plugin

Back-end verification

The plugin also requires verification on the server side. You need to point the backendVerificationUrl option to your back-end URL:
FormValidation.formValidation(
document.getElementById('demoForm'),
{
fields: {
...
},
plugins: {
...
recaptcha3: new FormValidation.plugins.Recaptcha3({
backendVerificationUrl: '/path/to/your/back-end/',
}),
},
}
);
When click the Submit button, the plugin will send an Ajax request with the value for ___g-recaptcha-token___ parameter which is generated by reCAPTCHA. With the value of captcha token and the reCAPTCHA secret key, you can connect to reCAPTCGA verification URL to verify the captcha.
In order to inform user in case the captcha is valid or invalid, the back-end has to return a JSON encoded version of
{
"score": ...,
"success": "true"
}
// or
{
"score": ...,
"success": "false"
}
The score and success can be taken from the response of Google reCAPTCHA v3 API. The following code demonstrates how to do it in PHP, but you can do it with your favorite language.
<?php
// Replace it with your reCAPTCHA secret key
$secretKey = 'YOUR_SECRET_KEY_HERE';
// See https://developers.google.com/recaptcha/docs/verify#api-request
$fields = array(
'secret' => $secretKey,
'response' => $_POST['___g-recaptcha-token___']
);
$postVars = '';
$sep = '';
foreach ($fields as $key => $value) {
$postVars .= $sep . urlencode($key) . '=' . urlencode($value);
$sep = '&';
}
$ch = curl_init();
curl_setopt($ch,CURLOPT_URL, 'https://www.google.com/recaptcha/api/siteverify');
curl_setopt($ch,CURLOPT_POST, count($fields));
curl_setopt($ch,CURLOPT_POSTFIELDS, $postVars);
curl_setopt($ch,CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
// IMPORTANT: $return has to include the "score" property
// In this case, the "score" is included from Google reCaptcha service
$return = json_decode($result, true);
// You can customize the error message based on the score ($return["score"]) such as
// $return["message"] = "The captcha is NOT valid";
curl_close($ch);
header('Content-Type: application/json');
echo json_encode($return);

Using with the Excluded plugin

If you use the Recaptcha3 plugin with the Excluded plugin, you have to include the hidden Recaptcha3 field that has name of ___g-recaptcha-token___.
You can access the name via FormValidation.plugins.Recaptcha3.CAPTCHA_FIELD as well.
In the sample code below, we use the excluded option provided by the Excluded plugin to check if the field is the Recaptcha3 token field or not.
plugins: {
excluded: new FormValidation.plugins.Excluded({
excluded: function(field, ele, eles) {
// Don't excluded the reCaptcha3 field
if (field === FormValidation.plugins.Recaptcha3.CAPTCHA_FIELD) {
return false;
}
// You can add more logics here to exclude or include other fields
return false;
}
}),
recaptcha3: new FormValidation.plugins.Recaptcha3({
...
}),
...
}

Changelog

v2.4.0
v2.0.0
  • Add the npm package
  • Clear loaded callback after uninstalling
v1.6.0
  • Add new minimumScore option. The plugin can return an error message from the backend verification
  • The Recaptcha3 plugin can return an error message from the backend verification
v1.5.0
  • First release. It means that the Recaptcha3 plugin requires FormValidation v1.5.0 or newer