Widget API

Widget API

Query-Parameter

ParameterWertBeschreibung
onload<Funktionsname>(Optional) Der Name Ihrer benutzerdefinierten Callback-Funktion, die aufgerufen wird, sobald die CaptchaFox-API geladen wurde. Muss definiert werden, bevor die API geladen wird.
renderexplicit | onload(Optional) Ob das Widget automatisch gerendert werden soll oder nicht. Der Standardwert ist onload.
lang<Sprachcode>(Optional) Erzwingt eine bestimmte Lokalisierung. Standardmäßig erkennt CaptchaFox automatisch die Anzeigesprache des Benutzers.

Die Parameter werden als key=value-Paare gesetzt, gefolgt von einem ? nach dem Skriptnamen. Wenn Sie das Widget zum Beispiel immer auf Deutsch darstellen wollen, sollte Ihr Skript-Tag wie folgt aussehen:

<script async defer src="https://cdn.captchafox.com/api.js?lang=de"></script>

Mehrere Query-Parameter werden mit & separiert:

<script async defer src="https://cdn.captchafox.com/api.js?lang=de&render=explicit"></script>

Container Attribute

Zusätzlich zu dem erforderlichen Attribut "data-sitekey" können Sie die folgenden Attribute an das Container-Element übergeben:

AttributWertBeschreibung
data-sitekey<Ihr Sitekey>Erforderlich. Ihr CaptchaFox-Seitenschlüssel.
data-lang<Sprachcode>(Optional) Erzwingt eine bestimmte Lokalisierung. Standardmäßig erkennt CaptchaFox automatisch die Anzeigesprache des Benutzers.
data-modeinline | popup | hidden(Optional) Der Modus, in dem das Widget angezeigt werden soll. Standardmäßig ist inline eingestellt.
data-themelight | dark(Optional) Das Theme für das Widget. Standardmäßig ist "light" eingestellt.
data-callback<Funktionsname>(Optional) Wird mit dem Antwort-Token nach erfolgreicher Überprüfung aufgerufen.
data-expired-callback<Funktionsname>(Optional) Wird aufgerufen, wenn die Antwort abläuft.
data-fail-callback<Funktionsname>(Optional) Wird nach erfolgloser Verifizierung aufgerufen.
data-close-callback<Funktionsname>(Optional) Wird aufgerufen, wenn die Herausforderung geschlossen wurde.
data-error-callback<Funktionsname>(Optional) Wird aufgerufen, wenn CaptchaFox auf einen Fehler stößt. Informieren Sie den Nutzer über eine erneute Ausführung.

Beispiel:

<div
  class="captchafox"
  data-sitekey="IHR_SITEKEY"
  data-lang="es"
  data-callback="verifyAndSubmit"
  data-error-callback="showError"
></div>

Fehler-Codes

Wenn das CaptchaFox Widget auf einen Fehler stößt, wird ein Fehlercode an das Error-Event gesendet (z.B. data-error-callback).

Nachfolgend finden Sie eine Liste möglicher Fehler und deren Ursachen:

FehlerBeschreibung
internal-errorDas Widget ist auf einen internen Fehler gestoßen.
load-challenge-errorDie Herausforderung konnte nicht geladen werden.
verify-challenge-errorDie Verifizierung konnte nicht durchgeführt werden.
load-audio-errorDie Audio-Herausforderung konnte nicht korrekt geladen werden.
load-slide-errorDie Schieber-Herausforderung konnte nicht korrekt geladen werden.
network-errorEin Netzwerkfehler ist aufgetreten.
rate-limitedDer Nutzer hat zu viele Anfragen gesendet.

JavaScript API

Das JavaScript-Tag stellt das captchafox window Objekt zur Verfügung, das Methoden zur Anpassung des CaptchaFox-Verhaltens bietet.

captchafox.render(containerElement, options)

Stellt das CaptchaFox-Widget innerhalb des Container-Elements dar und gibt eine eindeutige widgetId zurück.

ParameterWertBeschreibung
containerElementHTMLElement | stringDas HTML-Element, in das das Widget gerendert werden soll.
options<Objekt>Ein Objekt mit Konfigurationsparametern. Siehe Optionen
Options
AttributeWertBeschreibung
sitekey<Ihr Sitekey>Erforderlich. Ihr CaptchaFox-Seitenschlüssel.
lang<Sprachcode>(Optional) Erzwingt eine bestimmte Lokalisierung. Standardmäßig erkennt CaptchaFox automatisch die Anzeigesprache des Benutzers.
modeinline | popup | hidden(Optional) Der Modus, in dem das Widget angezeigt werden soll. Standardmäßig ist inline eingestellt.
themelight | dark | ThemeDefinition(Optional) Das Theme für das Widget. Standardmäßig ist "light" eingestellt.
i18n<object>(Optional) i18n-Konfiguration. Ermöglicht das Überschreiben von Bezeichnungen für bestimmte Sprachen.
onVerify<Funktionsname>(Optional) Wird mit dem Antwort-Token nach erfolgreicher Überprüfung aufgerufen.
onExpire<Funktionsname>(Optional) Wird aufgerufen, wenn die Antwort abläuft.
onFail<Funktionsname>(Optional) Wird nach erfolgloser Verifizierung aufgerufen.
onClose<Funktionsname>(Optional) Wird aufgerufen, wenn die Herausforderung geschlossen wurde.
onError<Funktionsname>(Optional) Wird aufgerufen, wenn CaptchaFox auf einen Fehler stößt. Informieren Sie den Nutzer über eine erneute Ausführung.

captchafox.reset(widgetId)

Setzt ein bestimmtes CaptchaFox-Widget zurück.

ParameterWertBeschreibung
widgetIdnumber(Optional) Eindeutige ID für ein Widget. Standardmäßig wird das erste gerenderte Widget verwendet.

captchafox.remove(widgetId)

Entfernt ein bestimmtes CaptchaFox-Widget aus dem DOM.

ParameterWertBeschreibung
widgetIdnumber(Optional) Eindeutige ID für ein Widget. Standardmäßig wird das erste gerenderte Widget verwendet.

captchafox.getResponse(widgetId)

Ruft die Antwort für ein bestimmtes CaptchaFox-Widget ab.

ParameterWertBeschreibung
widgetIdnumber(Optional) Eindeutige ID für ein Widget. Standardmäßig wird das erste gerenderte Widget verwendet.

captchafox.execute(widgetId)

Löst programmatisch den CaptchaFox-Abfrageablauf aus. Wird in einer benutzerdefinierten Integration verwendet oder wenn der Modus auf hidden gesetzt wird.

ParameterWertBeschreibung
widgetIdnumber(Optional) Eindeutige ID für ein Widget. Standardmäßig wird das erste gerenderte Widget verwendet.

Nach erfolgreichem Abschluss der Herausforderung wird die Funktion mit dem Antwort-Token aufgelöst. Im Falle eines Fehlers wird sie zurückgewiesen.

try {
  const token = await captchafox.execute(widgetId);
  console.log(token);
} catch (error) {
  console.error(error);
}