Pular para o conteúdo

Este conteúdo não está disponível em sua língua ainda.

Advanced Usage with WordPress Plugin

The ALTCHA WordPress plugin automatically protects your site right after installation, with no extra setup required.

This guide covers advanced topics and custom integrations for developers and power users who want more control.

Secure Context (HTTPS)

ALTCHA requires a Secure Context (HTTPS) to perform verification. Make sure you access and test your website over HTTPS — localhost is an acceptable exception because browsers treat it as a secure origin.

If you need to test from another device on your local network (for example a mobile phone), you can either set up HTTPS on the device, or use one of these testing workarounds:

  • log in as an admin to bypass verification, or
  • whitelist the device’s local IP address to bypass verification.

Shortcode

In most cases, it’s best to rely on the automatic Request Interceptor, which works without any configuration.

However, if you prefer, you can manually add the ALTCHA widget to your forms using a shortcode:

[altcha]

Shortcode attributes are also supported. See the ALTCHA Widget configuration options:

[altcha floating auto="onload"]

Custom Handlers

With the automatic Request Interceptor, server-side verification is handled seamlessly—no code changes required.

For custom form handlers, you can work directly with the AltchaPlugin class:

$altcha = AltchaPlugin::$instance;
$params = array();
$verified = $altcha->verify($payload, $params);
  • $payload: the base64-encoded ALTCHA payload.
  • $params: automatically populated with additional parameters from the salt.

When using ALTCHA Sentinel, verification data is available via:

  • $params["verification_data"]
  • or $altcha->verification_data (parsed into an associative array of key-value pairs).

Hooks

The plugin provides several actions and filters for customization.

Actions

altcha_verify_result

do_action("altcha_verify_result", $verified);

Triggered after ALTCHA verification.

  • $verified (boolean): whether the verification succeeded.

Filters

altcha_get_complexity

apply_filters("altcha_get_complexity", $result);

Called in get_complexity(). Allows modification of the challenge’s min/max numbers.

  • $result (array): array("max" => 0, "min" => 0)

altcha_get_challenge_url

apply_filters("altcha_get_challenge_url", $challenge_url);

Called in get_challenge_url(). Can override the widget’s challenge URL.

  • $challenge_url (string)

altcha_get_ip_address

apply_filters("altcha_get_ip_address", $ip);

Called in altcha_get_ip_address(). Can override the user’s IP address.

  • $ip (string)

altcha_get_ip_country

apply_filters("altcha_get_ip_country", null, $ip);

Called in altcha_get_ip_country(). Can override the detected country code.

  • $result (string|null): 2-letter ISO code
  • $ip (string)

altcha_get_widget_attrs

apply_filters("altcha_get_widget_attrs", $attrs);

Called in get_widget_attrs(). Can override widget attributes.

  • $attrs (array)

altcha_get_widget_html

apply_filters("altcha_get_widget_html", $html, $attrs, $wrap);

Called in get_widget_html(). Can modify the widget’s HTML.

  • $html (string)
  • $attrs (array)
  • $wrap (boolean)

altcha_intercept

apply_filters("altcha_intercept", $intercept, $payload_data, $params);

Called in the interceptor. Returning false disables interception (verification not required).

  • $intercept (boolean): defaults to true
  • $payload_data (array): parsed ALTCHA payload
  • $params (array): additional parameters from the challenge salt

Plugin Integrations

Thanks to the Request Interceptor, ALTCHA works automatically with most form plugins — no setup required. The widget is displayed as an overlay or invisibly in the background.

The plugin has been tested with several popular plugins, but works many others:

  • CoBlocks
  • Contact Form 7
  • Elementor Pro
  • Formidable Forms
  • Forminator
  • Fluent Forms
  • Gravity Forms
  • HTML Forms
  • MetForm
  • Ninja Forms
  • WooCommerce
  • WP-Members
  • wpDiscuz
  • WPForms
  • WordPress Comments
  • WordPress Login, Register, and Password Reset

Some plugins also include additional integrations for direct widget placement:

  • Elementor Pro: adds a dedicated widget field.
  • Formidable Forms: adds a dedicated widget field.
  • Gravity Forms: adds a dedicated widget field and stores submissions flagged as spam (Sentinel only).

Cookies

ALTCHA for WordPress plugin uses only strictly functional, non-identifying, first-party security cookies. For full GDPR compliance, these should be mentioned in your privacy policy:

  • altcha: single-use cookie used to protect form submissions.

When Under Attack Mode is active, the following temporary cookies are also used:

  • altcha_under_attack: short-lived session cookie used for site access protection.
  • altcha_under_attack_expires: short-lived session cookie storing the expiration time of the altcha_under_attack cookie.
  • altcha_under_attack_ttl: short-lived session cookie storing the lifespan of the altcha_under_attack cookie.
  • altcha_under_attack_tz: short-lived session cookie storing the user’s timezone.