Invisible reCAPTCHA Form Element Plugin

Introduction

The Invisible reCAPTCHA Form Element Plugin protects forms developed in Joget DX from spam and abuse by malicious automated bots. This plugin enhances security while remaining transparent to legitimate users.

Get started

Where to get the plugin

You can download the plugin from the GitHub repository.

How to install

1. Download the .jar file from the provided link.
2. In your Joget DX8 platform, go to System Settings > Manage Plugins > Upload Plugin.
3. Click Choose File, select the downloaded .jar file, and click Upload.

How to use it

1. Open the Form Builder and select the form where you want to implement the Invisible reCAPTCHA.
2. From the Form Element Palette, locate the Invisible reCAPTCHA element under the Marketplace section.
3. Drag and drop the element into your form.
4. Click on the element to open the Edit Invisible reCAPTCHA panel on the right.
   

Configure invisible reCAPTCHA properties

In the configuration panel, fill out the following fields:

• ID: A unique identifier for the element (e.g., invisible_recaptcha).
• reCAPTCHA site key: Obtain this key from the reCAPTCHA Admin Console.
• reCAPTCHA secret key: Obtain this secret key from the reCAPTCHA Admin Console.

Below, Generating Important Keys for the Plugin will explain how to generate the required reCAPTCHA site key and reCAPTCHA secret key for this plugin.

Generating important keys for the plugin

To generate the necessary keys:

1. Go to the reCAPTCHA website.
2. Click the v3 Admin Console.
3. Give your Label a meaningful name (e.g., recaptcha_test)
4. For the reCAPTCHA Type, select reCAPTCHA v2 > Invisible reCAPTCHA badge.
5. Under Domains, put the domain name on which your Joget DX8 instance is hosted.
   
   Setting a domain name
   If you are using Joget DX8 on a local computer for development purposes, you can put localhost as your domain name.
6.  Check Accept the reCAPTCHA terms of service and click Submit.
   
7. Copy the generated reCAPTCHA site key and reCAPTCHA secret key, and paste them into their respective fields in the Edit Invisible reCAPTCHA configuration.
   
8. Click Apply Change and save the form.
   

   Important reCAPTCHA keys

   • Site keys can be shown publicly, which is censored in this example.
   • Secret keys must never be shown or shared with anyone because the server uses them to verify reCAPTCHA responses upon form submission.

Testing the plugin

Submit the form to which you added the Invisible reCAPTCHA plugin. If the bottom-right corner of your form shows that it is protected by reCAPTCHA, the Invisible reCAPTCHA plugin works as intended.

If the Invisible reCAPTCHA plugin is not working as intended, you can seek help from Plugin Error Troubleshooting below.

Plugin error troubleshooting

Two types of errors may occur when using the Invisible reCAPTCHA plugin:

reCAPTCHA widget error

This issue occurs when the widget fails to function properly. For example, selecting the wrong reCAPTCHA type can cause this issue, and you may have chosen the v2 tickbox option instead of the v2 invisible option.
Remember to choose the v2 invisible option to enable the reCAPTCHA site key for the Invisible reCAPTCHA.

This is a reCAPTCHA widget error. Because of this error, the form will not be submitted.

Plugin validation error

This issue occurs when the plugin can't perform backend validation to verify the user who has submitted the form. For example, to replicate a Plugin validation error, you only have to provide an invalid reCAPTCHA secret key.

You can change a letter to a different letter or make up a reCAPTCHA secret key that does not exist.

For now, let's see what will happen if you do not add a Custom error text, and you disable the Debug mode.

Following the configurations demonstrated, the Plugin validation error has been replicated:

• "Validation Error" is printed out to show app designers that the validation has failed
• "reCAPTCHA error" is a default error text printed out if no Custom error text is added
• protected by reCAPTCHA widget does not show a red error message like what happened in reCAPTCHA widget error.

In this case, Debug mode is disabled so that you will see the default error text.

However, note that if Debug mode is enabled, you will not see either the default or Custom error text (even if you have added it).

Custom error text & debug mode

• Custom Error Text: You can display a custom message when a validation error occurs.
• Debug Mode: Displays debug information in the server logs. When enabled, custom error messages won't appear on the form.

What is custom error text for?

To demonstrate what the Custom error text and Debug mode are used for, once again, the reCAPTCHA secret key is made invalid to replicate the Plugin validation error.

In this example, the Custom error text is set as Invalid reCAPTCHA secret key: Please ensure your secret key is valid!.

For now, the Debug mode needs to be disabled to show the Custom error text at the top left corner of the Form.

Remember to click Apply Change and save the form. 

Now you can see how Custom error text works.

The Custom error text is printed instead of the default error text.

You see Invalid reCAPTCHA secret key: Please ensure your secret key is valid! instead of reCAPTCHA error.

Now that we have seen how Custom error text works, the next section explains Debug mode.

What is debug mode for?

With the same invalid reCAPTCHA secret key and Custom error text, Debug mode is enabled this time.

Remember to click Apply Change and save the form.

Notice that enabling Debug mode does not print out the Custom error text, even though it is being added.

Instead, the top left corner of the Form shows two error messages:

• [reCAPTCHA DEBUG MODE ENABLED!] states that Debug mode is enabled to warn app designers that additional error info is available in the server log
• reCAPTCHA error: invalid-input-secret states that the reCAPTCHA secret key is invalid

Availability of the plugin

The Invisible reCAPTCHA plugin will only work in some situations.

• Normal Form: Only a single plugin can exist and work as intended. Multiple plugins can be loaded into a single Normal Form, but only the first plugin will function.
• Sub-Form: A plugin cannot work as intended in a Sub-Form but can work in the Base Form.
• CRUD Datalist "New" and CRUD Datalist "Edit": Has identical performance and outcomes with the Normal Form and Sub-Form:
  • The Normal Form that CRUD Datalist represents only allows a single plugin to work in it, even though multiple plugins can still be loaded into it
  • The Sub-Form that CRUD Datalist represents only allows the plugin to work in its Base Form

Download plugin

Download the Invisible reCAPTCHA Form Element Plugin from the GitHub repository.