Einbindung CAPTCHA

Voraussetzung

Legen Sie zunächst ein Konto auf BerlinSMS an, um das CAPTCHA von BerlinSMS verwenden zu können. Loggen Sie sich anschließend auf https://app.berlinsms.de ein und laden sie sich den Sitekey und den Secretkey herunter.

→ So bekomme ich dem CAPTCHA–Sitekey?

Einbindungen

Tutorial: BerlinSMS Captcha einbinden

Clientseitig – per HTML/JS

Die Einbindung des Captchas setzt ein HTML-Formular mit Benutzereingaben voraus. Dies kann ein Kontaktformular, Registrierungsformular, Kommentarfeld oder jedes andere Formular mit Benutzereingaben sein.

Beispiel: Demo-Formular ohne Widget

Unser Captcha-Widget fügt eine Validierung hinzu, die überprüft, ob die Eingabe von einem Menschen stammt. Die Validierung erfolgt noch vor dem Abschicken des Formulars.

Schritt 1: Script einbinden

Um das Captcha-Widget zu integrieren, binden Sie folgenden CSS- und JavaScript-Tag im HTML-Dokument des Formulars ein: (Sie können die Dateien auch lokal hosten, um entfernte Aufrufe zu vermeiden)

<link rel="stylesheet" href="https://unpkg.com/@berlinsms/plain-js-captcha/dist/bsms-captcha.css">
<script src="https://unpkg.com/@berlinsms/plain-js-captcha/dist/bsms-captcha.js"></script>

Tipp: Platzieren Sie das CSS im <head> und das JavaScript vor dem schließenden </body>-Tag.

Schritt 2: Captcha-Container hinzufügen

Fügen Sie nun einen Container für das Captcha in Ihr Formular ein. Platzieren Sie ihn idealerweise vor dem Submit-Button.

<!-- Minimaler Container -->
<div class="bsms-captcha-container"></div>

Beispiel: Demo-Formular ohne Sitekey

Nun wird das Widget angezeigt. Erhalten Sie die folgende Fehlermeldung, fehlt der Sitekey.

⚠️ Fehler: "Captcha sitekey is required"

Schritt 3: Sitekey hinzufügen

Sie können das Widget mit mehreren Parametern anpassen. Bitte fügen Sie unbedingt den bsmsSitekey hinzu!

Link: Wie erhalte ich einen Sitekey?

Fügen Sie den Sitekey als data-sitekey Attribut zum Container hinzu:

<div class="bsms-captcha-container" 
     data-sitekey="[Ihr-Sitekey]">
</div>

Beispiel: Demo-Formular ohne Callback

Damit funktioniert nun das Captcha-Widget grundsätzlich.

Schritt 4: Submit-Button erst nach Validierung aktivieren

Allerdings empfehlen wir Ihnen, den Submit-Button noch nicht zu aktivieren, denn das Formular lässt sich im Moment auch ohne Captcha-Validierung abschicken. Die Überprüfung des Tokens auf Seiten des Servers würde fehlschlagen.

Um den Button bis zur Validierung inaktiv zu lassen, setzen Sie ihn initial auf „disabled". Fügen Sie außerdem eine eindeutige ID (z.B. „send-form") hinzu:

<button type="submit" id="send-form" disabled>
    Absenden
</button>

Schritt 5: Callback für Validierung einrichten

Um den Button nach der erfolgreichen Captcha-Validierung wieder auf „enabled" zu stellen, haben Sie zwei Möglichkeiten:

Variante A: Per data-Attribut (empfohlen)

<div class="bsms-captcha-container" 
     data-sitekey="[Ihr-Sitekey]"
     data-callback="onCaptchaSuccess">
</div>

<script>
    function onCaptchaSuccess(token) {
        console.log('Captcha erfolgreich validiert!', token);
        document.getElementById("send-form").disabled = false;
    }
</script>

Variante B: Per URL-Parameter im Script-Tag

<!-- Konfiguration im Script-Tag -->
<script src="...?bsmsSitekey=[Ihr-Sitekey]&callback=onCaptchaSuccess"></script>

<!-- Minimaler Container -->
<div class="bsms-captcha-container"></div>

<script>
    function onCaptchaSuccess(token) {
        console.log('Captcha erfolgreich validiert!', token);
        document.getElementById("send-form").disabled = false;
    }
</script>

Beide Varianten sind gleichwertig! Wählen Sie die Methode, die besser zu Ihrem Projekt passt.

Beispiel Variante A: Demo-Formular mit data-Attributen
Beispiel Variante B: Demo-Formular mit URL-Parametern

Nun lässt sich das Formular erst nach erfolgreicher Captcha-Validierung abschicken.

Vollständiges Beispiel

<!DOCTYPE html>
<html lang="de">
<head>
    <meta charset="UTF-8">
    <title>Kontaktformular mit Captcha</title>

    <!-- Captcha CSS -->
    <link rel="stylesheet" href="https://unpkg.com/@berlinsms/plain-js-captcha/dist/bsms-captcha.css">
