✅ Keine Abhängigkeiten - Pure Vanilla JavaScript
✅ Framework-agnostisch - Funktioniert überall (React, Vue, Angular, oder plain HTML)
✅ Automatische Hidden Inputs - Token wird ins Formular eingefügt
✅ Flexible Konfiguration - Auto-Start oder Click-Start
✅ Callbacks - onComplete, onError, onExpire
✅ Responsive Design - Funktioniert auf allen Geräten
✅ Browser-kompatibel - Chrome, Firefox, Safari, Edge
✅ TypeScript-ready - Kann problemlos in TypeScript-Projekten verwendet werden

📦 Installation

Via NPM (empfohlen für Build-Prozesse)

npm install @berlinsms/plain-js-captcha

Via CDN (für direktes Einbinden)

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

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

Manueller Download

Lade die Dateien aus dem dist/ Ordner herunter:

bsms-captcha.js
bsms-captcha.css

🚀 Schnellstart - Auto-Initialisierung (wie reCAPTCHA)

Einfachste Methode - Keine manuelle Initialisierung nötig!

1. Dateien einbinden

<!DOCTYPE html>
<html>
<head>
    <!-- CSS -->
    <link rel="stylesheet" href="https://unpkg.com/@berlinsms/plain-js-captcha/dist/bsms-captcha.css">
</head>
<body>
    <!-- JavaScript -->
    <script src="https://unpkg.com/@berlinsms/plain-js-captcha/dist/bsms-captcha.js"></script>
</body>
</html>

2. Captcha-Container mit data-Attributen

<form id="myForm">
    <input type="text" name="username" required>
    <input type="email" name="email" required>

    <!-- Captcha wird AUTOMATISCH initialisiert! -->
    <div class="bsms-captcha-container" 
         data-sitekey="YOUR-SITEKEY"
         data-callback="onCaptchaComplete"
         data-error-callback="onCaptchaError"
         data-expired-callback="onCaptchaExpired">
    </div>

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

3. Callback-Funktionen definieren

// Globale Callback-Funktionen
function onCaptchaComplete(token) {
    console.log('Captcha abgeschlossen! Token:', token);
    // Formular-Submit erlauben
}

function onCaptchaError(error) {
    console.error('Captcha Fehler:', error);
}

function onCaptchaExpired() {
    console.log('Captcha abgelaufen');
}

Fertig! 🎉 Das Captcha wird automatisch beim Laden der Seite initialisiert.

🎛️ Alternative: Manuelle Initialisierung

Falls du mehr Kontrolle brauchst:

var captcha = new BSMSCaptcha({
    sitekey: 'YOUR-SITEKEY',
    container: document.getElementById('captcha-container'),
    form: document.getElementById('myForm'),
    start: 'auto', // oder 'click'

    onComplete: function(token) {
        console.log('Captcha completed!', token);
    },

    onError: function(error) {
        console.error('Error:', error);
    },

    onExpire: function() {
        console.log('Expired');
    }
});
});

📖 Verwendung mit Bundlern (webpack, vite, etc.)

Mit ES6 Import

import '@berlinsms/plain-js-captcha/dist/bsms-captcha.css';
// BSMSCaptcha ist global verfügbar
const captcha = new BSMSCaptcha({ /* ... */ });

Mit CommonJS

require('@berlinsms/plain-js-captcha/dist/bsms-captcha.css');
const BSMSCaptcha = require('@berlinsms/plain-js-captcha');

In React

import { useEffect, useRef } from 'react';
import '@berlinsms/plain-js-captcha/dist/bsms-captcha.css';

function MyForm() {
    const captchaRef = useRef(null);
    const containerRef = useRef(null);

    useEffect(() => {
        if (containerRef.current) {
            captchaRef.current = new BSMSCaptcha({
                sitekey: 'YOUR-SITEKEY',
                container: containerRef.current,
                onComplete: (token) => console.log('Done!', token)
            });
        }
        return () => {
            if (captchaRef.current) captchaRef.current.destroy();
        };
    }, []);

    return <div ref={containerRef}></div>;
}

⚙️ Konfigurationsoptionen

data-Attribute (für Auto-Initialisierung)

Attribut	Typ	Erforderlich	Beschreibung
`data-sitekey`	string	✅ Ja	Ihr BerlinSMS Sitekey
`data-callback`	string	❌ Nein	Name der globalen Callback-Funktion (onComplete)
`data-error-callback`	string	❌ Nein	Name der globalen Error-Callback-Funktion
`data-expired-callback`	string	❌ Nein	Name der globalen Expire-Callback-Funktion
`data-start`	string	❌ Nein	`'auto'` (Standard) oder `'click'`

JavaScript-Optionen (für manuelle Initialisierung)

Option	Typ	Standard	Beschreibung
`sitekey`	string	erforderlich	Ihr BerlinSMS Sitekey
`container`	HTMLElement	erforderlich	Container-Element für das Captcha
`form`	HTMLFormElement	`null`	Formular, in das Hidden-Inputs eingefügt werden
`start`	string	`'auto'`	`'auto'` oder `'click'`
`className`	string	`'captcha'`	Zusätzliche CSS-Klasse
`onComplete`	function	-	Callback bei erfolgreicher Validierung
`onError`	function	-	Callback bei Fehler
`onExpire`	function	-	Callback bei Ablauf

🌐 Globale API (bsmsCaptcha)

Das Script stellt eine globale bsmsCaptcha API zur Verfügung:

`bsmsCaptcha.reset(containerId)`

Setzt ein Captcha zurück.

bsmsCaptcha.reset('myCaptcha');
// oder mit Element-Referenz
bsmsCaptcha.reset(document.getElementById('myCaptcha'));

`bsmsCaptcha.getResponse(containerId)`

Holt den Token aus einem Captcha.

var token = bsmsCaptcha.getResponse('myCaptcha');
console.log(token);

`bsmsCaptcha.render(containerId, options)`

Manuelles Rendern eines Captchas.

bsmsCaptcha.render('myCaptcha', {
    sitekey: 'YOUR-SITEKEY',
    start: 'auto'
});

`bsmsCaptcha.renderAll()`

Re-rendert alle Captchas auf der Seite.

bsmsCaptcha.renderAll();

📋 Hidden Inputs

Nach erfolgreicher Captcha-Validierung werden automatisch folgende Hidden-Inputs in das Formular eingefügt:

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

Diese Werte werden beim Formular-Submit automatisch mitgesendet.

🔧 API-Methoden

`captcha.reset()`

Setzt das Captcha zurück in den Ausgangszustand.

captcha.reset();

`captcha.destroy()`

Entfernt das Captcha vollständig und bereinigt alle Ressourcen.

captcha.destroy();

🎨 Start-Modi

Auto-Start (`start: 'auto'`)

Das Captcha startet automatisch nach dem Laden:

var captcha = new BSMSCaptcha({
    sitekey: 'YOUR-SITEKEY',
    container: document.getElementById('captcha-container'),
    start: 'auto'
});

Click-Start (`start: 'click'`)

Das Captcha muss vom Benutzer manuell gestartet werden:

var captcha = new BSMSCaptcha({
    sitekey: 'YOUR-SITEKEY',
    container: document.getElementById('captcha-container'),
    start: 'click'
});

🔐 Server-seitige Validierung

Nach dem Absenden des Formulars müssen Sie das Captcha-Token auf Ihrem Server validieren:

// Beispiel für Node.js/Express
app.post('/submit', async (req, res) => {
    const token = req.body['bsms-captcha-token'];
    
    // Token an BerlinSMS API senden zur Validierung
    const response = await fetch('https://api.berlinsms.de/captcha/verify', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ 
            token: token,
            sitekey: 'YOUR-SITEKEY'
        })
    });
    
    const result = await response.json();
    
    if (result.success) {
        // Captcha ist gültig
        // Formular verarbeiten...
    } else {
        // Captcha ist ungültig
        res.status(400).send('Captcha validation failed');
    }
});

