Captcha-Integration

Erfahren Sie, wie Sie Ihre Formulare mit PrivateStater Captcha vor Bots und Spam schützen.
PrivateStater Captcha ist für Kunden mit VPN ausgelegt. (Googles Captcha-Produkt verlangt von VPN-Nutzern oft mehr als 10 Captcha-Lösungen.)

Funktionsweise

PrivateStater Captcha nutzt eine 3-stufige Prüfung:

1. Honeypot - Erkennt versteckte Felder, die Bots und KI automatisch ausfüllen.

Honeypot wirkt vor allem gegen weniger intelligente KI-Bots, kann aber auch Nutzer mit KI-Browsern blockieren. Deaktivieren Sie es, wenn Sie es nicht brauchen. Bei hochintelligenter KI wie Opus 4.6 oder 4.7 wird der Honeypot oft ignoriert.

2. Puzzle-Challenge - Der Nutzer zieht ein Puzzleteil an die passende Stelle
3. PoW (Proof of Work) - Argon2id-Hashing erhöht die Angriffskosten für Bots.

Skriptinstallation

Nutzen Sie die Methoden in diesem Dokument, um privatestater.js zu installieren.

Überspringen Sie diesen Abschnitt, wenn Sie das Skript bereits installiert haben.

Captcha im Dashboard aktivieren

1. Gehen Sie zu Dashboard > Website > Captcha > Einstellungen
2. Schalten Sie Captcha aktivieren ein
3. Konfigurieren Sie die Optionen nach Bedarf

Konfigurationsoptionen

PoW-Schwierigkeitsstufen

Höhere Schwierigkeit blockiert Bots besser, verlängert aber die Wartezeit für Nutzer.

Captcha-Widget hinzufügen

Methode 1: Auto-Initialisierung (empfohlen)

Fügen Sie ein div mit dem Attribut data-captcha an der gewünschten Stelle im Formular ein:

<form id="contact-form">
    <input type="text" name="name" placeholder="Name">
    <input type="email" name="email" placeholder="Email">
    
    <!-- Captcha Widget -->
    <div data-captcha="prst"></div>
    
    <button type="submit">Submit</button>
</form>

Das Captcha-Widget erscheint beim Laden der Seite automatisch.

Methode 2: Programmatisch

Sie können das Captcha dynamisch per JavaScript anzeigen:

window.PrivateStater.showCaptcha({
    container: document.getElementById('captcha-container'),
    onSuccess: function(token) {
        console.log('Verification successful! Token:', token);
        // Send token to your server
    },
    onError: function(error) {
        console.error('Verification failed:', error);
    }
});

showCaptcha-Optionen

Rückgabewert

showCaptcha gibt ein Objekt mit folgenden Methoden zurück:

const captcha = await window.PrivateStater.showCaptcha({...});

// Remove widget
captcha.destroy();

Callback verarbeiten

Auto-Initialisierung (data-captcha)

Definieren Sie globale Callback-Funktionen:

<script>
    window.onPrivateStaterCaptchaSuccess = function(token) {
        console.log('Captcha verification successful!');
        
        // Add token to form
        document.getElementById('captcha-token').value = token;
        
        // Or submit form directly
        document.getElementById('contact-form').submit();
    };

    window.onPrivateStaterCaptchaError = function(error) {
        console.error('Captcha error:', error);
        alert('Captcha verification failed. Please try again.');
    };
</script>

Beispiel Formularübermittlung

<form id="contact-form" action="/submit" method="POST">
    <input type="text" name="name" required>
    <input type="email" name="email" required>
    
    <!-- Hidden field to store captcha token -->
    <input type="hidden" id="captcha-token" name="captchaToken">
    
    <!-- Captcha Widget -->
    <div data-captcha="prst"></div>
    
    <button type="submit">Submit</button>
</form>

<script>
    window.onPrivateStaterCaptchaSuccess = function(token) {
        document.getElementById('captcha-token').value = token;
    };
</script>

Token auf dem Server prüfen

Sie müssen das vom Client erhaltene Token auf Ihrem Server validieren.

API-Anfrage

const response = await fetch('https://privatestater.com/api/captcha/validate', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        websiteId: 'YOUR_SITE_ID',
        verifyToken: captchaToken
    })
});

const result = await response.json();
if (result.success) {
    // Captcha verification successful, proceed with form processing
} else {
    // Verification failed
    console.error('Captcha verification failed:', result.error);
}

Node.js/Express-Beispiel

app.post('/submit', async (req, res) => {
    const { name, email, captchaToken } = req.body;
    
    // Verify captcha token
    const captchaResponse = await fetch('https://privatestater.com/api/captcha/validate', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            websiteId: process.env.PRST_SITE_ID,
            verifyToken: captchaToken
        })
    });
    
    const captchaResult = await captchaResponse.json();
    
    if (!captchaResult.success) {
        return res.status(400).json({ error: 'Captcha verification failed' });
    }
    
    // Captcha verification successful, proceed with form processing
    // ...
    
    res.json({ success: true });
});

Antwort der Validierungs-API

Bei Erfolg:

{
    "success": true
}

Bei Fehler:

{
    "success": false,
    "error": "token_invalid_or_expired"
}

Wichtige Hinweise

• Tokens sind nur einmal verwendbar. Nach der Prüfung werden sie sofort verworfen.
• Tokens laufen nach 5 Minuten ab.
• Die Prüfung muss serverseitig erfolgen.

Captcha-Statistiken

Im Dashboard sehen Sie Captcha-Nutzungsstatistiken:

Styling

Das Captcha-Widget ist per Shadow DOM isoliert und wird von externem CSS nicht beeinflusst. Es passt sich automatisch an Dark und Light Mode an (Erkennung über prefers-color-scheme).

Mehrsprachigkeit

Das Captcha-Widget wird je nach Browsersprache automatisch auf Koreanisch oder Englisch angezeigt.
Für weitere Sprachen schreiben Sie mir an hello@privatestater.com, dann ergänze ich sie.

Fehlerbehebung

Captcha-Widget erscheint nicht

1. Prüfen Sie, ob Captcha im Dashboard aktiviert ist
2. Prüfen Sie die korrekte Skriptinstallation
3. Prüfen Sie die Konsole auf Fehler

Funktioniert nicht auf localhost

Aktivieren Sie Localhost erlauben im Dashboard.

Token-Validierung schlägt fehl

• Prüfen Sie, ob das Token abgelaufen ist (5 Minuten gültig)
• Prüfen Sie, ob das Token bereits verwendet wurde (Einmalnutzung)
• Prüfen Sie, ob websiteId korrekt ist

Fehlercodes