Widget auf der Website einbinden

Das Script-Tag einbauen, Formulare markieren und das Widget mit Modus, Design und Sprache anpassen.

Script-Tag einbauen

1Kopier im Dashboard unter „Websites & Keys“ beim Key „Script-Tag kopieren“.
2Füg es auf jeder Seite mit Formular ein, am besten vor dem schließenden </body>.
3Markiere die Formulare, die geschützt werden sollen, mit data-smartcaptcha.

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>

Das Widget holt das Token schon während des Ausfüllens und erneuert es vor Ablauf. Beim Absenden geht das Formular ganz normal raus, zusätzlich mit den Feldern smartcaptcha_token und smartcaptcha_sid. Diese prüft dein Backend.

Optionen

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>

Modus	Verhalten
`smart` (Standard)	Prüft still und bittet nur bei schwachen Signalen um ein kurzes Halten.
`auto`	Verzichtet auf das Halten.
`strict`	Verlangt das Halten immer.
`invisible`	Zeigt kein Element, nur eine kleine Hinweiszeile. `data-badge="none"` blendet auch die aus.

Eigene AJAX-Formulare

Das Widget löst am Formular die Ereignisse smartcaptcha:ready, smartcaptcha:token, smartcaptcha:verified, smartcaptcha:error, smartcaptcha:needs-interaction und smartcaptcha:reset aus. Jedes Token gilt genau einmal: Nach eigenem Versand per JavaScript ein neues holen.

javascript

// 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)

Wichtig

Das Widget allein schützt nichts. Erst die Prüfung im Backend entscheidet, ob das Formular angenommen wird. Das Secret gehört nie ins Frontend.

Noch Fragen? Wir helfen gern weiter.

Zum Kontaktformular

Stand: 5. Oktober 2026