docs(wordpress): verification_result action and JavaScript events

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:
 

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:
 

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:
 

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 :
 

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:
 

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: