Ein Script-Tag, ein Div im Formular.
ByeBot einbinden.
Die Einbindung hat zwei Teile: das Widget im Browser, die Prüfung auf Ihrem Server. Dazwischen liegt ein Formularfeld namens byebot-token.
Wie binde ich ByeBot in ein Formular ein?
Zwei Zeilen HTML.
Ein Script-Tag und ein Div an der Stelle, an der die Prüfung erscheinen soll. Den Sitekey finden Sie im Dashboard. Für die Web-Einbindung gibt es keine Bibliothek, die Sie installieren müssten.
<script src="https://challenge.byebot.de/ray/widget.js" defer></script>
<form method="post" action="/anmeldung">
<div class="captcha-widget" data-sitekey="IHR_SITEKEY"></div>
<button type="submit">Absenden</button>
</form>
Echte Aufnahme des laufenden Dashboards. Der Schlüssel im Bild gehört zu einem Testkonto mit Demo-Daten. Das Widget nimmt ihn unter sitekey wie unter data-sitekey an.
- Besucher
- Ihr Formular
- widget.js im Browser
ByeBot
Deutschland
Prüfung bestanden
- Token im Feld byebot-token
- Ihr Server ruft validate_token auf
- Antwort 200, Formular annehmen
Prüfung nicht bestanden
- Kein gültiger Token im Formular
- Antwort 400, Formular ablehnen
Geprüft wird in Deutschland, in jedem Tarif.
Das Widget läuft in einem eigenen Rahmen. Ihr Formular merkt davon nur eines: Nach bestandener Prüfung steht darin ein verstecktes Feld mit dem Namen byebot-token. Dieses Feld schickt der Browser beim Absenden mit, wie jedes andere auch.
Wie prüfe ich das Ergebnis auf dem Server?
Ein POST an validate_token.
Ihr Backend schickt den Feldwert zusammen mit Ihrem API-Key. Erst wenn die Antwort 200 lautet, nehmen Sie das Formular an.
POST https://challenge.byebot.de/validate_token
Content-Type: application/json
{
"api_key": "IHR_API_KEY",
"token": "Wert des Feldes byebot-token"
}200Prüfung gültig. Formular annehmen.400Prüfung ungültig. Formular ablehnen.
Im Browser
Nicht belastbar
- Der Token liegt im Formular des Besuchers
- Ein Skript kann jedes Feld selbst setzen
- Der Browser gehört nicht Ihnen
Auf Ihrem Server
Belastbar
- Der API-Key verlässt Ihren Server nie
- ByeBot antwortet mit 200 oder 400
- Erst danach nehmen Sie das Formular an
- Anfrage
- POST an validate_token, JSON mit api_key und token. Der Token ist der Wert des Formularfeldes byebot-token.
- 200
- Bestanden. Die Antwort enthält zusätzlich sitekey, challenged_at, solve_time_ms und interactive_solved, falls Sie mitschreiben wollen.
- 400
- Nicht bestanden. Die Antwort hat keinen Inhalt. Für die Entscheidung genügt der Status.
- API-Key
- Steht im Dashboard und gehört auf den Server. In die Seite gehört nur der Sitekey.
Echte Aufnahme des laufenden Dashboards. Die Werte stammen aus einem Testkonto mit Demo-Daten.
Welche Attribute kennt das Widget?
Zwei Pflichtangaben, vier optionale.
Alles steht am Div. Es gibt keine Konfigurationsdatei und keinen Initialisierungsaufruf, den Sie schreiben müssten.
- Pflichtclass="captcha-widget" markiert das Div, in dem die Prüfung erscheint.
- Pflichtdata-sitekey trägt den öffentlichen Schlüssel Ihrer Seite aus dem Dashboard.
- Optionaldata-token-callback ruft Ihre Funktion auf, sobald ein Token vorliegt.
- Optionaldata-expired-callback ruft Ihre Funktion auf, wenn ein Token abgelaufen ist.
- Optionaldata-domain überschreibt die Domain, gegen die geprüft wird. Für WebViews.
- Optionaldata-width setzt die Breite in Pixeln, 280 bis 2000.
Aussehen, Modus und Schwierigkeit stellen Sie nicht im HTML ein, sondern pro Seite im Dashboard.
<div class="captcha-widget"
data-sitekey="IHR_SITEKEY"
data-token-callback="tokenErhalten"
data-expired-callback="tokenAbgelaufen"
data-width="360"></div>Ohne data-width richtet sich die Breite nach dem breitesten Eingabefeld im selben Formular. Steht das Widget außerhalb eines Formulars, gilt eine Standardbreite. Angegebene Werte werden auf 280 bis 2000 Pixel begrenzt.
Wie binde ich das Widget in React, Vue oder eine App ein?
Über window.Byebot.render.
Hängt ein Framework das Formular erst nachträglich in die Seite, ist das Script längst durchgelaufen. Dann rendern Sie selbst, sobald das Div steht.
// aufrufen, sobald das Div im DOM steht
window.Byebot.render(element);
// oder jedes Widget auf der Seite
window.Byebot.renderAll();- Schritt 1Ihre Komponente hängt das Div mit der Klasse captcha-widget ins DOM.
- Schritt 2Ihr Code ruft window.Byebot.render(element) mit genau diesem Div auf.
- Schritt 3data-token-callback bekommt den Token, sobald die Prüfung bestanden ist.
- Schritt 4Läuft der Token ab, meldet sich data-expired-callback und die Prüfung startet neu.
- Schritt 5Für ein zurückgesetztes Formular rufen Sie render() erneut auf.
Für Angular, Next.js, Svelte und Vue liegt dieser Ablauf als fertige Komponente bereit.
- render(element)
- Rendert ein einzelnes Widget in dem übergebenen Div.
- renderAll()
- Rendert jedes Div mit der Klasse captcha-widget, das gerade auf der Seite steht.
- Ohne Aufruf
- Beim Laden der Seite rendert das Script von selbst alle Widgets, die schon im DOM stehen. Für klassisches serverseitiges HTML brauchen Sie keine Zeile JavaScript.
- Mobile Apps
- Die SDKs für Android, iOS und React Native betten dasselbe Widget in einen WebView ein. data-domain setzt dabei die Domain, gegen die geprüft wird.
- Sprache
- Zwölf Sprachen, automatisch aus der Browsersprache des Besuchers. Es gibt kein Sprachattribut.
- Fertiger Code
- Zu den Integrationen
Fragen zur Einbindung.
Kurze Antworten zu Feldnamen, Statuscodes und dem, was ins HTML gehört und was nicht.
Wie heißt das Formularfeld mit dem Token?
Es heißt byebot-token. Nach bestandener Prüfung steht in Ihrem Formular ein verstecktes Feld mit diesem Namen, und der Browser schickt es beim Absenden mit, wie jedes andere Feld auch. Dessen Wert reichen Sie an validate_token weiter. Das Widget selbst läuft in einem eigenen Rahmen, mehr als dieses Feld bekommt Ihr Formular davon nicht mit.
Was bedeutet die Antwort 400 bei validate_token?
400 heißt nicht bestanden, Formular ablehnen. Die Antwort hat keinen Inhalt, für die Entscheidung genügt der Status. Bei 200 ist die Prüfung gültig, und die Antwort enthält zusätzlich sitekey, challenged_at, solve_time_ms und interactive_solved, falls Sie mitschreiben wollen. Erst bei 200 nehmen Sie das Formular an.
Gehört der API-Key in die Website?
Nein, der API-Key gehört auf den Server, in die Seite gehört nur der Sitekey. Ihr Backend schickt ihn zusammen mit dem Feldwert an validate_token. In die Seite gehört er nie. Eine Entscheidung im Browser wäre nicht belastbar: Dort liegt der Token im Formular des Besuchers, und ein Skript kann jedes Feld selbst setzen.
Brauche ich JavaScript für ein einfaches HTML-Formular?
Nein. Beim Laden der Seite rendert das Script von selbst alle Widgets, die schon im DOM stehen. Für klassisches serverseitiges HTML brauchen Sie keine Zeile JavaScript. Nötig wird window.Byebot.render erst, wenn ein Framework das Formular nachträglich in die Seite hängt, denn dann ist das Script längst durchgelaufen.
Wie breit wird das Widget im Formular?
Ohne data-width richtet sich die Breite nach dem breitesten Eingabefeld im selben Formular. Steht das Widget außerhalb eines Formulars, gilt eine Standardbreite. Mit data-width setzen Sie die Breite in Pixeln selbst, angegebene Werte werden dabei auf 280 bis 2000 Pixel begrenzt.
Wo stelle ich Aussehen und Modus des Widgets ein?
Im Dashboard, pro Seite. Aussehen, Modus und Schwierigkeit stellen Sie nicht im HTML ein. Am Div stehen nur zwei Pflichtangaben und vier optionale Attribute, eine Konfigurationsdatei oder einen Initialisierungsaufruf schreiben Sie dafür nicht. Auch den Sitekey, den data-sitekey trägt, finden Sie im Dashboard.
In welcher Sprache erscheint das Widget?
In zwölf Sprachen, automatisch aus der Browsersprache des Besuchers. Ein Sprachattribut gibt es nicht, Sie stellen dafür also nichts ein. Dasselbe Widget steckt in den SDKs für Android, iOS und React Native, die es in einen WebView einbetten. data-domain setzt dort die Domain, gegen die geprüft wird.
Sieben Tage testen, dann entscheiden.
Ein Zahlungsmittel wird zu Beginn hinterlegt. In der Testphase liegt die Grenze bei 10.000 Prüfungen. Danach ab 19 € im Monat.