HamCaptcha
← Zpět na přehled

Ukázková integrace — jak chránit formulář

Tři kroky: vložíte widget do svého formuláře s veřejným projectKey, uživatel opíše volačku a widget přidá do formuláře jednorázový token, a váš backend ten token po odeslání ověří tajným secret. Níže je copy-paste kód i živá ukázka, kterou si vyzkoušíte s vlastním klíčem projektu.

Postup integrace

1
Vložte widget do formuláře

Načtěte skript /v2/api.js a do chráněného <form> přidejte <div class="hamcaptcha" data-projectkey="…">. Widget se sám vykreslí a po správném opsání volačky vloží do formuláře skryté pole hamcaptcha-token.

HTML — vložení do stránky klienta
<script src="https://<hamcaptcha>/v2/api.js" async defer></script>

<form method="post" action="/registrace">
  <input name="email" type="email" required>

  <!-- widget se vykreslí sem; po vyřešení doplní skryté pole hamcaptcha-token -->
  <div class="hamcaptcha" data-projectkey="<PROJECT_KEY>"></div>

  <button>Odeslat</button>
</form>
2
Token přijde s formulářem

Po odeslání formuláře dorazí na váš backend mezi poli i hamcaptcha-token. Volitelně lze reagovat hned přes data-on-success (např. povolit tlačítko Odeslat).

3
Ověřte token na backendu (povinné)

Přítomnost tokenu ve formuláři sama o sobě nic nedokazuje — vždy ho ověřte server-side svým secret na POST /v2/verify.

Backend — ověření tokenu (curl)
curl -X POST https://<hamcaptcha>/v2/verify \
  -H 'Content-Type: application/json' \
  -d '{"secret": "<SECRET>", "token": "<hamcaptcha-token z formuláře>"}'

→ {"success": true, "solved_at": "2026-06-11T15:14:30Z", "hostname": "klient.cz", "errors": []}
  success:false znamená odmítnout odeslání (viz pole errors)
Backend — ověření tokenu (Java / Spring)
record VerifyRequest(String secret, String token) {}
record VerifyResponse(boolean success, List<String> errors) {}

// po odeslání formuláře: token je v poli "hamcaptcha-token"
VerifyResponse v = restClient.post()
        .uri("https://<hamcaptcha>/v2/verify")
        .body(new VerifyRequest(secret, captchaToken))   // secret z konfigurace
        .retrieve()
        .body(VerifyResponse.class);

if (v == null || !v.success()) {
    // nechat uživatele vyřešit novou captchu
}

Widget v obou jazycích

Jazyk widgetu určuje parametr data-language (cs | en) při vložení. Níže je tentýž widget vykreslený v obou jazycích.

Čeština — data-language="cs"
English — data-language="en"

Živá ukázka

Ukázkový formulář chráněný widgetem (pevný projectKey demo projektu). Po opsání volačky a odeslání uvidíte přesně to, co by dostal váš backend (pole formuláře včetně hamcaptcha-token) i hotový curl pro ověření. Tajný secret do prohlížeče nikdy nepatří — ověření provádí vždy backend.

Ukázkový registrační formulář

Pozn.: výpis níže je jen simulace v prohlížeči — tento JavaScript ve svém projektu nepíšeš. Server-side ověření tokenu řeší tvůj backend (viz příklady v Javě/PHP výše).