SilentShield

Saugiai integruokite SilentShield į savo formą

Kliento scenarijus, serverio pusės patikrinimas, raktai ir klaidų atvejai – visa integracija vienoje vietoje.

Greita pradžiaNustatyti bandomąjį domeną

Kaip kartu veikia skriptas ir patikra serveryje

Visą integraciją sudaro dvi dalys: skriptas naršyklėje ir patikra jūsų serveryje.

  1. 1

    Skriptas įkeliamas

    Jūsų puslapis įkelia client.js?k=… su jūsų svetainės raktu. Skriptas matuoja elgseną formoje.

  2. 2

    Forma pateikiama

    Pateikiant formą skriptas praneša matavimo rezultatą ir į jūsų formą įdeda lauką behavior_nonce.

  3. 3

    Jūsų serveris klausia

    Jūsų serveris siunčia behavior_nonce į POST /api/v1/captcha/verify-nonce, o jūsų raktas pateikiamas antraštėje X-Api-Key.

  4. 4

    Sprendžiate jūs

    Atsakyme yra ok, verdict, confidence ir reason_codes. Jei ok yra true, priimkite pateikimą, kitu atveju jį atmeskite.

Be 3 žingsnio integracija apsaugo tik iš dalies: vien skriptas nesustabdo užklausos, išsiųstos tiesiai į jūsų serverį.

Svetainės raktas ir serverio raktas

Svetainės raktas (viešas)

client.js?k=…

Jis yra jūsų puslapio šaltinio kode, todėl matomas visiems. Jis susieja skriptą su jūsų domenu; padomeniai, pvz., www. ar staging., įtraukti.

Serverio raktas (slaptas, neprivalomas)

X-Api-Key

Neprivaloma. Jei norite, kad jūsų serverio užklausos turėtų reikšmę, kurios nėra jūsų puslapio šaltinio kode, sukurkite ją valdymo skydelyje prie rakto, skirtuke „Serverio raktas“. Ji turi būti tik jūsų serveryje, niekada naršyklėje, ir ją bet kada galima sugeneruoti iš naujo.

Patikra serveryje veikia tik su svetainės raktu, todėl nieko keisti nereikia. Priimami abu raktai. Naudojant serverio raktą, jūsų serverio kode nėra jokios reikšmės, kurią bet kas galėtų perskaityti jūsų puslapio šaltinio kode.

Greita pradžia

1

Įdiegti ir integruoti

Pridėkite scenarijų ir gaukite žetoną (token)

2

Patikrinti serveryje

Patvirtinkite žetoną savo serverio pusėje (backend)

Greitas testas su cURL

Patikrinkite 'nonce' iš komandinės eilutės

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

Sauga ir privatumas

  • Be slapukų – visiškai veikia be slapukų
  • Jokių profilių, jokių slapukų – galima naudoti laikantis BDAR
  • Talpinimas EU – patikra ir saugojimas mūsų serveriuose Vokietijoje
  • WCAG atitiktis – prieinama visiems vartotojams
  • CSP atitiktis – naudokite su '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 ir Bibliotekos

Paketas veikia jūsų serveryje (Node.js nuo 18). Naršyklėje paketo išvis nereikia — ten pakanka greitosios pradžios client.js fragmento.

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

DI agentai (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 žinynas

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

POST/api/v1/captcha/verify-nonce

Patikrinti SilentShield Nonce

Request Headers:

X-Api-KeyYOUR_API_KEY
Content-Typeapplication/json

Request Body:

noncestringNonce, kurį reikia patikrinti

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 sėkmingai patikrintas
400Neteisinga užklausa (trūksta arba neteisingas Nonce)
401Neteisingas API raktas
403Nepatvirtinta kaip žmogus (ok: false) – atmeskite pateikimą
429Viršytas užklausų limitas
500Vidinė serverio klaida

Laiko limitai, sutrikimai ir kvota

  • Nustatykite patikrai serveryje laiko limitą. Mūsų kodo pavyzdžiuose naudojamos 5 sekundės.
  • Jei patikra neatsako laiku, pavyzdžiai tai laiko „nepatvirtinta“ ir atmeta. Jei tokiu atveju norite verčiau priimti, apdorokite klaidą patys — sprendimas jūsų.
  • Jei pirmasis serveris neatsako, kol skriptas įkelia savo nustatymus ir komponentus, jis persijungia į antrąjį (api.silentshield.io ir api-eu.silentshield.io). Raktai su griežtu ES susiejimu lieka ES serveryje.
  • Patikrai serveryje automatinio atsarginio serverio nėra.
  • Viršijus mėnesio kvotą, API toliau tikrina ir atsako kaip įprasta. Atsakymas 429 reiškia, kad viršytas jūsų rakto užklausų per minutę limitas.

Testavimas vietoje ir bandomajame domene

  • Jūsų raktas neveikia localhost: jis susietas su jūsų domenu, ir ten skriptas atmetamas.
  • Testuokite savo domeno padomenyje, pavyzdžiui, staging.jusu-domenas.lt. Jis veikia su pagrindinio domeno raktu ir neužima papildomos domeno vietos.
  • Jei norite atskirai vertinti testinę ir veikiančią aplinką, sukurkite tam pačiam domenui antrą raktą. Jis taip pat neužima papildomos domeno vietos.
  • Bandymui pateikite formą ir savo serveryje patikrinkite verify-nonce atsakymą: ranka įvestiems duomenims turėtų būti grąžinta ok: true; kitu atveju reason_codes parodo, kodėl ne.
Nustatyti bandomąjį domeną

Versijos ir pakeitimai

  • API versija nurodyta kelyje: /api/v1. Tie patys maršrutai pasiekiami ir per /api.
  • Skriptas neturi versijos numerio: client.js visada pateikia dabartinį leidimą, todėl jums nieko nereikia atnaujinti.
  • PHP, Node, Go ir Edge SDK turi versijų numerius; pakeitimai nurodyti kiekvieno paketo pakeitimų žurnale.
  • API ir skripto pakeitimus skelbiame pakeitimų žurnale.

Ištekliai

Pagalbos centras

Išsami dokumentacija su pradžios vadovais, integracijos pamokomis, konfigūracijos žinynais ir trikčių šalinimu.

Atidaryti pagalbos centrą

Pakeitimų žurnalas

Sekite naujausias funkcijas, patobulinimus ir pataisymus.

Peržiūrėti pakeitimų žurnalą

Pasiruošę pradėti?

Susikurkite nemokamą paskyrą ir gaukite savo raktą.

Pradėti dabar