Knowledge Base

reCAPTCHA setup

Last Modified:
25 Jan 2019
User Level:
Administrator +

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.

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 your site has not been registered, log in to Google and go to the Google reCAPTCHA admin panel.

Complete the options under "Register a new site" ensuring that reCAPTCHA v2 is chosen. reCAPTCHA v2 requires the user to click a checkbox indicating the user is not a robot.

Screenshot of the reCAPTCHA register screen

ItemDescription
Label 

enter a description that will allow you to 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
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 on the accompayning 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 when it detects problems with your site 
   .

 

Site key and Secret key

On the next screen you can scroll to the Keys section of the page:

Screenshot of the Google API Site and Secret key boxes

Copy the Site key and Secret key. 

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.

Enable reCAPTCHA and paste the Site and Secret keys into the text boxes:

Screenshot of he Form Builder settings with reCAPTCHA enabled

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
    • The reCAPTCHA button is not visible on any of your forms
  • reCAPTCHA is enabled and not enforced
    • The reCAPTCHA button is visible under advanced inputs when selecting fields
    • 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

Animated GIF showing how a reCAPTCHA element is added with Form Builder

  • reCAPTCHA is enabled and enforced
    • The reCAPTCHA field is positioned before the submit /reset buttons and it is not possible to move it
    • The reCAPTCHA button is visible under advanced inputs, but is not clickable
    • It is not possible to delete the reCAPTCHA field

Screenshot showing Form Builder with enforced reCAPTCHA

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. The following Site types are not supported: Invisible reCAPTCHA, reCAPTCHA Android, reCAPTCHA V1.

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.