Recaptcha3 plugin
Show and validate a Google reCAPTCHA v3
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">
...
<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)
Option | Type | Description |
---|
action * | String | The page action |
backendVerificationUrl * | String | The URL of your back-end that verifies the captcha via reCAPTCHA API |
element * | String | The ID of element showing the captcha |
language | String | The language code defined by reCAPTCHA |
message * | String | The invalid message that will be shown in case the captcha is not valid |
minimumScore | Number | A 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 * | String | The 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.
$ 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.
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"
}
{
"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
$secretKey = 'YOUR_SECRET_KEY_HERE';
$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);
$return = json_decode($result, true);
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) {
if (field === FormValidation.plugins.Recaptcha3.CAPTCHA_FIELD) {
return false;
}
return false;
}
}),
recaptcha3: new FormValidation.plugins.Recaptcha3({
...
}),
...
}
Changelog
- Add the npm package
- Clear loaded callback after uninstalling
- 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
- First release. It means that the Recaptcha3 plugin requires FormValidation v1.5.0 or newer