</head>
<body>
    <h1>Kontaktformular</h1>

    <form id="contactForm" method="POST" action="/submit">
        <div>
            <label for="name">Name:</label>
            <input type="text" id="name" name="name" required>
        </div>

        <div>
            <label for="email">E-Mail:</label>
            <input type="email" id="email" name="email" required>
        </div>

        <div>
            <label for="message">Nachricht:</label>
            <textarea id="message" name="message" required></textarea>
        </div>

        <!-- Captcha-Widget -->
        <div class="bsms-captcha-container" 
             data-sitekey="IHR-SITEKEY-HIER"
             data-callback="onCaptchaSuccess"
             data-error-callback="onCaptchaError"
             data-expired-callback="onCaptchaExpired">
        </div>

        <button type="submit" id="send-form" disabled>
            Nachricht senden
        </button>
    </form>

    <!-- Captcha JavaScript -->
    <script src="https://unpkg.com/@berlinsms/plain-js-captcha/dist/bsms-captcha.js"></script>

    <script>
        function onCaptchaSuccess(token) {
            console.log('✅ Captcha erfolgreich!', token);
            document.getElementById("send-form").disabled = false;
        }

        function onCaptchaError(error) {
            console.error('❌ Captcha Fehler:', error);
            alert('Captcha-Fehler: ' + error);
        }

        function onCaptchaExpired() {
            console.log('⏰ Captcha abgelaufen');
            document.getElementById("send-form").disabled = true;
            alert('Das Captcha ist abgelaufen. Bitte erneut durchführen.');
        }
    </script>
</body>
</html>

Serverseitige Validierung

Wichtig: Die Captcha-Validierung muss auch serverseitig überprüft werden!

Nach dem Absenden des Formulars enthält das POST-Request ein Hidden-Input-Feld mit dem Namen bsms-captcha-token:

<input type="hidden" name="bsms-captcha-token" value="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...">

PHP-Beispiel:

<?php
$token = $_POST['bsms-captcha-token'];
$sitekey = 'IHR-SITEKEY';

// Token an BerlinSMS API senden
$response = file_get_contents('https://api.berlinsms.de/captcha/verify', false, stream_context_create([
    'http' => [
        'method' => 'POST',
        'header' => 'Content-Type: application/json',
        'content' => json_encode([
            'token' => $token,
            'sitekey' => $sitekey
        ])
    ]
]));

$result = json_decode($response, true);

if ($result['success']) {
    // Captcha ist gültig - Formular verarbeiten
    echo "Formular erfolgreich gesendet!";
} else {
    // Captcha ungültig
    http_response_code(400);
    echo "Captcha-Validierung fehlgeschlagen!";
}
?>

Node.js/Express-Beispiel:

app.post('/submit', async (req, res) => {
    const token = req.body['bsms-captcha-token'];
    const sitekey = 'IHR-SITEKEY';

    // Token validieren
    const response = await fetch('https://api.berlinsms.de/captcha/verify', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ token, sitekey })
    });

    const result = await response.json();

    if (result.success) {
        // Captcha gültig - Formular verarbeiten
        res.send('Formular erfolgreich gesendet!');
    } else {
        // Captcha ungültig
        res.status(400).send('Captcha-Validierung fehlgeschlagen!');
    }
});

Weitere Konfigurationsoptionen

Start-Modus festlegen

Das Captcha kann automatisch oder per Klick gestartet werden:

<!-- Automatischer Start (Standard) -->
<div class="bsms-captcha-container" 
     data-sitekey="IHR-SITEKEY"
     data-start="auto">
</div>

<!-- Start per Klick -->
<div class="bsms-captcha-container" 
     data-sitekey="IHR-SITEKEY"
     data-start="click">
</div>

Mehrere Captchas auf einer Seite

Sie können beliebig viele Captchas auf einer Seite einbinden:

<!-- Captcha 1 -->
<div class="bsms-captcha-container" 
     id="captcha1"
     data-sitekey="IHR-SITEKEY"
     data-callback="onSuccess1">
</div>

<!-- Captcha 2 -->
<div class="bsms-captcha-container" 
     id="captcha2"
     data-sitekey="IHR-SITEKEY"
     data-callback="onSuccess2">
</div>

<script>
    function onSuccess1(token) {
        console.log('Captcha 1 erfolgreich:', token);
    }

    function onSuccess2(token) {
        console.log('Captcha 2 erfolgreich:', token);
    }
</script>

Captcha programmatisch zurücksetzen

Sie können das Captcha über die globale API zurücksetzen:

// Reset per Container-ID
bsmsCaptcha.reset('captcha1');

// Token abrufen
var token = bsmsCaptcha.getResponse('captcha1');
console.log(token);

Häufige Anwendungsfälle

1. Kontaktformular

Schützt vor Spam-Anfragen über Kontaktformulare.

2. Registrierungsformular

Verhindert automatisierte Bot-Registrierungen.

3. Kommentar-Funktion

Schützt Blogs und Foren vor Spam-Kommentaren.

4. Download-Formular

Verhindert automatisierte Downloads.

5. Newsletter-Anmeldung

Schützt vor Fake-Anmeldungen.

6. Passwort-Reset

Zusätzliche Sicherheit bei sensiblen Aktionen.

Support & Dokumentation

Vollständige Dokumentation: GitHub README
Live-Demos: Demo-Seite
API-Dokumentation: API-Docs
Support: support@berlinsms.de

Zusammenfassung

In 5 Schritten zum fertigen Captcha:

✅ CSS & JavaScript einbinden
✅ Container mit class="bsms-captcha-container" hinzufügen
✅ Sitekey mit data-sitekey setzen
✅ Submit-Button initial auf disabled setzen
✅ Callback-Funktion mit data-callback definieren

Fertig! Ihr Formular ist jetzt vor Bots geschützt. 🎉