Skip to main content

Friendly CaptchaNew in 5.15.10+

Freeform includes an integration for Friendly Captcha.

​Overview

This integration uses Friendly Captcha v2. The Friendly Captcha widget is loaded and handled automatically by Freeform when the integration is enabled for a form. The widget is inserted above the submit button(s).

​Widget Mode

Which interaction users see (one-click, zero-click, smart) is configured per application in the Friendly Captcha dashboard, not in Freeform. That design prevents visitors from weakening the captcha by changing client-side settings.

​Risk Intelligence

When Risk Intelligence is enabled on your Friendly Captcha account, verification responses can include risk scores. Freeform stores a short summary (for example Overall 2/5, Network 1/5, Browser 3/5) on spam submissions so you can review them in the control panel.

​Setup Instructions

1

​Create a Friendly Captcha application

  • Open the Friendly Captcha dashboard.
  • Select an existing application or create a new one:
    • Click on Applications on the left navigation.
    • Click the New application button.
    • Name the application, e.g. Freeform and click Next.
    • For Use-cases, choose something like Contact under Forms, then click Next.
    • Review the app and click Create application.
    • On the next page that loads, copy the Sitekey, e.g. FCXXXXXXXXXXXXXX.
2

​Create a Friendly Captcha API Key

  • Click on Keys on the left navigation.
  • Click the New API Key button.
  • Name the API key, e.g. Freeform and click Generate API key.
  • Copy the API Key provides on the next step, e.g. A1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.
    • API keys are shown only once. Copy them securely.
3

​Set up Integration on your site

  • Go to the Integrations section in Freeform Settings (Freeform → Integrations).
  • Find Friendly Captcha in the list of service providers.
  • In the Site Key and API Key settings, paste in the Sitekey and API Key values from the Friendly Captcha site.
4

​Additional Configuration

  • Complete the rest of the following optional fields (these will only be the default value when configuring the integration in the form builder later):
    • Only load Captcha scripts once the user interacts with the form?
    • Failure Behavior - set to Display Error Message or Send to Spam Folder.
      • Error Message - set a custom error message if using Display Error Message failure behavior.
    • Start Mode - when the puzzle starts (Auto, Focus, None).
    • Theme - set to Auto, Light or Dark.
    • Language - leave blank for auto-detection, or set a 2-letter code such as en, de, fr.
  • Click the Save button.
5

​Configure the Form

To use this integration on your form(s), you'll need to configure each form individually.

  • Visit the form inside the form builder.
  • Click on the Integrations tab.
  • Click on Friendly Captcha in the list of available integrations.
  • On the right side of the page:
    • Enable the integration.
    • Adjust any of the settings as needed.

​Behavior & Overrides

The following options are available for adjusting the behavior of Friendly Captcha and overriding at the template-level.

​Disabling Captchas

To disable Captchas per form at template level, add the disableCaptcha: true parameter to the Form query.

​Manual Placement

If you need full control over the placement of the visible Friendly Captcha captcha, please see the Captcha Placement guide.

​Add Attributes to Wrapper

You can add attributes to the main Captcha wrapper that is automatically inserted by Freeform.

{{ form.render({
    captchas: {
        class: ["custom-class", "another-class"],
        "data-test": true,
    }
}) }}

​Content Security Policy (CSP)

If your site sends a Content-Security-Policy header, allow Friendly Captcha's iframe origin. See Friendly Captcha's documentation: Content Security Policy (CSP) (typically frame-src for *.frcapi.com). Freeform bundles the widget SDK with its scripts so you do not need to allow an extra script CDN for Freeform's captcha bundle.

​Testing

Use the Friendly Captcha Playground to preview widget behavior. Production widget mode and some options are controlled in the Friendly Captcha dashboard, not in the playground's UI on your site.

Page Feedback