Sigurno integrirajte SilentShield u svoj obrazac

Klijentska skripta, provjera na poslužitelju, ključevi i slučajevi pogrešaka – cijela integracija na jednom mjestu.

Brzi početak Postavite testnu domenu

Kako skripta i provjera na poslužitelju rade zajedno

Potpuna integracija ima dvije polovice: skriptu u pregledniku i provjeru na vašem poslužitelju.

1
Skripta se učitava
Vaša stranica učitava client.js?k=… s vašim ključem web-mjesta. Skripta mjeri ponašanje u obrascu.
2
Obrazac se šalje
Pri slanju skripta javlja mjerenje i dodaje polje behavior_nonce u vaš obrazac.
3
Vaš poslužitelj provjerava
Vaš poslužitelj šalje behavior_nonce na POST /api/v1/captcha/verify-nonce, s vašim ključem u zaglavlju X-Api-Key.
4
Vi odlučujete
Odgovor sadrži ok, verdict, confidence i reason_codes. Prihvatite slanje ako je ok true, inače ga odbijte.

Bez koraka 3 integracija štiti samo napola: sama skripta ne zaustavlja zahtjev poslan izravno na vaš poslužitelj.

Ključ web-mjesta i poslužiteljski ključ

Ključ web-mjesta (javni)

client.js?k=…

Nalazi se u izvornom kodu vaše stranice i vidljiv je svima. Veže skriptu uz vašu domenu; poddomene poput www. ili staging. su uključene.

Poslužiteljski ključ (tajni, neobavezan)

X-Api-Key

Neobavezno. Ako želite da pozivi vašeg poslužitelja nose vrijednost kojoj nema traga u izvornom kodu vaše stranice, izradite je na nadzornoj ploči uz ključ, na kartici „Poslužiteljski ključ“. Pripada samo vašem poslužitelju, nikada pregledniku, i može se u bilo kojem trenutku ponovno generirati.

Provjera na poslužitelju radi samo s ključem web-mjesta, pa ne morate ništa mijenjati. Prihvaćaju se oba ključa. S poslužiteljskim ključem vaš kôd na poslužitelju ne sadrži vrijednost koju svatko može pročitati u izvornom kodu vaše stranice.

Brzi početak

Instalacija i ugradnja

Dodajte skriptu i dohvatite token

Provjera na poslužitelju

Provjerite valjanost tokena na svom pozadinskom sustavu (backendu)

Brzi test s cURL-om

Provjerite nonce iz naredbenog retka

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

Sigurnost i privatnost

Bez kolačića – potpuno funkcioniranje bez kolačića
Bez profila, bez kolačića – primjenjivo u skladu s GDPR-om
Smještaj podataka u EU – provjera i pohrana na našim poslužiteljima u Njemačkoj
WCAG usklađenost – dostupno svim korisnicima
CSP usklađenost – korištenje 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-ovi i Biblioteke

Paket radi na vašem poslužitelju (Node.js od 18). U pregledniku vam paket uopće ne treba — ondje je dovoljan isječak client.js iz brzog poč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

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

API referenca

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

POST/api/v1/captcha/verify-nonce

Provjeri SilentShield Nonce

Request Headers:

X-Api-KeyYOUR_API_KEY

Content-Typeapplication/json

Request Body:

noncestringNonce za provjeru

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 uspješno provjeren

400Nevažeći zahtjev (nedostaje ili je netočan Nonce)

401Nevažeći API ključ

403Nije potvrđeno kao čovjek (ok: false) – odbijte slanje

429Prekoračena granica stope

500Interna pogreška poslužitelja

Vremenska ograničenja, ispadi i kvota

Postavite vremensko ograničenje za provjeru na poslužitelju. Naši primjeri koda koriste 5 sekundi.
Ako provjera ne odgovori na vrijeme, primjeri to tretiraju kao „nepotvrđeno“ i odbijaju. Ako u tom slučaju radije prihvaćate, sami uhvatite pogrešku — odluka je vaša.
Ako prvi host ne odgovori dok skripta učitava svoje postavke i komponente, prelazi na drugi (api.silentshield.io i api-eu.silentshield.io). Ključevi sa strogim vezanjem za EU ostaju na hostu u EU-u.
Za provjeru na poslužitelju ne postoji automatski pričuvni host.
Iznad vaše mjesečne kvote API nastavlja provjeravati i odgovara kao i obično. Kod 429 znači da je prekoračeno ograničenje zahtjeva po minuti za vaš ključ.

Testiranje lokalno i na testnoj domeni

Vaš ključ ne radi na localhost: vezan je uz vašu domenu i skripta se tamo odbija.
Testirajte na poddomeni svoje domene, na primjer staging.vasa-domena.hr. Radi s ključem glavne domene i ne zauzima dodatno mjesto za domenu.
Ako želite zasebno vrednovati test i produkciju, izradite drugi ključ za istu domenu. Ni on ne zauzima dodatno mjesto za domenu.
Pošaljite probni obrazac i na svom poslužitelju provjerite odgovor verify-nonce: za ručno upisani unos trebao bi se vratiti ok: true; inače reason_codes pokazuju zašto nije.

Postavite testnu domenu

Verzije i promjene

API nosi svoju verziju u putanji: /api/v1. Iste rute dostupne su i pod /api.
Skripta nema broj verzije: client.js uvijek isporučuje aktualno izdanje, pa ne morate ništa ažurirati.
SDK-ovi za PHP, Node, Go i Edge imaju brojeve verzija; promjene su navedene u dnevniku promjena pojedinog paketa.
Promjene API-ja i skripte objavljujemo u dnevniku promjena.

Resursi

Centar za pomoć

Opsežna dokumentacija s vodičima za početak, uputama za integraciju, referencom konfiguracije i rješavanjem problema.

Otvorite centar za pomoć

Dnevnik promjena

Budite u tijeku s najnovijim značajkama, poboljšanjima i ispravcima.

Pogledajte dnevnik promjena

Spremni za početak?

Izradite besplatni račun i preuzmite svoj ključ.

Započnite sada