Varno integrirajte SilentShield v svoj obrazec

Odjemalski skript, preverjanje na strežniku, ključi in napake – celotna integracija na enem mestu.

Hitri začetek Nastavite testno domeno

Kako skripta in preverjanje na strežniku delujeta skupaj

Celotna integracija ima dve polovici: skripto v brskalniku in preverjanje na vašem strežniku.

1
Skripta se naloži
Vaša stran naloži client.js?k=… z vašim ključem spletnega mesta. Skripta meri vedenje v obrazcu.
2
Obrazec se pošlje
Ob pošiljanju skripta sporoči meritev in v vaš obrazec doda polje behavior_nonce.
3
Vaš strežnik povpraša
Vaš strežnik pošlje behavior_nonce na POST /api/v1/captcha/verify-nonce, z vašim ključem v glavi X-Api-Key.
4
Odločite vi
Odgovor vsebuje ok, verdict, confidence in reason_codes. Če je ok true, oddajo sprejmite, sicer jo zavrnite.

Brez 3. koraka integracija ščiti le napol: skripta sama ne ustavi zahteve, poslane neposredno na vaš strežnik.

Ključ spletnega mesta in strežniški ključ

Ključ spletnega mesta (javni)

client.js?k=…

Je v izvorni kodi vaše strani in zato viden vsakomur. Skripto veže na vašo domeno; poddomene, kot sta www. ali staging., so vključene.

Strežniški ključ (skrivni, neobvezen)

X-Api-Key

Neobvezno. Če želite, da klici, ki jih pošilja vaš strežnik, vsebujejo vrednost, ki je ni v izvorni kodi vaše strani, ga ustvarite na nadzorni plošči pri ključu, na zavihku »Strežniški ključ«. Sodi le na vaš strežnik, nikoli v brskalnik, in ga lahko kadar koli znova ustvarite.

Preverjanje na strežniku deluje že samo s ključem strani, zato vam ni treba ničesar spreminjati. Sprejmeta se oba ključa. S strežniškim ključem vaša strežniška koda ne vsebuje nobene vrednosti, ki bi jo kdor koli lahko prebral v izvorni kodi vaše strani.

Hitri začetek

Namestitev in vdelava

Dodajte skripto in pridobite žeton (token)

Preverjanje na strežniku

Preverite veljavnost žetona v svojem zalednem sistemu (backend)

Hiter test s cURL-om

Preveri 'nonce' iz ukazne vrstice

# Preveri 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>

Varnost in zasebnost

Brez piškotkov – popolno delovanje brez piškotkov
Brez profilov, brez piškotkov – uporabno skladno z GDPR
Gostovanje v EU – preverjanje in shranjevanje na naših strežnikih v Nemčiji
Skladno z WCAG – dostopno vsem uporabnikom
Skladno s CSP – uporaba 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-ji in Knjižnice

Paket teče na vašem strežniku (Node.js od 18). V brskalniku paketa sploh ne potrebujete — tam zadošča odsek client.js iz hitrega začetka.

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

Agenti UI (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

Referenca API

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

POST/api/v1/captcha/verify-nonce

Preveri SilentShield Nonce

Request Headers:

X-Api-KeyYOUR_API_KEY

Content-Typeapplication/json

Request Body:

noncestringNonce za preverjanje

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 je bil uspešno preverjen

400Neveljavna zahteva (manjkajoč ali napačen Nonce)

401Neveljaven API ključ

403Ni potrjeno kot človek (ok: false) – zavrnite pošiljanje

429Presežena omejitev hitrosti

500Notranja strežniška napaka

Časovne omejitve, izpadi in kvota

Za preverjanje na strežniku nastavite časovno omejitev. Naši primeri kode uporabljajo 5 sekund.
Če preverjanje ne odgovori pravočasno, ga primeri obravnavajo kot »nepotrjeno« in zavrnejo. Če v tem primeru raje sprejmete, napako prestrezite sami — odločitev je vaša.
Če prvi gostitelj ne odgovori, medtem ko skripta nalaga svoje nastavitve in komponente, preklopi na drugega (api.silentshield.io in api-eu.silentshield.io). Ključi s strogo vezavo na EU ostanejo na gostitelju v EU.
Za preverjanje na strežniku ni samodejnega nadomestnega gostitelja.
Nad mesečno kvoto API še naprej preverja in odgovarja kot običajno. Koda 429 pomeni, da je bila presežena omejitev zahtev na minuto za vaš ključ.

Testiranje lokalno in na testni domeni

Vaš ključ ne deluje na localhost: vezan je na vašo domeno in skripta je tam zavrnjena.
Testirajte na poddomeni svoje domene, na primer staging.vasa-domena.si. Deluje s ključem glavne domene in ne zaseda dodatnega mesta za domeno.
Če želite test in produkcijo vrednotiti ločeno, ustvarite za isto domeno drugi ključ. Tudi ta ne zaseda dodatnega mesta za domeno.
Za preizkus pošljite obrazec in na svojem strežniku preverite odgovor verify-nonce: pri ročno vtipkanem vnosu bi se moral vrniti ok: true; sicer reason_codes pokažejo, zakaj ne.

Nastavite testno domeno

Različice in spremembe

API nosi svojo različico v poti: /api/v1. Iste poti so na voljo tudi pod /api.
Skripta nima številke različice: client.js vedno dostavi trenutno izdajo, zato vam ni treba ničesar posodabljati.
SDK-ji za PHP, Node, Go in Edge imajo številke različic; spremembe so navedene v dnevniku sprememb posameznega paketa.
Spremembe API-ja in skripte objavljamo v dnevniku sprememb.

Viri

Center za pomoč

Celovita dokumentacija z vodniki za začetek, navodili za integracijo, referenco nastavitev in odpravljanjem težav.

Odprite center za pomoč

Dnevnik sprememb

Bodite na tekočem z najnovejšimi funkcijami, izboljšavami in popravki.

Oglejte si dnevnik sprememb

Pripravljeni na začetek?

Ustvarite brezplačen račun in pridobite svoj ključ.

Začnite zdaj