Introduction
Invisible reCAPTCHA Form Element Plugin is used to protect forms developed in Joget DX from spams or abuse from malicious automated bots that are programmed to enter false or irrelevant information into a form, while being as transparent as possible to legitimate users of the platform.
About reCAPTCHA
- reCAPTCHA is a free Google service with the acronym of "Completely Automated Public Turing test to tell Computers and Humans Apart".
- It can identify whether a form is submitted by a real human or a bot.
- For more information about reCAPTCHA, see: https://www.google.com/recaptcha/about/.
Installing the plugin in Joget DX
You can follow the steps below, or refer to Manage Plugins to read more about managing plugins:
- Download invisible-recaptcha-field-7.0.0.jar into your computer
- In the Joget DX platform, go to System Settings > Manage Plugins > Upload Plugin
- Click on Choose File, select the .jar file you just downloaded, and click Upload
Using the plugin in a Form
In the Form Builder, open up any Form that you wish to implement this feature for.
Search the Form Element Palette for the Invisible reCAPTCHA element under the Marketplace section.
Drag and drop this element into your Form.
Click on the element in your form and the Edit Invisible reCAPTCHA panel appears (on the right hand side).
In the Edit Invisible reCAPTCHA configuration, you are required to insert the information for the following fields:
- ID
- reCAPTCHA site key
- reCAPTCHA secret key
Your ID can be any meaningful name you want (e.g.: invisible_recaptcha).
The next section will explain how to generate the required reCAPTCHA site key and reCAPTCHA secret key for this plugin.
Generating important keys for the plugin
You can follow the steps below, or refer to this related guide online:
- Go to https://www.google.com/recaptcha/about/
- Click on v3 Admin Console at the navigation bar
Give your Label a meaningful name (e.g.: recaptcha_test)
For the reCAPTCHA Type, select reCAPTCHA v2 > Invisible reCAPTCHA badge
Under Domains, put the domain name that your Joget DX instance is hosted on.
Setting a domain name
If you are using Joget DX on a local computer for development purposes, you can put "localhost" as your domain name.
- Tick Accept the reCAPTCHA Terms of Service
- Click Submit
Copy the generated reCAPTCHA site keys and reCAPTCHA secret keys, and paste them into their respective fields in the Edit Invisible reCAPTCHA configuration.
Remember to click Apply Change and save the form.
Important reCAPTCHA keys
- Site keys can actually be shown publicly, but it is censored in this example.
- Secret keys must never be shown or shared with anyone, because the server uses it to verify reCAPTCHA responses upon form submission.
Testing out the plugin
Try submitting the form where you added the Invisible reCAPTCHA plugin.
If the bottom right corner of your form shows the protected by reCAPTCHA, it means that the Invisible reCAPTCHA plugin is working as intended.
You can seek help from Errors of the plugin if the Invisible reCAPTCHA plugin is not working as intended.
Errors of the plugin
There are two types of error that may occur when using the Invisible reCAPTCHA plugin:
- reCAPTCHA widget error
- Plugin validation error
What is a reCAPTCHA widget error?
reCAPTCHA widget error occurs when you may have chosen the v2 tickbox option instead of the v2 invisible option.
Remember to choose the v2 invisible option, so that the reCAPTCHA site key is enabled for the Invisible reCAPTCHA.
This is how a reCAPTCHA widget error looks like.
Because of this error, the "Form Submitted" message is not shown on the top left corner of the Form.
What is a Plugin validation error? incomplete
To replicate plugin validation error is very simple, you only have to provide an invalid reCAPTCHA secret key (e.g. changing a letter to a different letter).
image to be inserted here later..
This is how a Plugin validation error looks like.
Because of this error, the error texts are shown on the top left corner of the Form instead of the "Form Submitted" message.
Edit Invisible reCAPTCHA: Other configurations
- Custom error text is returned when there is a Plugin validation error
- Debug mode can be enabled to help app designers indicate what the problem or error is
You can refer to Custom error text & Debug mode sections.
Tip: Hover on the tooltips (? icon) in Edit Invisible reCAPTCHA configuration to read what each configuration properties mean.
Custom error text & Debug mode
What is Custom error text for? incomplete
image to be inserted here later..
Custom error text is designed to be shown to end-users when there is a plugin validation error.
Without using the Custom error text configuration property, the top left corner of your Form will only show "Validation Error" and a default error text of "reCAPTCHA error" when plugin validation error occurs
- Error texts as such do not explain much on what the validation problem is, therefore Custom error text can be used to elaborate the validation problem to end-users
- To produce a meaningful error message or text, you should first understand what a plugin validation error is
What is Debug mode for? incomplete
Enabling Debug mode allows error messages to be printed out for end-users to see.
image to be inserted here later..
Availability of the plugin incomplete
| Form Type | Reason |
|---|---|