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

La coincidencia de IP solo se aplica a las claves de sitio con la validación de IP activada en el portal de Prosopo (plan Professional o superior). Procaptcha compara entonces la IP desde la que se resolvió el captcha con la IP que envía su servidor, según las reglas que defina en el portal (cambios de país, ciudad, proveedor y distancia). Para ello el plugin debe enviar la IP real del visitante, por eso el ajuste está desactivado por defecto: en sitios detrás de Cloudflare u otro proxy, el servidor ve la dirección del proxy, y enviarla haría que la validación de IP rechazara 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. Si su clave de sitio usa la validación de IP y su sitio está detrás de un proxy, actualice a la 1.24.0 o posterior.

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ó o el widget 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.