Friendly Captcha Field

Owned by Christo Gogler
Last updated: Sept. 06, 2024 by Stephan Giesen
5 min read

CAPTCHAs are commonly used on websites and online forms to prevent automated bots from abusing or spamming the system.

The Friendly Captcha Field is designed to be a user-friendly and minimally intrusive way to effectively distinguishing between humans and automated bots.

 

 

More info about Friendly Captcha can be found on their official website: Friendly Captcha - Privacy-First Bot Protection

If you haven't already done it, install and setup your project. You can use the umkickstarter.

Continue with creating a new Contact Form instance.

Setting up Friendly Captcha

To actively use Friendly Captcha you will need to register on their website and create an account.

Register here: Signup - Friendly Captcha

Create App & Site key

Once the account is registered you can create a new application.

Bildschirmfoto 2024-02-05 um 09.16.19.png
Bildschirmfoto 2024-02-05 um 09.15.14.png

  • To do so navigate to “Organizations > Organisation > Applications > Create new application”

  • Fill in a name for your app.

  • You can enter a domain for your app optionally.

  • Choose a “Puzzle Endpoint”.

    • Global Endpoint (default)

    • EU Endpoint

  • After successfully creating a new app you will receive a Site key.

 

By default the FriendlyCaptcha widget talks to a global service served from all over the world to retrieve CAPTCHA puzzles. Depending on your user's geography this request may be served from outside the EU.

As a premium feature we offer a dedicated forwarding endpoint hosted in Germany as an additional guarantee that the personal information (i.e. visitor IP addresses) never leave the EU.

Create API Key

Second key needed is the API Key. It is used to prove your identity when verifying puzzle solutions.

 

  • Navigate to “Organizations > Organisation > API Keys > Create API Key”

  • Generate the key.

 

The API Key only shows once. Make sure to copy and save it to a safe space. You will need the API Key later.

Setting up Contact Form Instance

 

  • Navigate to Apps and setup a new instance.

  • You can choose to add the Friendly Captcha Field from the select box on the “Form Wizard” tab.

  • The Friendly Captcha Field gives you several ways to change the functionality and appearance of it. Those options will be explained next.

Site key & Secret key

Fill in the Site key that you created on your Friendly Captcha account.

The secret key and the API key are synonymous. So fill in the API key you received on the Freindly Captcha account.

Both keys can be configured in a properties file as well like this:

cmsbs.friendlyCaptcha.siteKey = "ADD_SITEKEY_HERE" cmsbs.friendlyCaptcha.secretKey = "ADD_APIKEY_HERE"

If you wish to do so the two inputs for Site key & Secret key will be prefilled with those values.

Puzzle Endpoint

The Puzzle Endpoint can be left empty per default. Though if you choose a specific one on your Friendly Captcha Account (e.g. ”EU Endpoint”) then you will need to specify that endpoint here.

Additional CSS classes

If you wish to add specific CSS classes to your Friendly Captcha Field to customize the appearance of it, then you can add those classes here. Those classes will be added to the div-Element containing the Friendly Captcha.

Start mode

Start mode offers three different ways to initiate the Friendly Captcha validation process.

 

  • focus: Friendly Captcha starts as the user focuses an input.

  • auto: Friendly Captcha will start as soon as possible/form is loaded.

  • manually: Friendly Captcha starts when the user presses the button.

Style injection

You can choose to use the built-in Friendly Captcha style or to use a custom style.

If you choose to use your own custom style the Friendly Captcha Field will be rendered very minimally until you add your own CSS.

 

  • Friendly Captcha CSS

 

 

  • custom CSS

    • You can access the Field via the following classes e.g.:

    • frc-captcha, frc-captcha-container, frc-icon, frc-content, etc.

    • You can also add your own additional CSS classes (see above)

Appearance

If you have chosen “Friendly Captcha CSS“ for the previous attribute “Style injection“, then you can choose between a light and a dark theme for the Friendly Captcha Field.

  • Light mode

 

 

  • Dark mode

JavaScript Snippet

The JavaScript Snippet generated in the App instance has to be copied and added to the webpage where the form should be rendered.

If you add a Friendly Captcha Field an additional Script is needed. The JavaScript Snippet will be updated, so you need to copy the snippet again to your webpage.

<script type="module" src="/p/de.pinuts.cmsbs.lib.widget.Pi/fc/v0916/widget.module.min.js" async defer ></script> <script nomodule src="/p/de.pinuts.cmsbs.lib.widget.Pi/fc/v0916/widget.min.js" async defer></script>

The version of the Friendly Captcha has changed with UM version 7.57.0. For UM versions before 7.57.0 use the path /p/en.pinuts.cmsbs.lib.widget.Pi/fc/v094.

Validation Process

When the validation process starts (depends on the value of “Start mode“ you chose) the user will see a progress bar and a success or error message afterwards.

  • Once the validation has started, Friendly Captcha sends a request to Friendly Captcha to solve a puzzle.

  • This happens in the background without any help of the user needed.

  • The solved puzzle will be transmitted with the form submit and validated on the server-side as well.

Proxy Settings

Since UM version 7.51.2, it is possible to use Captchas through a proxy. The configuration for this needs to be added to a file with the extension .properties in the /cmsbs-conf/conf.d directory.

You have the option to define either a global proxy:

cmsbs.proxy = http://username:password@host:port/ # cmsbs.ssl.checks = <none|relaxed|secure>

This setting would apply to various aspects such as downloads/includes in HTML newsletters.

Alternatively, you can specify a proxy specifically for Captchas: