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

La corrispondenza IP si applica solo alle chiavi del sito con la convalida IP attiva nel portale Prosopo (piano Professional e superiori). Procaptcha confronta quindi l’IP da cui è stato risolto il captcha con l’IP inviato dal tuo server, secondo le regole impostate nel portale (cambi di paese, città, provider e distanza). Per questo il plugin deve inviare l’IP reale del visitatore, perciò l’impostazione è disattivata per impostazione predefinita: sui siti dietro Cloudflare o un altro proxy il server vede l’indirizzo del proxy, e inviarlo farebbe rifiutare visitatori reali dalla convalida IP.

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. Se la tua chiave del sito usa la convalida IP e il sito è dietro un proxy, aggiorna alla 1.24.0 o successiva.

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 o il widget è 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.