🎯 Vollständiges Beispiel

<!DOCTYPE html>
<html lang="de">
<head>
    <meta charset="UTF-8">
    <title>Captcha Beispiel</title>
    <link rel="stylesheet" href="bsms-captcha.css">
</head>
<body>
    <form id="contactForm">
        <div>
            <label>Name:</label>
            <input type="text" name="name" required>
        </div>
        
        <div>
            <label>E-Mail:</label>
            <input type="email" name="email" required>
        </div>
        
        <div>
            <label>Nachricht:</label>
            <textarea name="message" required></textarea>
        </div>
        
        <!-- Captcha -->
        <div id="captcha-widget"></div>
        
        <button type="submit" id="submitBtn" disabled>Senden</button>
    </form>

    <script src="bsms-captcha.js"></script>
    <script>
        var form = document.getElementById('contactForm');
        var submitBtn = document.getElementById('submitBtn');
        
        // Captcha initialisieren
        var captcha = new BSMSCaptcha({
            sitekey: 'demo-sitekey-12345',
            container: document.getElementById('captcha-widget'),
            form: form,
            start: 'auto',
            
            onComplete: function(token) {
                // Submit-Button aktivieren
                submitBtn.disabled = false;
                console.log('Captcha completed:', token);
            },
            
            onError: function(error) {
                // Submit-Button deaktivieren
                submitBtn.disabled = true;
                alert('Captcha Fehler: ' + error);
            },
            
            onExpire: function() {
                // Submit-Button deaktivieren
                submitBtn.disabled = true;
                alert('Captcha ist abgelaufen. Bitte erneut durchführen.');
            }
        });
        
        // Formular-Submit
        form.addEventListener('submit', function(e) {
            e.preventDefault();
            
            var token = document.getElementById('bsms-captcha-token');
            if (!token || !token.value) {
                alert('Bitte Captcha vervollständigen!');
                return;
            }
            
            // Formular-Daten senden
            var formData = new FormData(form);
            
            fetch('/submit', {
                method: 'POST',
                body: formData
            })
            .then(response => response.json())
            .then(data => {
                alert('Formular erfolgreich gesendet!');
                form.reset();
                captcha.reset();
            })
            .catch(error => {
                alert('Fehler beim Senden: ' + error);
            });
        });
    </script>
</body>
</html>

🎨 Anpassung des Designs

Das Captcha kann über CSS-Variablen angepasst werden:

:root {
    --bmstwofa-c-brand1: #A13535;  /* Primärfarbe */
    --bmstwofa-c-brand2: #327E8B;  /* Sekundärfarbe */
    --bmstwofa-c-error: #d50303;   /* Fehlerfarbe */
    --bmstwofa-c-success: darkgreen; /* Erfolgsfarbe */
}

Oder eigene CSS-Klassen hinzufügen:

var captcha = new BSMSCaptcha({
    sitekey: 'YOUR-SITEKEY',
    container: document.getElementById('captcha-container'),
    className: 'custom-captcha'
});

.custom-captcha {
    border-radius: 10px;
    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
}

🌐 Browser-Kompatibilität

Chrome/Edge: ✅
Firefox: ✅
Safari: ✅
IE11: ⚠️ (mit Polyfills)

📝 Lizenz

MIT License - siehe plain-js-captcha/package.json

👥 Author

BerlinSMS

🆘 Support

Bei Problemen oder Fragen: support@berlinsms.de

Keywords

FAQs

What is @berlinsms/plain-js-captcha?

Is @berlinsms/plain-js-captcha well maintained?

Package last updated on 25 Mar 2026

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@berlinsms/plain-js-captcha

BerlinSMS Captcha - Plain JavaScript

✨ Features