Filtros y Hooks

El plugin Procaptcha introduce nuevos filtros y hooks de WordPress, lo que le permite personalizar su comportamiento.

1. Visibilidad del Captcha

Por defecto, Procaptcha se muestra solo a usuarios no autorizados.

Para controlar este comportamiento, además de la configuración del plugin, puede usar el hook is_captcha_present. Por ejemplo, para hacer que Procaptcha sea requerido para todos, agregue el siguiente código al archivo functions.php de su tema:

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

2. Mensaje de error personalizado

Puede personalizar el mensaje de error predeterminado agregando este código al archivo functions.php de su tema:

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

3. Personalización de atributos de Procaptcha

Más allá de las preferencias de estilo en la configuración del plugin, puede personalizar cualquier atributo de datos de Procaptcha admitido usando el filtro prosopo/procaptcha/captcha_attributes.

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

4. Coincidencia de IP del visitante

Con la coincidencia de IP activada, el plugin envía la dirección IP del visitante en cada solicitud de verificación, y Procaptcha rechaza un token resuelto desde otra IP. Está desactivada por defecto: la mayoría de los sitios están detrás de Cloudflare u otro proxy, y enviar la dirección del proxy en lugar de la del visitante rechazaría a visitantes reales.

Para activarla, vaya a Ajustes > Prosopo Procaptcha > General y elija de dónde procede la IP del visitante en Coincidencia de IP del visitante:

Activado: el sitio está detrás de Cloudflare: la cabecera CF-Connecting-IP.
Activado: el sitio está detrás de otro proxy: la primera dirección de la cabecera X-Forwarded-For.
Activado: los visitantes se conectan directamente: REMOTE_ADDR.

Elija solo una cabecera que establezca su proxy, ya que los visitantes pueden enviar estas cabeceras ellos mismos. Si falta la cabecera o no es una dirección IP válida, no se envía nada y el token se verifica sin coincidencia de IP.

Para otras configuraciones, el filtro prosopo/procaptcha/visitor_ip recibe la IP del ajuste (vacía si está desactivado) y REMOTE_ADDR. Devuelva la IP que desea enviar, o una cadena vacía para no enviar ninguna:

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

La versión 1.23.0 enviaba REMOTE_ADDR por defecto. Actualice a la 1.24.0 o posterior si su sitio está detrás de un proxy.

5. Resultado de la verificación

A partir de la versión 1.24.0, la acción prosopo/procaptcha/verification_result se ejecuta tras cada solicitud de verificación con el resultado y la respuesta de la API, para que pueda registrar la puntuación o el motivo por el que se rechazó un envío. Cuando WP_DEBUG está activo, las verificaciones fallidas también se escriben en el registro de depuración.

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. Eventos de JavaScript

A partir de la versión 1.24.0, el widget emite estos eventos, que se propagan hasta el formulario y el documento:

prosopo-procaptcha:filled: el visitante resolvió el captcha. event.detail.token contiene el token.
prosopo-procaptcha:cleared: el token caducó, el widget dio un error o se reinició.

Un token solo se puede verificar una vez. El plugin reinicia el captcha tras los envíos AJAX de los plugins de formularios compatibles. En sus propios formularios AJAX, emita prosopo-procaptcha:reset en el formulario (o en cualquier elemento que contenga el captcha, o en document para reiniciarlos todos):

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. Formularios con Procaptcha en pruebas

Si sus pruebas involucran formularios con Procaptcha, puede omitir el Procaptcha agregando la siguiente constante a su archivo wp-config.php:

define('PROSOPO_PROCAPTCHA_ALLOW_BYPASS', true);

En sus pruebas, agregue un elemento input[name=procaptcha-response] con el valor bypass a cualquier formulario para simular la finalización de Procaptcha.

Importante: Esta constante de omisión solo debe usarse en entornos de desarrollo.