Zum Hauptinhalt springen
Das <ribaunt-widget> löst drei benutzerdefinierte DOM-Ereignisse aus — verify, error und state-change — die du mit addEventListener am Element abhören kannst. Verwende in React stattdessen die typisierten Callback-Props; der Wrapper verbindet und löst die Listener automatisch für dich auf.

​
verify

Das verify-Ereignis wird ausgelöst, wenn das Widget alle Challenges erfolgreich löst und — falls du einen verify-endpoint angegeben hast — der Server bestätigt, dass die Lösungen gültig sind. Wenn kein verify-endpoint gesetzt ist, wird das Ereignis ausgelöst, sobald der lokale Proof-of-Work abgeschlossen ist. Ereignistyp: CustomEvent<{ solutions: ChallengeSolution[] }> Wobei ChallengeSolution = { nonce: string; hash: string }. 
widget.addEventListener('verify', (e) => {
  const { solutions } = e.detail;
  console.log('Verified! Solutions:', solutions);
  // Enable submit button, proceed with form, etc.
});
React-Äquivalent: onVerify={(detail) => ...}

​
error

Das error-Ereignis wird ausgelöst, wenn das Widget in irgendeiner Phase einen Fehler erleidet — beim Abrufen von Tokens von deinem Challenge-Endpunkt, beim Ausführen des Proof-of-Work-Solvers oder beim Erhalten einer nicht-OK-Antwort von deinem Verify-Endpunkt. Ereignistyp: CustomEvent<{ error: string; timeout?: boolean }> 
widget.addEventListener('error', (e) => {
  const { error, timeout } = e.detail;
  if (timeout) {
    console.warn('Timed out:', error);
  } else {
    console.error('CAPTCHA failed:', error);
  }
});
React-Äquivalent: onError={(detail) => ...}
Das timeout-Feld ist nur dann im Event-Detail enthalten, wenn solve-timeout konfiguriert ist und die Lösungsdauer dieses Limit überschreitet. Wenn vorhanden, ist es immer true.

​
state-change

Das state-change-Ereignis wird jedes Mal ausgelöst, wenn das Widget zwischen internen Zuständen wechselt. Du kannst es nutzen, um den visuellen Zustand des Widgets in deiner eigenen UI nachzubilden — zum Beispiel, um eine Senden-Schaltfläche während der laufenden Verifizierung zu deaktivieren. Ereignistyp: CustomEvent<{ state: 'initial' | 'verifying' | 'done' | 'error' }> 
widget.addEventListener('state-change', (e) => {
  const { state } = e.detail;
  // 'initial' | 'verifying' | 'done' | 'error'
});
React-Äquivalent: onStateChange={(detail) => ...}

​
React-Callback-Props

Wenn du den React-Wrapper verwendest, kannst du alle Callbacks direkt als Props übergeben. Der Wrapper behält stabile Event-Listener-Referenzen über Re-Renders hinweg, sodass deine Callbacks immer die aktuellsten Closure-Werte erhalten: 
<RibauntWidget
  challengeEndpoint="/api/captcha/challenge"
  verifyEndpoint="/api/captcha/verify"
  onVerify={(detail) => console.log('Solutions:', detail.solutions)}
  onError={(detail) => console.error('Error:', detail.error)}
  onStateChange={(detail) => console.log('State:', detail.state)}
  onReady={(detail) => console.log('Ready with state:', detail.state)}
  onLoad={(detail) => console.log('Widget loaded:', detail.state)}
  onEvent={(type, detail) => console.log('Event:', type, detail)}
/>

​
Nur in React verfügbare Ereignisse

Zwei zusätzliche Callbacks sind im React-Wrapper verfügbar, die kein entsprechendes benutzerdefiniertes DOM-Ereignis an der Web-Komponente haben:
  • onReady — wird einmal ausgelöst, nachdem das Widget gemountet wurde, mit dem initialen Widget-Zustand im Detail-Payload. Verwende dies, um zu erkennen, wann das Widget bereit für Interaktionen ist.
  • onLoad — funktional identisch mit onReady. Es wird als Alias zur Abwärtskompatibilität bereitgestellt, falls du onLoad bereits in einer früheren Version verwendet hast.
  • onEvent — ein Sammel-Handler, der für jeden Ereignistyp ausgelöst wird ('verify', 'error', 'state-change' und 'ready'), zusammen mit dem Detail-Objekt des Ereignisses. Verwende ihn, wenn du eine einzige Stelle zum Behandeln oder Protokollieren aller Widget-Ereignisse möchtest.

​
Widget-Zustände

Das Widget durchläuft während seines Lebenszyklus eine definierte Menge von Zuständen. Diese Zustands-Zeichenketten begegnen dir in state-change-Ereignissen und im Rückgabewert von getState():
ZustandBeschreibung
initialWidget ist geladen, wartet auf Klick des Benutzers oder Auto-Verify
verifyingSolver läuft (Proof-of-Work in Bearbeitung)
doneChallenge erfolgreich gelöst und verifiziert
errorWährend Fetch, Solve oder Verify ist ein Fehler aufgetreten