Bezpečne integrujte SilentShield do svojho formulára

Klientsky skript, overenie na strane servera, kľúče a chybové stavy – kompletná integrácia na jednom mieste.

Rýchly štart Nastaviť testovaciu doménu

Ako spolupracuje skript a kontrola na serveri

Úplná integrácia má dve polovice: skript v prehliadači a kontrolu na vašom serveri.

1
Skript sa načíta
Vaša stránka načíta client.js?k=… s vaším kľúčom webu. Skript meria správanie vo formulári.
2
Formulár sa odošle
Pri odoslaní skript nahlási meranie a pridá do vášho formulára pole behavior_nonce.
3
Váš server sa opýta
Váš server pošle behavior_nonce na POST /api/v1/captcha/verify-nonce s vaším kľúčom v hlavičke X-Api-Key.
4
Rozhodujete vy
Odpoveď obsahuje ok, verdict, confidence a reason_codes. Ak je ok true, odoslanie prijmite, inak ho odmietnite.

Bez kroku 3 chráni integrácia len napoly: samotný skript nezastaví požiadavku odoslanú priamo na váš server.

Kľúč webu a serverový kľúč

Kľúč webu (verejný)

client.js?k=…

Je uvedený v zdrojovom kóde vašej stránky, a preto je viditeľný pre každého. Viaže skript na vašu doménu; subdomény ako www. alebo staging. sú zahrnuté.

Serverový kľúč (tajný, voliteľný)

X-Api-Key

Voliteľné. Ak chcete, aby volania, ktoré posiela váš server, obsahovali hodnotu, ktorá nie je v zdrojovom kóde vašej stránky, vytvorte ho v dashboarde pri kľúči na karte „Serverový kľúč“. Patrí iba na váš server, nikdy do prehliadača, a dá sa kedykoľvek vygenerovať znova.

Kontrola na serveri funguje už so samotným kľúčom stránky, takže nemusíte nič meniť. Prijímajú sa oba kľúče. So serverovým kľúčom kód vášho servera neobsahuje žiadnu hodnotu, ktorú si môže ktokoľvek prečítať v zdrojovom kóde vašej stránky.

Rýchly štart

Inštalácia a vloženie

Pridajte skript a získajte token

Overenie na serveri

Overte token na vašom backende

Rýchly test s cURL

Overenie nonce z príkazového riadku

# Overiť Nonce
curl -X POST https://api.silentshield.io/api/v1/captcha/verify-nonce \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nonce": "256ea6c63c3ccdd317e05cbc9ef0c659"}'

Frontend Integration

Add the client script with SRI and defer attributes

<!-- In <head> or before </body> of every page with a form -->
<script src="https://api.silentshield.io/client.js?k=YOUR_API_KEY" defer></script>

Bezpečnosť a súkromie

Žiadne cookies – prevádzka úplne bez cookies
Žiadne profily, žiadne cookies – použiteľné v súlade s GDPR
Hosting v EU – kontrola a ukladanie na našich serveroch v Nemecku
WCAG kompatibilné – prístupné pre všetkých používateľov
CSP kompatibilné – použitie s Content Security Policy:

Content-Security-Policy: script-src 'self' https://api-us.silentshield.io https://api-eu.silentshield.io; connect-src 'self' https://api-us.silentshield.io https://api-eu.silentshield.io; worker-src 'self' blob:;

SDK a Knižnice

Balík beží na vašom serveri (Node.js od 18). V prehliadači žiadny balík nepotrebujete — tam stačí úryvok client.js z rýchleho štartu.

Node.js / Express

v1.5.0

npm i @forge12interactive/silentshield-sdk-js

import { createClient } from "@forge12interactive/silentshield-sdk-js";

const shield = createClient({ apiKey: process.env.SILENTSHIELD_API_KEY });

app.post("/signup", async (req, res) => {
  const { human } = await shield.verify(req.body.behavior_nonce);
  if (!human) return res.status(403).send("Verification failed");
  res.send("ok");
});

NPM

AI agenti (Node.js)

v1.5.0

npm i @forge12interactive/silentshield-sdk-js

