Browser löst, Server entscheidet.

CAPTCHA einbinden: Anleitung für Entwickler.

Zwei Zeilen im Formular und ein POST von Ihrem Server. Der Client-Teil ist in einer Minute erledigt, der Server-Teil entscheidet, ob der Schutz überhaupt wirkt.

Widget ausprobieren Die vier Fehler

Stand: 1. August 2026

Alle gängigen CAPTCHA-Dienste folgen demselben Muster. Ein Script rendert ein Widget in einen Container, der Besucher löst die Prüfung, das Widget legt ein Ergebnis in das Formular, und Ihr Server fragt nach, ob dieses Ergebnis echt ist. Die Beispiele unten zeigen das an ByeBot, das Muster gilt auch für andere Anbieter.

Ablauf

Wie läuft die Prüfung technisch ab?

Der Browser löst, Ihr Server entscheidet.

Alles, was nur im Browser passiert, kann ein Bot überspringen. Deshalb ist der letzte Schritt der wichtige.

Vom Script-Tag zur Entscheidung auf Ihrem Server

Script-Tag lädt widget.js
Container mit Sitekey
Prüfung im Browser gelöst
Feld byebot-token gesetzt

Ihr Server

POST /validate_token

HTTP 200

Prüfung gültig
Formular annehmen

HTTP 400

Ungültig oder verbraucht
Formular ablehnen

Das Widget prüft im Browser, angenommen oder abgelehnt wird das Formular ausschließlich auf Ihrem Server.

Einbinden

Schritt 1: Wie binde ich das Widget ein?

Ein Script-Tag und ein Container mit dem Sitekey.

HTML

<script src="https://challenge.byebot.de/ray/widget.js" defer></script>

<form action="/kontakt" method="post">
  <input name="email" type="email" required>
  <textarea name="nachricht" required></textarea>

  <div class="captcha-widget" data-sitekey="IHR_SITEKEY"></div>

  <button type="submit">Absenden</button>
</form>

Die Einbau-Anleitung im Dashboard: der Seitenschlüssel zum Kopieren, darunter zwei Codeblöcke für die Skriptzeile und das Widget-Element, dann dreizehn Plattformlogos und ein Verweis auf die Anleitungen. — Dieselben zwei Zeilen im Dashboard, mit dem Sitekey zum Kopieren

Container: Das Widget rendert sich in jedes Element mit der Klasse captcha-widget.
Sitekey: Öffentlich und an die Domains gebunden, die Sie im Dashboard eingetragen haben. Auf fremden Domains rendert das Widget nicht.
Ergebnis: Nach erfolgreicher Prüfung legt das Widget im umschließenden Formular ein verstecktes Feld namens byebot-token ab.
Build: Kein Build-Schritt, keine Bibliothek, kein Framework nötig.

Server

Schritt 2: Wie prüfe ich das Ergebnis auf dem Server?

Mit einer POST-Anfrage, bevor Sie das Formular annehmen.

HTTP

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.

JavaScript

// Node.js / Express
const antwort = await fetch("https://challenge.byebot.de/validate_token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: process.env.BYEBOT_API_KEY,
    token: req.body["byebot-token"],
  }),
});

if (!antwort.ok) {
  return res.status(400).send("CAPTCHA-Prüfung fehlgeschlagen");
}
// ab hier das Formular verarbeiten

Erfolg: Antwort 200 mit einem JSON-Objekt, das unter anderem success, sitekey, challenged_at, solve_time_ms und interactive_solved enthält.
Fehlschlag: Antwort 400. Ein bereits eingelöstes Ergebnis wird abgelehnt, ein zweites Einreichen desselben Wertes also ebenfalls.
API-Schlüssel: Bleibt auf dem Server, in einer Umgebungsvariablen. Niemals im ausgelieferten Frontend.

Frameworks

Schritt 3: Wie integriere ich das in mein Framework?

Gleiches Muster, andere Syntax.

React, Next.js: Container als Komponente, Render-Aufruf nach dem Mount.
Vue, Angular, Svelte: Dieselbe Logik im jeweiligen Lifecycle-Hook.
Express, Django, Go, Rails, Rust: Die Prüfung als Middleware oder direkt im Formular-Handler.
WordPress: Per Plugin, ohne eigenen Code.
Native Apps: SDKs für React Native, Android und iOS. Das Widget läuft dort in einer WebView.

In Anwendungen, die das Formular erst nachträglich in den DOM hängen, stoßen Sie das Rendern selbst an:

