Google reCAPTCHA

Google reCAPTCHA scores each submission to a form you protect, with no puzzle to solve, and blocks the ones that look like bots. It works with score-based (v3) keys only. Install and activate XPAC Forms first.

Connect Google reCAPTCHA

Admins can see both keys on this screen. It also has:

• Score threshold: submissions scoring at or below this are blocked. Scores run from 0.0 (likely a bot) to 1.0 (likely a person). Default 0.5, from 0.1 to 0.8.
• Hide the reCAPTCHA badge: shows Google's required notice under each protected form instead of the floating badge.

Google includes 10,000 checks a month for free. Above that, turn on billing for the key's Google Cloud project, or Google lets every submission through for the rest of the month. Admins see a notice when that happens.

Add it to a form

Edit the form, open Anti-spam protection and turn on Google reCAPTCHA. If a key is missing, the editor warns that the form blocks every submission. Google's script loads only on pages with a protected form, and it contacts Google from the visitor's browser, so cover it in your privacy notice.

When a submission is blocked

reCAPTCHA only checks submissions. It doesn't send them anywhere, so it never appears on the Deliveries screen.

A submission is accepted only when Google scores it above your threshold and the check ran on this site's own domain. Otherwise:

• Low score: the visitor sees your Spam rejection message (XPAC → Forms → Settings → Messages).
• The check couldn't finish: missing keys, an expired check, a check from another domain, or no reply from Google in 5 seconds. The visitor is asked to try again, or told the form isn't set up correctly. Each check works once, so it isn't retried.
• Google's script is blocked by an ad blocker or consent tool: the visitor sees "The spam check couldn't load in this browser. Allow google.com or accept cookies, then reload the page." Nothing is sent. If the script takes over 30 seconds, the visitor sees an error and can submit again.

Blocked submissions go to the Spam view when Keep submissions marked as spam is on, and send no email or integration. Every scored submission, blocked or not, shows its score in the reCAPTCHA score column, which helps you tune the threshold.

Admins see a notice on Forms screens and XPAC settings when Google says the keys are over their free quota, when Google turns checks away for too many requests, or after 20 failed checks in a row with none passing. That last one often means the site key and secret key come from different keys. Each admin can dismiss it.

A site that answers on more than one domain, such as with and without www, has to list the others with the filter below, or their submissions are blocked.

For developers

add_filter('xpac_google_recaptcha_allowed_hostnames', function ($hosts) {
	$hosts[] = 'www.example.com';

	return $hosts;
});

Return false from xpac_forms_enable_verification for the provider google-recaptcha to skip the check. Forms Auto Submit does this, because a link has no browser to get a token in.

Setup problems are written to the PHP error log with the prefix XPAC google-recaptcha:, and so is each low-score block, with its score and the threshold.

Settings are saved in the xpac option as recaptcha_v3_site_key, recaptcha_v3_secret_key, recaptcha_v3_score_threshold and recaptcha_v3_disable_badge. Each form's toggle is under googleRecaptcha in its form_settings meta.