Friendly Captcha

Key Features

• Adds a Friendly Captcha field to Gravity Forms under Advanced Fields
• Verifies captcha responses server-side through the Friendly Captcha v2 API
• Supports Global and EU verification endpoints
• Validates the site key and API key when settings are saved
• Provides global widget theme and start-mode settings
• Allows theme and start mode to be overridden per field
• Supports standard, AJAX, and multipage Gravity Forms
• Optionally disables the submit button until the challenge is complete
• Optionally accepts submissions when Friendly Captcha returns an HTTP 400 or 401 configuration error
• Loads frontend assets only on forms containing a Friendly Captcha field
• Prevents captcha response tokens from being stored in Gravity Forms entries
• Supports translatable user-facing messages

Requirements

• WordPress 6.5+
• PHP 7.4+
• Gravity Forms 2.9.24+
• A Friendly Captcha account
• A Friendly Captcha v2 site key
• A Friendly Captcha API key

Installation

1. Copy the plugin directory to:/wp-content/plugins/gravityformsfriendlycaptcha  Alternatively, upload the plugin ZIP through Plugins → Add New → Upload Plugin.
2. Ensure Gravity Forms is installed and active.
3. Activate Gravity Forms Friendly Captcha Add-On.
4. Open Forms → Settings → Friendly Captcha.
5. Enter and save your Friendly Captcha site key and API key.

Using the Add-On

A typical setup is:

1. Create an application and site key in the Friendly Captcha dashboard.
2. Create a Friendly Captcha API key.
3. Save both credentials under Forms → Settings → Friendly Captcha.
4. Edit a Gravity Form.
5. Add the Friendly Captcha field from Advanced Fields.
6. Optionally customize the field theme, start mode, or validation message.
7. Save and test the form.

Only one Friendly Captcha field can be added to each form.

For multipage forms, place the field on the final page so the challenge is completed immediately before submission.

Plugin Settings

Location:

Forms → Settings → Friendly Captcha

Site Key

The site key identifies the Friendly Captcha application associated with the form widget.

Create a site key from the Applications section of the Friendly Captcha dashboard.

API Key

The API key authenticates server-side verification requests to Friendly Captcha.

Create an API key from the API Keys section of the Friendly Captcha dashboard.

The API key is entered through a password-style field and is used only for server-side requests.

The add-on validates the site key and API key together when settings are saved. Both credentials must be configured before the field can be used.

Default Widget Settings

Theme

Controls the default widget appearance:

• Auto — follows the visitor’s preferred color scheme
• Light
• Dark

The default is Auto.

Start Mode

Controls when the widget begins solving the challenge:

• Focus — starts when the visitor interacts with the form
• Auto — starts automatically
• None — waits to be started manually

The default is Focus.

API Endpoint

Select the Friendly Captcha verification region:

• Global
• EU

Choose the endpoint appropriate for the Friendly Captcha application and data-residency requirements.

Advanced Settings

Accept Configuration Errors

When enabled, the add-on accepts a submission if Friendly Captcha returns an HTTP 400 or 401 configuration or authentication error.

This fail-open behavior does not apply to general network failures, unexpected responses, or other HTTP errors.

Leave this disabled when submissions should always be rejected if verification cannot be completed.

Disable Submit Until Complete

When enabled, form submit buttons remain disabled until the Friendly Captcha widget reports that its challenge has completed.

The buttons are disabled again if the response expires or the widget reports an error.

Server-side verification is still performed when the form is submitted.

Field Settings

Select the Friendly Captcha field in the form editor to configure its standard Gravity Forms settings and the following add-on-specific options.

Field Theme

Overrides the global theme for this field:

• Use Global Default
• Auto
• Light
• Dark

Field Start Mode

Overrides the global start mode for this field:

• Use Global Default
• Focus
• Auto
• None

Custom Validation Message

Use the standard Gravity Forms Custom Validation Message setting to replace the default message displayed when Friendly Captcha validation fails.

Verification Behavior

When a protected form is submitted:

1. The browser submits the Friendly Captcha response token with the form.
2. The add-on sends the token and configured site key to the selected Friendly Captcha v2 siteverify endpoint.
3. The API key is included in the authenticated server-side request.
4. The form is accepted when Friendly Captcha reports successful verification.
5. The form displays a validation error when the response is missing, invalid, expired, already used, or cannot be verified.

Verification is synchronous, so Friendly Captcha response time can affect form-submission response time.

The captcha token is a display-only value and is not stored in the Gravity Forms entry.

Failure Behavior

By default, the form is not submitted when:

• Friendly Captcha credentials are missing
• The challenge has not been completed
• The response is invalid
• The response has expired
• The response has already been used
• The site key or API key is invalid
• The verification request fails
• Friendly Captcha returns an unexpected response

A custom validation message configured on the field takes precedence over the default error message.

If the fail-open setting is enabled, HTTP 400 and 401 configuration errors are accepted. Other verification failures continue to block submission.

External Services

The add-on communicates with Friendly Captcha to:

• Load the Friendly Captcha browser SDK
• Validate configured credentials
• Verify submitted captcha responses

Frontend SDK assets are loaded from jsDelivr. Server-side verification requests are sent to the selected Friendly Captcha Global or EU endpoint using the WordPress HTTP API.

No captcha response token is saved to the Gravity Forms entry.

Permissions and Security

The add-on defines these Gravity Forms capabilities:

• gravityforms_friendlycaptcha
• gravityforms_friendlycaptcha_uninstall

The settings capability controls access to the add-on settings. The uninstall capability controls access to the Gravity Forms uninstall action.

Additional security behavior includes:

• Server-side verification of every submitted response
• Password-style display for the API key setting
• Sanitization of plugin and field settings
• Escaping of rendered values and user-facing messages
• No storage of captcha response tokens in form entries
• No logging of the API key by the add-on

Known Limitations

• Only Friendly Captcha v2 is supported
• Only one Friendly Captcha field can be added to a form
• Credentials are configured globally rather than per form
• All protected forms use the same site key and API key
• Per-field customization is limited to theme, start mode, and validation-message settings
• Multipage forms should place the field on the final page
• Verification depends on the availability and response time of the Friendly Captcha API
• The optional fail-open behavior applies only to HTTP 400 and 401 responses
• The Friendly Captcha browser SDK is loaded from an external CDN
• This Gravity Labs project is not officially supported