reCAPTCHA setup
Description
With reCAPTCHA you can bot-proof your forms by ensuring that they're filled out by humans. TERMINALFOUR offers reCAPTCHA validation on all the forms you create with Form Builder. There are reCAPTCHA FAQs here.
For a general overview of reCAPTCHA, check out the Google Guide.
To enable reCAPTCHA in TERMINALFOUR, the reCAPTCHA v2 Site key and Secret key are required. If you are already using a Google product on your site, like Google Analytics or Google Tag Manager, you'll need access to the Google Admin account you use for that. Otherwise, you'll have to set up an account.
Register a new site
If you have not registered your site, log in to Google and go to the Google reCAPTCHA admin panel.
Complete the options under "Register a new site" and choose reCAPTCHA v2. reCAPTCHA v2 requires the user to click a checkbox indicating the user is not a robot.
| Item | Description |
|---|---|
| Label |
Enter a description to help identify the site in the future, e.g., website-name. This is optional. Choose the type of reCAPTCHA, |
| Choose the type of reCAPTCHA |
Select reCAPTCHA v2 and Checkbox, The following reCAPTCHA types are not supported:
|
| Domains |
The domains / subdomains that the forms using reCAPTCHA will appear under should be registered without the protocal (http(s)://) and should end with the Top Level Domain (TLD), i.e., .ed, .com, .org, .net, etc E.g., https://testdomain.com/contact.php would be invalid. The correct domain would be testdomain.com. You should also include the domain of the Form Bank URL when configuring the Google reCAPTCHA. This is highlighted in the accompanying screenshot. If you want to test reCAPTCHA locally, then you can use the key from any domain as all API keys work on localhost (127.0.0.1). See the Google Guide on Domain/Package Name Validation for further information. |
| Send alerts to owners | Check this if you want Google to send you a report if it there is a problem with reCAPTCHA on your site |
Site key and Secret key
On the next screen you can scroll to the Keys section of the page:
Copy the Site key and Secret key.
Only one reCAPTCHA key pair can be added to FORM Builder in your Terminalfour instance.
You'll need both of these so keep this tab open.
Form Builder Settings
In another tab, open Terminalfour and go to System administration > System settings > Form Builder to complete the configuration.
Use the switch to enable reCAPTCHA across your site(s). When reCAPTCHA is enabled in the settings, a reCAPTCHA option will be available in Form Builder under Advanced Inputs. Paste the Site and Secret keys into the text boxes.
When "enforcement" is enabled, reCAPTCHA is added to every form, so you do not add it. If you want to select the forms that reCAPTCHA is added to, then you should disable "enforcement."
If you choose to add reCAPTCHA to all forms, you will not see the "Create fields from content type" option. This is because "Create fields from content type" is only available when there are no form elements present in a form.
When you create a new form or editing an existing form, the display of the reCAPTCHA field will change, depending on the combination of enable and enforcement settings you choose.
| reCAPTCHA is disabled | reCAPTCHA is enabled and not enforced | reCAPTCHA is enabled and enforced |
|---|---|---|
| The reCAPTCHA button is not visible on any of your forms | The reCAPTCHA button is visible under advanced inputs when selecting fields but is not clickable | |
| One reCAPTCHA field can be added to the form |
||
| The reCAPTCHA field, if added will be positioned before the submit /reset buttons and it is not possible to move it |
||
| It is possible to delete the reCAPTCHA field | It is not possible to delete the reCAPTCHA fieldAdding a | |
Adding reCAPTCHA to your form when reCPATCHA is enabled and not enforced:
Adding reCAPTCHA to your form when reCPATCHA is enabled and is enforced:
When enforcement is disabled, forms that had a reCAPTCHA explicitly added before enforcement was enabled will still have a reCAPTCHA field. Forms that had a reCAPTCHA because enforcement was enabled will not have a reCAPTCHA field.
reCAPTCHA FAQ
How many reCAPTCHA key pairs can be added?
One reCAPTCHA key pair can be added.
How can I add more than one domain?
Multiple domains can be added to one site key in Google. Please include the domain of the Form Bank URL when configuring the Google reCAPTCHA.
Which users can configure the reCAPTCHA?
Administrator users can configure the reCAPTCHA at System administration > System settings > Form builder.
Can a reCAPTCHA be shared?
Sharing is not required as only one reCAPTCHA is configured per installation.
Can the Google site type be specified?
The site type reCAPTCHA v2 is used.
How is the widget rendered?
The widget is explicitly rendered.
Do I need to specify the language code?
There is no need to set the language code as Google will set the language based on the user's browser.
How do I ensure reCAPTCHA is set on all forms?
Administrator users can configure "enforcement" so that the reCAPTCHA will show on all forms. This is configured at System administration > System settings > Form builder.
Where on the form will the reCAPTCHA be displayed?
It will be displayed before the Submit button in all cases. It is not possible to reorder the position of the reCAPTCHA.
How is the reCAPTCHA response processed?
The response is verified via an API request to https://www.google.com/recaptcha/api/siteverify.
What logic is applied to the "hostname" data in the API response?
The logic is based on the "success" property in the API response.
If the "success" response is true, the response token is set as a value in the submission so it can be submitted.
If the "success" response is false, the user is brought the the failure error message / page specified for the form. No response token is sent so the submission is not submitted. The API request error code can be seen in the POST request, via the developer console.