From 0db4c9d25dee6dc8cf0421c58683a3d9b6d087ba Mon Sep 17 00:00:00 2001 From: Chris Taylor Date: Thu, 29 Oct 2026 13:48:51 +0000 Subject: [PATCH] docs(wordpress): document the verification_result action and the widget's JavaScript events Co-Authored-By: Claude Opus 5.5 --- .../docs/de/wordpress-plugin/hooks.mdx | 37 ++++++++++++++++++- .../docs/en/wordpress-plugin/hooks.mdx | 37 ++++++++++++++++++- .../docs/es/wordpress-plugin/hooks.mdx | 37 ++++++++++++++++++- .../docs/fr/wordpress-plugin/hooks.mdx | 37 ++++++++++++++++++- .../docs/it/wordpress-plugin/hooks.mdx | 37 ++++++++++++++++++- .../docs/pt-br/wordpress-plugin/hooks.mdx | 37 ++++++++++++++++++- 6 files changed, 216 insertions(+), 6 deletions(-) diff --git a/src/content/docs/de/wordpress-plugin/hooks.mdx b/src/content/docs/de/wordpress-plugin/hooks.mdx index 5bdf4d3a649c0..1e754821c5943 100644 --- a/src/content/docs/de/wordpress-plugin/hooks.mdx +++ b/src/content/docs/de/wordpress-plugin/hooks.mdx @@ -49,7 +49,42 @@ add_filter('prosopo/procaptcha/visitor_ip', function (string $ip): string { Vertrauen Sie nur einem weitergeleiteten Header, den Ihr Proxy setzt. Werte, die keine gültige IP-Adresse sind, werden nicht gesendet. -## 5. Formulare mit Procaptcha in Tests +## 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. + +```php +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, im Widget ist ein Fehler aufgetreten oder es 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): + +```js +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: diff --git a/src/content/docs/en/wordpress-plugin/hooks.mdx b/src/content/docs/en/wordpress-plugin/hooks.mdx index 796035c8b99f7..41f28d7dd5535 100644 --- a/src/content/docs/en/wordpress-plugin/hooks.mdx +++ b/src/content/docs/en/wordpress-plugin/hooks.mdx @@ -49,7 +49,42 @@ add_filter('prosopo/procaptcha/visitor_ip', function (string $ip): string { Only trust a forwarded header that your proxy sets. Values that aren't a valid IP address aren't sent. -## 5. Forms with Procaptcha in tests +## 5. Verification result + +From version 1.24.0, the **prosopo/procaptcha/verification_result** action runs after each verification request with the result and the API response, so you can record the score or the reason a submission was rejected. When `WP_DEBUG` is on, failed verifications are also written to the debug log. + +```php +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 events + +From version 1.24.0, the widget dispatches these events, which bubble up to the form and the document: + +- `prosopo-procaptcha:filled`: the visitor solved the captcha. `event.detail.token` holds the token. +- `prosopo-procaptcha:cleared`: the token expired, the widget errored or it was reset. + +A token can be verified only once. The plugin resets the captcha after AJAX submissions of the supported form plugins. For your own AJAX forms, dispatch `prosopo-procaptcha:reset` on the form (or any element that contains the captcha, or `document` to reset all of them): + +```js +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. Forms with Procaptcha in tests If your tests involve forms with Procaptcha, you can bypass the Procaptcha by adding the following constant to your wp-config.php file: diff --git a/src/content/docs/es/wordpress-plugin/hooks.mdx b/src/content/docs/es/wordpress-plugin/hooks.mdx index 60d358d307714..df74a317b60d9 100644 --- a/src/content/docs/es/wordpress-plugin/hooks.mdx +++ b/src/content/docs/es/wordpress-plugin/hooks.mdx @@ -49,7 +49,42 @@ add_filter('prosopo/procaptcha/visitor_ip', function (string $ip): string { Confíe solo en una cabecera reenviada que establezca su proxy. Los valores que no sean una dirección IP válida no se envían. -## 5. Formularios con Procaptcha en pruebas +## 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. + +```php +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): + +```js +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: diff --git a/src/content/docs/fr/wordpress-plugin/hooks.mdx b/src/content/docs/fr/wordpress-plugin/hooks.mdx index e43d7e879aade..e212ac4188776 100644 --- a/src/content/docs/fr/wordpress-plugin/hooks.mdx +++ b/src/content/docs/fr/wordpress-plugin/hooks.mdx @@ -49,7 +49,42 @@ add_filter('prosopo/procaptcha/visitor_ip', function (string $ip): string { Ne faites confiance qu'à un en-tête transféré défini par votre proxy. Les valeurs qui ne sont pas une adresse IP valide ne sont pas envoyées. -## 5. Formulaires avec Procaptcha dans les tests +## 5. Résultat de la vérification + +Depuis la version 1.24.0, l'action **prosopo/procaptcha/verification_result** s'exécute après chaque requête de vérification avec le résultat et la réponse de l'API, pour enregistrer le score ou la raison du rejet d'une soumission. Lorsque `WP_DEBUG` est activé, les vérifications échouées sont aussi écrites dans le journal de débogage. + +```php +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. Événements JavaScript + +Depuis la version 1.24.0, le widget déclenche ces événements, qui remontent jusqu'au formulaire et au document : + +- `prosopo-procaptcha:filled` : le visiteur a résolu le captcha. `event.detail.token` contient le jeton. +- `prosopo-procaptcha:cleared` : le jeton a expiré, le widget a rencontré une erreur ou a été réinitialisé. + +Un jeton ne peut être vérifié qu'une seule fois. Le plugin réinitialise le captcha après les soumissions AJAX des plugins de formulaires pris en charge. Pour vos propres formulaires AJAX, déclenchez `prosopo-procaptcha:reset` sur le formulaire (ou sur tout élément contenant le captcha, ou sur `document` pour tous les réinitialiser) : + +```js +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. Formulaires avec Procaptcha dans les tests Si vos tests impliquent des formulaires avec Procaptcha, vous pouvez contourner le Procaptcha en ajoutant la constante suivante à votre fichier wp-config.php : diff --git a/src/content/docs/it/wordpress-plugin/hooks.mdx b/src/content/docs/it/wordpress-plugin/hooks.mdx index 4acb79197221d..d780da48bbfb1 100644 --- a/src/content/docs/it/wordpress-plugin/hooks.mdx +++ b/src/content/docs/it/wordpress-plugin/hooks.mdx @@ -49,7 +49,42 @@ add_filter('prosopo/procaptcha/visitor_ip', function (string $ip): string { Fidati solo di un header inoltrato impostato dal tuo proxy. I valori che non sono un indirizzo IP valido non vengono inviati. -## 5. Moduli con Procaptcha nei test +## 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. + +```php +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): + +```js +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: diff --git a/src/content/docs/pt-br/wordpress-plugin/hooks.mdx b/src/content/docs/pt-br/wordpress-plugin/hooks.mdx index 10088f07c9bbd..b22d64261542e 100644 --- a/src/content/docs/pt-br/wordpress-plugin/hooks.mdx +++ b/src/content/docs/pt-br/wordpress-plugin/hooks.mdx @@ -49,7 +49,42 @@ add_filter('prosopo/procaptcha/visitor_ip', function (string $ip): string { Confie apenas em um cabeçalho encaminhado definido pelo seu proxy. Valores que não sejam um endereço IP válido não são enviados. -## 5. Formulários com Procaptcha em Testes +## 5. Resultado da verificação + +A partir da versão 1.24.0, a action **prosopo/procaptcha/verification_result** é executada após cada solicitação de verificação com o resultado e a resposta da API, para que você possa registrar a pontuação ou o motivo pelo qual um envio foi rejeitado. Quando `WP_DEBUG` está ativo, as verificações que falharam também são gravadas no log de depuração. + +```php +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 JavaScript + +A partir da versão 1.24.0, o widget dispara estes eventos, que se propagam até o formulário e o documento: + +- `prosopo-procaptcha:filled`: o visitante resolveu o captcha. `event.detail.token` contém o token. +- `prosopo-procaptcha:cleared`: o token expirou, o widget apresentou um erro ou foi redefinido. + +Um token só pode ser verificado uma vez. O plugin redefine o captcha após os envios AJAX dos plugins de formulário compatíveis. Nos seus próprios formulários AJAX, dispare `prosopo-procaptcha:reset` no formulário (ou em qualquer elemento que contenha o captcha, ou em `document` para redefinir todos): + +```js +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. Formulários com Procaptcha em Testes Se seus testes envolvem formulários com Procaptcha, você pode ignorar o Procaptcha adicionando a seguinte constante ao seu arquivo wp-config.php: