Filtri e Hook

Il plugin Procaptcha introduce nuovi filtri e hook WordPress, che le consentono di personalizzarne il comportamento.

1. Visibilità del Captcha

Per impostazione predefinita, Procaptcha viene visualizzato solo agli utenti non autorizzati.

Per controllare questo comportamento, oltre alle impostazioni del plugin, può utilizzare l’hook is_captcha_present. Per esempio, per rendere Procaptcha obbligatorio per tutti, aggiunga il seguente codice al file functions.php del suo tema:

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

2. Messaggio di errore personalizzato

Può personalizzare il messaggio di errore predefinito aggiungendo questo codice al file functions.php del suo tema:

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

3. Personalizzazione degli attributi Procaptcha

Oltre alle preferenze di stile nelle impostazioni del plugin, può personalizzare qualsiasi attributo data Procaptcha supportato utilizzando il filtro prosopo/procaptcha/captcha_attributes.

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

4. Corrispondenza IP del visitatore

Con la corrispondenza IP attiva, il plugin invia l’indirizzo IP del visitatore con ogni richiesta di verifica, e Procaptcha rifiuta un token risolto da un altro IP. È disattivata per impostazione predefinita: la maggior parte dei siti è dietro Cloudflare o un altro proxy, e inviare l’indirizzo del proxy invece di quello del visitatore rifiuterebbe visitatori reali.

Per attivarla, vai su Impostazioni > Prosopo Procaptcha > General e scegli da dove proviene l’IP del visitatore in Corrispondenza IP del visitatore:

Attivato – il sito è dietro Cloudflare: l’header CF-Connecting-IP.
Attivato – il sito è dietro un altro proxy: il primo indirizzo nell’header X-Forwarded-For.
Attivato – i visitatori si connettono direttamente: REMOTE_ADDR.

Scegli solo un header impostato dal tuo proxy, perché i visitatori possono inviare questi header da soli. Se l’header manca o non è un indirizzo IP valido, non viene inviato nulla e il token viene verificato senza corrispondenza IP.

Per altre configurazioni, il filtro prosopo/procaptcha/visitor_ip riceve l’IP dall’impostazione (vuoto quando è disattivata) e REMOTE_ADDR. Restituisci l’IP da inviare, o una stringa vuota per non inviarne nessuno:

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

La versione 1.23.0 inviava REMOTE_ADDR per impostazione predefinita. Aggiorna alla 1.24.0 o successiva se il tuo sito è dietro un proxy.

5. Risultato della verifica

Dalla versione 1.24.0, l’azione prosopo/procaptcha/verification_result viene eseguita dopo ogni richiesta di verifica con il risultato e la risposta dell’API, così puoi registrare il punteggio o il motivo per cui un invio è stato rifiutato. Quando WP_DEBUG è attivo, le verifiche non riuscite vengono scritte anche nel log di debug.

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. Eventi JavaScript

Dalla versione 1.24.0, il widget emette questi eventi, che risalgono fino al modulo e al documento:

prosopo-procaptcha:filled: il visitatore ha risolto il captcha. event.detail.token contiene il token.
prosopo-procaptcha:cleared: il token è scaduto, il widget ha dato un errore o è stato reimpostato.

Un token può essere verificato una sola volta. Il plugin reimposta il captcha dopo gli invii AJAX dei plugin di moduli supportati. Per i tuoi moduli AJAX, emetti prosopo-procaptcha:reset sul modulo (o su qualsiasi elemento che contiene il captcha, oppure su document per reimpostarli tutti):

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. Moduli con Procaptcha nei test

Se i suoi test coinvolgono moduli con Procaptcha, può bypassare Procaptcha aggiungendo la seguente costante al file wp-config.php:

define('PROSOPO_PROCAPTCHA_ALLOW_BYPASS', true);

Nei suoi test, aggiunga un elemento input[name=procaptcha-response] con il valore bypass a qualsiasi modulo per simulare il completamento di Procaptcha.

Importante: Questa costante di bypass dovrebbe essere utilizzata solo negli ambienti di sviluppo.