Pular para o conteúdo
ALTCHA ALTCHA ALTCHA

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.

For more examples, see How To documentation.

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.

The get_ip_country function returns null by default, as no IP resolution mechanism is included. You can use the altcha_get_ip_country filter to enable more accurate geolocation based on the user’s IP address instead of their timezone. See Country Detection for more details.

  • $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_inject

apply_filters("altcha_inject", $inject, $bypass);

Called in the script injector. Returning false prevents the ALTCHA scripts from being added to the page.

  • $inject (bool): whether ALTCHA scripts are currently set to be injected
  • $bypass (bool): true if a bypass condition has been triggered (e.g., logged-in user, whitelisted IP, or valid bypass cookie)

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).

Special Configuration

Some plugins require special configuration to ensure they work correctly with ALTCHA. This usually involves disabling specific actions or paths that use Ajax requests.

The following configuration is applied by default if these plugins are detected during ALTCHA activation. To customize it, adjust the Actions and/or Paths under Settings.

  • Forminator

    • !forminator_get_nonce: Excludes the action used for fetching a new nonce.

  • Elementor Pro

    • !elementor_js_log: Elementor performs Ajax logging; whitelist this action.

  • MetForm

    • !/wp-json/metform/v1/forms/views/*: Excludes MetForm’s statistics path.

  • Real Cookie Banner

    • !/wp-json/real-cookie-banner/v1/consent: Excludes the main cookie consent Ajax path.
    • !/wp-json/*/consent: Excludes cookie consent Ajax paths (RCB may also use randomly generated paths).

  • WooCommerce

    • !wc-ajax=*: Excludes all WooCommerce Ajax actions.
    • !wc-api=*: Excludes all WooCommerce webhooks and api actions.
    • !*_wc_privacy_cleanup: Excludes internal “cleanup” actions.
    • /wp-json/wc/store/v1/checkout: Protects the checkout path.
    • !/wp-json/wc/store/v1/*: Excludes all other WooCommerce Ajax paths.

  • Wordfence

    • !wordfence_ls_authenticate: Excludes 2FA verification Ajax action.

  • wpDiscuz

    • !wpdCheckNotificationType: Excludes the wpDiscuz notification action triggered after submitting a comment.

Country Detection

The plugin determines the user’s country based on their timezone, as reported during the verification process. This method provides reliable, privacy-friendly geolocation without relying on any IP address resolution service.

Geolocation data is used for event logging and firewall request blocking.

For more precise geolocation, you can use the altcha_get_ip_country filter to implement your own IP resolution logic or integrate with another plugin’s API.

Cookies and GDPR

The ALTCHA for WordPress plugin utilizes only strictly necessary, first-party cookies that are essential for the proper operation of the website and its security mechanisms. These cookies are used solely for technical and security-related purposes and do not involve user profiling, behavioral tracking, or cross-site data sharing. No personally identifiable information (PII) is stored or processed through these cookies.

In accordance with Article 6(1)(f) of the General Data Protection Regulation (GDPR), the use of such cookies is based on the legitimate interest of the website operator to ensure the security, integrity, and reliable operation of online forms and web access.

Essential Security Cookie:

  • altcha: A single-use, functional cookie required for validating legitimate form submissions and preventing spam or automated abuse. This cookie is transient and does not contain any personal data.

Temporary Protection Cookies (used only when “Under Attack Mode” is enabled):

  • altcha_under_attack: A session-based cookie used to temporarily manage access during periods of increased malicious activity or automated attacks.
  • altcha_under_attack_expires: A session cookie that records the expiration timestamp of the altcha_under_attack cookie.
  • altcha_under_attack_ttl: A session cookie that records the lifespan (time-to-live) of the altcha_under_attack cookie.
  • altcha_under_attack_tz: A session cookie that stores the user’s timezone, used exclusively for low-precision country detection.

All cookies set by ALTCHA:

  • Are first-party and stored exclusively on the user’s device by the website domain;
  • Are strictly necessary for the operation and security of the website;
  • Are temporary and automatically expire after their intended security purpose is fulfilled;
  • Do not collect, transmit, or process personal or behavioral data;
  • Are therefore exempt from the consent requirement under Article 5(3) of the ePrivacy Directive (Directive 2002/58/EC, as amended).

API Caching

The plugin fetches a unique challenge from:

/wp-json/altcha/v1/challenge

This AJAX endpoint must be excluded from caching by CDN proxies or caching plugins. Some providers — including WP Engine — may also strip or ignore cookies, so ensure that your CDN excludes the altcha cookie from caching.

Under Attack Mode with CDN

Most CDN providers already offer DDoS protection or rate limiting at the CDN layer, making the plugin’s Under Attack mode generally unnecessary.

If you still choose to use Under Attack mode with a CDN, additional configuration may be required depending on the provider:

  • WP Engine: Exclude the following cookies from caching:

    • altcha_under_attack
    • altcha_under_attack_tz

    Be aware that excluding these cookies causes WP Engine to bypass caching entirely. For this reason, using Under Attack mode on WP Engine is not recommended.

  • Other providers: Most CDNs and proxies that follow caching standards and respect Cache-Control headers do not require any additional configuration.