JavaScript

// Wenn das Formular erst nachträglich in den DOM kommt
window.Byebot.render(element);   // ein einzelner Container
window.Byebot.renderAll();       // alle Container auf der Seite

Vollständige Beispiele für über zehn Frameworks stehen in der ByeBot-Dokumentation.

Fehler

Welche Fehler kosten den Schutz?

Vier, und der erste macht das Widget wirkungslos.

Was hält und was nur so aussieht

Hält

Wirksam eingebunden

Serverseitige Prüfung vor der Annahme
API-Schlüssel in einer Umgebungsvariablen
Domain im Dashboard eingetragen
Fehlerfall mit Meldung und neuem Versuch

Fällt durch

Sieht nur richtig aus

Nur im Browser geprüft
API-Schlüssel im Frontend
Entwicklungs-Domain fehlt
Formular wird stumm verworfen

Die rechte Spalte beschreibt Einbindungen, die im Browser korrekt aussehen und trotzdem nichts abhalten.

Nur im Browser: Ein Bot schickt das Formular direkt per HTTP-Anfrage ab und sieht das Widget nie. Ohne die Prüfung auf dem Server ist der Schutz Dekoration.
Schlüssel sichtbar: Im ausgelieferten Frontend ist der API-Schlüssel für jeden lesbar und damit für jeden nutzbar.
Domain fehlt: Das Widget rendert nur auf hinterlegten Domains. Für lokale Entwicklung braucht es einen eigenen Eintrag oder einen Test-Sitekey.
Stummer Fehler: Bei einer fehlgeschlagenen Prüfung braucht der Besucher eine verständliche Meldung und einen zweiten Versuch.

Häufige Fragen

Fragen zur Einbindung.

Kurze Antworten zu Antwortcodes, Schlüsseln, Domains, Rendern und nativen Apps.

Was passiert, wenn dasselbe Ergebnis zweimal eingereicht wird?

Der Validierungsendpunkt lehnt es ab. Ein bereits eingelöstes Ergebnis wird abgelehnt, ein zweites Einreichen desselben Wertes also ebenfalls. Die Antwort ist dann 400 und das Formular wird abgelehnt. Bei Erfolg antwortet der Endpunkt mit 200 und einem JSON-Objekt, das unter anderem success, sitekey, challenged_at, solve_time_ms und interactive_solved enthält.

Wohin gehört der API-Schlüssel?

Er bleibt auf dem Server, in einer Umgebungsvariablen, niemals im ausgelieferten Frontend. Dort ist er für jeden lesbar und damit für jeden nutzbar. Öffentlich ist nur der Sitekey. Er ist an die Domains gebunden, die Sie im Dashboard eingetragen haben, und auf fremden Domains rendert das Widget nicht.

Warum bleibt der Container in der lokalen Entwicklung leer?

Das Widget rendert nur auf hinterlegten Domains. Für lokale Entwicklung braucht es einen eigenen Eintrag oder einen Test-Sitekey. Die fehlende Entwicklungs-Domain steht in der Gegenüberstellung auf dieser Seite in der Spalte, die im Browser korrekt aussieht und trotzdem nichts abhält.

Braucht die Einbindung einen Build-Schritt?

Nein. Kein Build-Schritt, keine Bibliothek, kein Framework nötig. Das Widget rendert sich in jedes Element mit der Klasse captcha-widget. In Anwendungen, die das Formular erst nachträglich in den DOM hängen, stoßen Sie das Rendern selbst an: window.Byebot.render für einen einzelnen Container, window.Byebot.renderAll für alle Container auf der Seite.

Was gehört in die Fehlerbehandlung, wenn eine Prüfung fehlschlägt?

Bei einer fehlgeschlagenen Prüfung braucht der Besucher eine verständliche Meldung und einen zweiten Versuch. Ein Formular, das stumm verworfen wird, gehört auf dieser Seite zu den vier Fehlern, die im Browser korrekt aussehen.

Läuft das Widget in einer nativen App?

Ja, über SDKs für React Native, Android und iOS. Das Widget läuft dort in einer WebView. Im Web ist das Muster framework-unabhängig: ein Container im Markup, ein POST im Backend. Vollständige Beispiele für über zehn Frameworks stehen in der ByeBot-Dokumentation, von React und Vue bis WordPress.

Weiterlesen.

Testphase

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.

Kostenlos testen Dokumentation