Bezpečně integrujte SilentShield do svého formuláře

Klientský skript, ověření na straně serveru, klíče a chybové stavy – kompletní integrace na jednom místě.

Rychlý start Nastavit testovací doménu

Jak spolupracuje skript a kontrola na serveru

Úplná integrace má dvě poloviny: skript v prohlížeči a kontrolu na vašem serveru.

1
Skript se načte
Vaše stránka načte client.js?k=… s vaším klíčem webu. Skript měří chování ve formuláři.
2
Formulář se odešle
Při odeslání skript nahlásí měření a přidá do vašeho formuláře pole behavior_nonce.
3
Váš server se zeptá
Váš server pošle behavior_nonce na POST /api/v1/captcha/verify-nonce s vaším klíčem v hlavičce X-Api-Key.
4
Rozhodnete vy
Odpověď obsahuje ok, verdict, confidence a reason_codes. Pokud je ok true, odeslání přijměte, jinak ho odmítněte.

Bez kroku 3 chrání integrace jen napůl: samotný skript nezastaví požadavek odeslaný přímo na váš server.

Klíč webu a serverový klíč

Klíč webu (veřejný)

client.js?k=…

Je uveden ve zdrojovém kódu vaší stránky, a je tedy viditelný pro každého. Váže skript k vaší doméně; subdomény jako www. nebo staging. jsou zahrnuty.

Serverový klíč (tajný, volitelný)

X-Api-Key

Volitelné. Pokud chcete, aby volání vašeho serveru nesla hodnotu, která není ve zdrojovém kódu vaší stránky, vytvořte ho v dashboardu u klíče na kartě „Serverový klíč“. Patří pouze na váš server, nikdy do prohlížeče, a lze ho kdykoli vygenerovat znovu.

Kontrola na serveru funguje i samotným klíčem webu, takže nemusíte nic měnit. Přijímají se oba klíče. Se serverovým klíčem neobsahuje kód vašeho serveru žádnou hodnotu, kterou si může kdokoli přečíst ve zdrojovém kódu vaší stránky.

Rychlý start

Instalace a vložení

Přidejte skript a získejte token

Ověření na serveru

Ověřte token na vašem backendu

Rychlý test s cURL

Ověření nonce z příkazového řádku

# Ověřit 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>

Zabezpečení a soukromí

Žádné cookies – provoz zcela bez cookies
Žádné profily, žádné cookies – použitelné v souladu s GDPR
Hosting v EU – kontrola a ukládání na našich serverech v Německu
WCAG kompatibilní – přístupné všem uživatelům
CSP kompatibilní – použití 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 Knihovny

Balíček běží na vašem serveru (Node.js od verze 18). V prohlížeči žádný balíček nepotřebujete — tam stačí úryvek client.js z rychlého startu.

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

Referenční příručka API

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

POST/api/v1/captcha/verify-nonce

Ověřit SilentShield Nonce

Request Headers:

X-Api-KeyYOUR_API_KEY

Content-Typeapplication/json

Request Body:

noncestringNonce k ověření

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 úspěšně ověřen

400Neplatný požadavek (chybějící nebo nesprávný Nonce)

401Neplatný API klíč

403Nepotvrzeno jako člověk (ok: false) – odeslání odmítněte

429Překročen limit rychlosti

500Interní chyba serveru

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

Nastavte pro kontrolu na serveru časový limit. Naše příklady kódu používají 5 sekund.
Pokud kontrola neodpoví včas, příklady to vyhodnotí jako „nepotvrzeno“ a odmítnou. Pokud v takovém případě raději přijímáte, zachyťte chybu sami — rozhodnutí je na vás.
Pokud první host neodpoví, zatímco skript načítá svá nastavení a komponenty, přepne na druhý (api.silentshield.io a api-eu.silentshield.io). Klíče s přísnou vazbou na EU zůstávají na hostu v EU.
Pro kontrolu na serveru neexistuje automatický záložní host.
Po překročení měsíční kvóty API dál kontroluje a odpovídá jako obvykle. Kód 429 znamená, že byl překročen limit požadavků za minutu pro váš klíč.

Testování lokálně a na testovací doméně

Na localhost váš klíč nefunguje: je vázán na vaši doménu a skript je tam odmítnut.
Testujte na subdoméně vaší domény, například staging.vase-domena.cz. Běží s klíčem hlavní domény a nezabírá další místo pro doménu.
Pokud chcete vyhodnocovat test a ostrý provoz odděleně, vytvořte pro stejnou doménu druhý klíč. Ani ten nezabírá další místo pro doménu.
Odešlete zkušebně formulář a na svém serveru zkontrolujte odpověď verify-nonce: u ručně zadaného vstupu by se mělo vrátit ok: true; jinak reason_codes ukazují, proč ne.

Nastavit testovací doménu

Verze a změny

API nese svou verzi v cestě: /api/v1. Stejné trasy jsou dostupné i pod /api.
Skript nemá číslo verze: client.js vždy doručuje aktuální vydání, takže nemusíte nic aktualizovat.
SDK pro PHP, Node, Go a Edge mají čísla verzí; změny jsou uvedeny v changelogu příslušného balíčku.
Změny API a skriptu zveřejňujeme v changelogu.

Zdroje

Centrum nápovědy

Komplexní dokumentace s úvodními návody, integračními tutoriály, referencí konfigurace a řešením problémů.

Otevřít Centrum nápovědy

Seznam změn

Buďte v obraze o nejnovějších funkcích, vylepšeních a opravách.

Zobrazit seznam změn

Jste připraveni začít?

Vytvořte si bezplatný účet a získejte svůj klíč.

Začněte nyní