How Do I Integrate My Plugin with Solid Security reCAPTCHA?

Integrating your plugin with Solid Security is a simple process. In this article, we cover how to display and validate the reCAPTCHA.

Solid Security fires the itsec_recaptcha_api_ready hook when it is time for plugins to set up their Recaptcha integrations. At this point, Solid Security has already verified that the site administrator has configured their access tokens. You can also check if the API is available by calling ITSEC_Recaptcha_API::is_available().

Technical Details: This happens during WordPress’ init hook on the standard 10 priority.

Displaying the reCAPTCHA

To display the reCAPTCHA, simply call the ITSEC_Recaptcha_API::display() function. If the API is not available, an empty string will be displayed.

You don’t need to worry about fetching API keys or choosing whether to display reCAPTCHA V2 or Invisible reCAPTCHA, Solid Security handles all of that.

For example:

function my_plugin_display_recaptcha() {
	ITSEC_Recaptcha_API::display();
}
add_action( 'my_login_form_template', 'my_plugin_display_recaptcha' );

Technical Details: The Recaptcha field requires JavaScript to work properly. The show_recaptcha() method will automatically enqueue the necessary scripts. If you are loading your form via Ajax, you might need to manually print these scripts. Call wp_print_scripts() aftercalling the show_recaptcha() method.

By default, the V2 reCAPTCHA badge has 10 pixels of margin on the top and bottom. You can customize this by using the margin option.

For example:

ITSEC_Recaptcha_API::display( array( 'margin' => array( 'top' => '20' ) ) );

This will change the top margin to 20 pixels and leave the rest of the margins as their default values. You can completely disable the margin by passing null to the option.

Validating the reCAPTCHA

If your plugin ends up calling the authenticate filter, typically by calling the wp_signon() or wp_authenticate() functions or posting your login form directly to wp-login.php, then Solid Security will automatically pick up that the reCAPTCHA was submitted.

Likewise, for the registration form, if you use the register_new_user() function, Solid Security will work transparently.

Alternatively, if you have a custom login or registration form, or a completely different use case, you can call the validation function directly.

function my_plugin_do_login() {
	$validated = ITSEC_Recaptcha_API::validate();

	if ( is_wp_error( $validated ) ) {
		// Show error message.
		return false;
	}
	// User submitted the Recaptcha. Continue with custom login.
}

This will look in the post variables for g-recaptcha-response. This will work automatically when using Recaptcha in a standard HTML Form context.

If this value won’t be populated when calling the validate() function, when using a GET form, for instance, you should manually set $_POST['g-recaptcha-response'] to the captcha value.

Solid Security does not currently support passing the response code directly to the validate() function.

Technical Details: The validation result is cached for the duration of the request. If Google’s Recaptcha API is temporarily unavailable, Solid Security will treat the validation as successful.