Filter und Hooks

Das Procaptcha-Plugin führt neue WordPress-Filter und Hooks ein, die es Ihnen ermöglichen, sein Verhalten anzupassen.

1. CAPTCHA-Sichtbarkeit

Standardmäßig wird Procaptcha nur nicht autorisierten Benutzern angezeigt.

Um dieses Verhalten zu steuern, können Sie neben den Plugin-Einstellungen auch den is_captcha_present-Hook verwenden. Um beispielsweise Procaptcha für alle erforderlich zu machen, fügen Sie folgenden Code zur functions.php-Datei Ihres Themes hinzu:

add_filter('prosopo/procaptcha/is_captcha_present', '__return_true');`

2. Benutzerdefinierte Fehlermeldung

Sie können die Standard-Fehlermeldung anpassen, indem Sie diesen Code zur functions.php-Datei Ihres Themes hinzufügen:

add_filter('prosopo/procaptcha/validation_error_message', function (string $message): string {
    return __('Custom error message', 'my-theme');
});

3. Anpassen von Procaptcha-Attributen

Über die Stilpräferenzen in den Plugin-Einstellungen hinaus können Sie alle unterstützten Procaptcha-Datenattribute mit dem prosopo/procaptcha/captcha_attributes-Filter anpassen.

add_filter('prosopo/procaptcha/captcha_attributes', function (array $attributes): array {
    $attributes['language'] = 'de';
    return $attributes;
});

4. Abgleich der Besucher-IP

Der IP-Abgleich gilt nur für Site Keys, bei denen die IP-Validierung im Prosopo-Portal aktiviert ist (ab dem Professional-Tarif). Procaptcha vergleicht dann die IP, von der das CAPTCHA gelöst wurde, mit der IP, die Ihr Server sendet – nach den Regeln, die Sie im Portal festlegen (Wechsel von Land, Stadt, Anbieter und Entfernung). Dafür muss das Plugin die echte IP des Besuchers senden, deshalb ist die Einstellung standardmäßig aus: Bei Websites hinter Cloudflare oder einem anderen Proxy sieht der Server die Adresse des Proxys, und würde diese gesendet, lehnte die IP-Validierung echte Besucher ab.

Zum Einschalten öffnen Sie Einstellungen > Prosopo Procaptcha > General und wählen unter Abgleich der Besucher-IP, woher die IP des Besuchers stammt:

An – Website läuft hinter Cloudflare: der Header CF-Connecting-IP.
An – Website läuft hinter einem anderen Proxy: die erste Adresse im Header X-Forwarded-For.
An – Besucher verbinden sich direkt: REMOTE_ADDR.

Wählen Sie nur einen Header, den Ihr Proxy setzt, da Besucher diese Header selbst senden können. Fehlt der Header oder ist er keine gültige IP-Adresse, wird nichts gesendet und das Token ohne IP-Abgleich verifiziert.

Für andere Konfigurationen erhält der Filter prosopo/procaptcha/visitor_ip die IP aus der Einstellung (leer, wenn sie aus ist) und REMOTE_ADDR. Geben Sie die zu sendende IP zurück oder einen leeren String, um keine zu senden:

add_filter('prosopo/procaptcha/visitor_ip', function (string $ip, string $remote_addr): string {
    return $_SERVER['HTTP_TRUE_CLIENT_IP'] ?? $ip;
}, 10, 2);

Version 1.23.0 hat standardmäßig REMOTE_ADDR gesendet. Wenn Ihr Site Key die IP-Validierung nutzt und Ihre Website hinter einem Proxy läuft, aktualisieren Sie auf 1.24.0 oder neuer.

5. Verifizierungsergebnis

Ab Version 1.24.0 wird die Action prosopo/procaptcha/verification_result nach jeder Verifizierungsanfrage mit dem Ergebnis und der API-Antwort ausgeführt. So können Sie den Score oder den Grund für eine abgelehnte Übermittlung erfassen. Wenn WP_DEBUG aktiv ist, werden fehlgeschlagene Verifizierungen außerdem ins Debug-Log geschrieben.

add_action('prosopo/procaptcha/verification_result', function (bool $verified, array $response): void {
    // $response: verified, status, score, reason, error, sessionId
    if (! $verified) {
        error_log('Procaptcha rejected a submission: ' . ($response['reason'] ?? 'unknown'));
    }
}, 10, 2);

6. JavaScript-Ereignisse

Ab Version 1.24.0 löst das Widget diese Ereignisse aus, die bis zum Formular und zum Dokument aufsteigen:

prosopo-procaptcha:filled: Der Besucher hat das CAPTCHA gelöst. event.detail.token enthält das Token.
prosopo-procaptcha:cleared: Das Token ist abgelaufen oder das Widget wurde zurückgesetzt.

Ein Token kann nur einmal verifiziert werden. Das Plugin setzt das CAPTCHA nach AJAX-Übermittlungen der unterstützten Formular-Plugins zurück. Lösen Sie bei eigenen AJAX-Formularen prosopo-procaptcha:reset auf dem Formular aus (oder auf einem Element, das das CAPTCHA enthält, oder auf document, um alle zurückzusetzen):

document.addEventListener('prosopo-procaptcha:filled', (event) => {
    console.log('Token received', event.detail.token);
});

document.addEventListener('prosopo-procaptcha:cleared', (event) => {
    console.log('Token expired or the widget was reset', event.target);
});

// Reset the captcha in a form, e.g. after your own AJAX submission.
form.dispatchEvent(new Event('prosopo-procaptcha:reset'));

7. Formulare mit Procaptcha in Tests

Wenn Ihre Tests Formulare mit Procaptcha umfassen, können Sie das Procaptcha umgehen, indem Sie die folgende Konstante zu Ihrer wp-config.php-Datei hinzufügen:

define('PROSOPO_PROCAPTCHA_ALLOW_BYPASS', true);

Fügen Sie in Ihren Tests ein input[name=procaptcha-response]-Element mit dem Wert bypass zu jedem Formular hinzu, um den Procaptcha-Abschluss zu simulieren.

Wichtig: Diese Bypass-Konstante sollte nur in Entwicklungsumgebungen verwendet werden.