Dokumentation

SmartCaptcha Integration

Widget einbinden → Token beim Submit → serverseitig verifizieren. Ohne sichtbares Captcha.

Quickstart Widget Verify

1WidgetToken automatisch beim Submit holen.
2VerifyToken serverseitig mit Secret prüfen.
3ErgebnisAllow/Deny + Score + Reason.

Quickstart

Key erstellen → Widget einbinden → Verify im Backend.

Voraussetzungen

Im Dashboard eine Website angelegt (pro Website 1 Domain/Origin).
Key erstellt und Secret einmalig kopiert.
Domain als Origin erlaubt (z.B. https://example.com).

Wichtig

Das secret niemals im Frontend speichern.

Standard-Einbindung:

html

<!-- SmartCaptcha Widget: unsichtbarer Spam-Schutz -->
<script
  src="https://app.smartcaptcha.de/widget.js"
  data-sitekey="sk_..."
  data-action="contact"
  defer
></script>

<form data-smartcaptcha method="post" action="/kontakt">
  <!-- deine Felder; das Widget ergänzt automatisch
       smartcaptcha_token und smartcaptcha_sid -->
</form>

Optional: nur Forms mit data-smartcaptcha:

html

<form data-smartcaptcha method="post" action="/contact">
  <input name="name" />
  <input name="email" />
  <button type="submit">Senden</button>
</form>

Hinweis

Das Widget fügt automatisch smartcaptcha_token hinzu.

Server Verify

Token + siteKey + secret an /v1/verify senden → allow/deny.

Native PHP (cURL) Beispiel:

php

<?php
$apiBase = 'https://app.smartcaptcha.de';
$siteKey = 'sk_...';
$secret  = 'sec_...';   // nur im Backend, nie im Frontend
$action  = 'contact';   // muss zur data-action des Widgets passen

// Auch ohne Token /v1/verify aufrufen: Bots posten das Formular oft direkt (ohne JavaScript).
// Die API lehnt dann mit "missing_token" ab und zählt den Block in deinem Dashboard.
$token = (string)($_POST['smartcaptcha_token'] ?? '');
$sid   = (string)($_POST['smartcaptcha_sid'] ?? '');

$payload = json_encode([
  'siteKey' => $siteKey,
  'secret'  => $secret,
  'token'   => $token,
  'sid'     => $sid,
  'action'  => $action,
], JSON_THROW_ON_ERROR);

$ch = curl_init($apiBase . '/v1/verify');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_TIMEOUT => 6,
  CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
  CURLOPT_POSTFIELDS => $payload,
]);

$res  = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode((string)$res, true) ?: [];

if ($code !== 200 || empty($data['ok'])) {
  // 400 = Token fehlt/abgelaufen/ungültig, 402 = Abo nicht aktiv, 403 = als Bot eingestuft
  // Fail-closed: auch bei Netzwerkfehlern (code 0) nicht durchlassen.
  http_response_code(403);
  exit('Anfrage blockiert (' . ($data['reason'] ?? 'unknown') . ').');
}

// Mensch: Formular normal verarbeiten
echo 'OK';

Immer /v1/verify aufrufen – auch ohne Token

Prüfe ein fehlendes Token nicht nur lokal. Schick die Anfrage trotzdem mit leerem token an /v1/verify: Die API lehnt mit missing_token ab und zählt den Block im Dashboard (Auswertung → Blockiert). Sonst bleiben genau die Bots unsichtbar, die das Formular ohne Browser direkt absenden. Gezählt wird nur mit gültigem Secret.

Fail-closed

Empfohlen: Wenn Verify fehlschlägt → Submission blocken.

Widget-Optionen

Modus, Design, Sprache und Ereignisse.

Modus: smart (Standard) prüft still und bittet nur bei schwachen Signalen um ein kurzes Halten. auto verzichtet auf das Halten, strict verlangt es immer, invisible zeigt gar kein Element, nur eine kleine Hinweiszeile (data-badge="none" blendet auch die aus).

html

<!-- Alle Optionen sind freiwillig -->
<script
  src="https://app.smartcaptcha.de/widget.js"
  data-sitekey="sk_..."
  data-action="contact"      <!-- Name des Formulars, muss zum Key passen -->
  data-mode="smart"          <!-- smart | auto | strict | invisible -->
  data-theme="auto"          <!-- auto | light | dark -->
  data-size="normal"         <!-- normal | compact -->
  data-lang="de"             <!-- de | en -->
  defer
></script>

<!-- Je Formular überschreibbar -->
<form data-smartcaptcha data-smartcaptcha-action="login" data-smartcaptcha-mode="strict">
  …
</form>

Das Widget holt das Token schon während des Ausfüllens und erneuert es vor Ablauf. Beim Absenden wird das Formular normal abgeschickt, mit den Feldern smartcaptcha_token und smartcaptcha_sid.

// Für eigene AJAX-Formulare: Token abwarten, dann selbst senden
const form = document.querySelector('form[data-smartcaptcha]');

form.addEventListener('smartcaptcha:verified', (e) => {
  // e.detail.token liegt bereits im Feld smartcaptcha_token
});

// Nach eigenem AJAX-Versand ein frisches Token holen (jedes Token gilt einmal)
await window.SmartCaptcha.refresh(form);

Ereignisse

smartcaptcha:ready, smartcaptcha:token, smartcaptcha:verified, smartcaptcha:error, smartcaptcha:needs-interaction und smartcaptcha:reset werden am Formular ausgelöst.