import { createClient, enforce } from "@forge12interactive/silentshield-sdk-js";

const shield = createClient({ apiKey: process.env.SILENTSHIELD_API_KEY });

// Reports bot candidates only — never blocks, never sees human traffic.
app.use(shield.observe);

// Applies your policy locally from a signed bundle. Fail-open.
app.use(enforce({ apiKey: process.env.SILENTSHIELD_API_KEY }));

NPM

Referencia API

API Version: 2025-10-01 · Base URL: https://api.silentshield.io

POST/api/v1/captcha/verify-nonce

Overiť SilentShield Nonce

Request Headers:

X-Api-KeyYOUR_API_KEY

Content-Typeapplication/json

Request Body:

noncestringNonce na overenie

Response:

Success (200):

{
  "ok": true,
  "verdict": "human",
  "confidence": 0.95,
  "requested_nonce": "256ea6c63c3ccdd317e05cbc9ef0c659"
}

Error:

{
  "ok": false,
  "verdict": "bot",
  "confidence": 0.12,
  "request_nonce": "256ea6c63c3ccdd317e05cbc9ef0c659",
  "reason_codes": ["NO_MOUSE_MOVEMENT"]
}

Status Codes:

200Nonce úspešne overený

400Neplatná požiadavka (chýbajúci alebo nesprávny Nonce)

401Neplatný API kľúč

403Nepotvrdené ako človek (ok: false) – odoslanie odmietnite

429Prekročený limit rýchlosti

500Vnútorná chyba servera

Časové limity, výpadky a kvóta

Nastavte pre kontrolu na serveri časový limit. Naše príklady kódu používajú 5 sekúnd.
Ak kontrola neodpovie včas, príklady to vyhodnotia ako „nepotvrdené“ a odmietnu. Ak v takom prípade radšej prijímate, zachyťte chybu sami — rozhodnutie je na vás.
Ak prvý host neodpovie, kým skript načítava svoje nastavenia a komponenty, prepne na druhý (api.silentshield.io a api-eu.silentshield.io). Kľúče s prísnou väzbou na EÚ zostávajú na hoste v EÚ.
Pre kontrolu na serveri neexistuje automatický záložný host.
Po prekročení mesačnej kvóty API ďalej kontroluje a odpovedá ako zvyčajne. Kód 429 znamená, že bol prekročený limit požiadaviek za minútu pre váš kľúč.

Testovanie lokálne a na testovacej doméne

Na localhost váš kľúč nefunguje: je viazaný na vašu doménu a skript je tam odmietnutý.
Testujte na subdoméne vašej domény, napríklad staging.vasa-domena.sk. Beží s kľúčom hlavnej domény a nezaberá ďalšie miesto pre doménu.
Ak chcete vyhodnocovať test a ostrú prevádzku oddelene, vytvorte pre tú istú doménu druhý kľúč. Ani ten nezaberá ďalšie miesto pre doménu.
Odošlite skúšobne formulár a na svojom serveri skontrolujte odpoveď verify-nonce: pri ručne zadanom vstupe by sa malo vrátiť ok: true; inak reason_codes ukazujú, prečo nie.

Nastaviť testovaciu doménu

Verzie a zmeny

API nesie svoju verziu v ceste: /api/v1. Rovnaké trasy sú dostupné aj pod /api.
Skript nemá číslo verzie: client.js vždy doručuje aktuálne vydanie, takže nemusíte nič aktualizovať.
SDK pre PHP, Node, Go a Edge majú čísla verzií; zmeny sú uvedené v changelogu príslušného balíka.
Zmeny API a skriptu zverejňujeme v changelogu.

Zdroje

Centrum pomoci

Komplexná dokumentácia s úvodnými návodmi, integračnými tutoriálmi, referenciou konfigurácie a riešením problémov.

Otvoriť Centrum pomoci

Zoznam zmien

Buďte v obraze o najnovších funkciách, vylepšeniach a opravách.

Zobraziť zoznam zmien

Pripravení začať?

Vytvorte si bezplatný účet a získajte svoj kľúč.

Začať