SilentShield

A SilentShield biztonságos integrálása az űrlapjába

Kliensszkript, szerveroldali ellenőrzés, kulcsok és hibaesetek – a teljes integráció egy helyen.

Gyors kezdésTesztdomain beállítása

Így működik együtt a szkript és a szerveroldali ellenőrzés

Egy teljes integrációnak két fele van: a szkript a böngészőben és egy ellenőrzés az Ön szerverén.

  1. 1

    A szkript betöltődik

    Az Ön oldala betölti a client.js?k=… fájlt az Ön webhelykulcsával. A szkript méri az űrlapon tanúsított viselkedést.

  2. 2

    Az űrlap elküldése

    Elküldéskor a szkript jelenti a mérést, és hozzáadja a behavior_nonce mezőt az Ön űrlapjához.

  3. 3

    Az Ön szervere rákérdez

    Az Ön szervere elküldi a behavior_nonce értéket a POST /api/v1/captcha/verify-nonce végpontra, a kulccsal az X-Api-Key fejlécben.

  4. 4

    Ön dönt

    A válasz tartalmazza az ok, verdict, confidence és reason_codes mezőket. Ha az ok értéke true, fogadja el a beküldést, ellenkező esetben utasítsa el.

A 3. lépés nélkül az integráció csak félig véd: a szkript önmagában nem állítja meg a közvetlenül az Ön szerverére küldött kérést.

Webhelykulcs és kiszolgálókulcs

Webhelykulcs (nyilvános)

client.js?k=…

Az Ön oldalának forráskódjában szerepel, így bárki láthatja. A szkriptet az Ön domainjéhez köti; az olyan aldomainek, mint a www. vagy a staging., ide tartoznak.

Kiszolgálókulcs (titkos, opcionális)

X-Api-Key

Nem kötelező. Ha azt szeretné, hogy a szervere hívásai olyan értéket hordozzanak, amely nincs az oldala forráskódjában, hozza létre az irányítópulton a kulcsnál, a „Kiszolgálókulcs” lapon. Csak az Ön szerverére tartozik, soha nem a böngészőbe, és bármikor újragenerálható.

A szerveroldali ellenőrzés a webhelykulccsal önmagában is működik, ezért semmit nem kell módosítania. Mindkét kulcsot elfogadja. A kiszolgálókulccsal a szerverkódja nem tartalmaz olyan értéket, amelyet bárki elolvashat az oldala forráskódjában.

Gyorsindítás

1

Telepítés és beágyazás

Adja hozzá a szkriptet és szerezzen tokent

2

Ellenőrzés a szerveren

Érvényesítse a tokent a backendjén

Gyors teszt cURL-lel

Nonce ellenőrzése parancssorból

# Nonce ellenőrzése
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>

Biztonság és adatvédelem

  • Nincsenek cookie-k – teljes mértékben cookie-mentes működés
  • Nincsenek profilok, nincsenek sütik – GDPR-kompatibilisen használható
  • EU-s tárhely – ellenőrzés és tárolás a németországi szervereinken
  • WCAG kompatibilis – minden felhasználó számára elérhető
  • CSP kompatibilis – használja a Content Security Policy-vel:
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-k és Könyvtárak

A csomag a szerveren fut (Node.js 18-tól). A böngészőben egyáltalán nincs szükség csomagra — ott elég a gyors kezdéshez tartozó client.js kódrészlet.

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

MI-ügynökök (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 referencia

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

POST/api/v1/captcha/verify-nonce

SilentShield Nonce ellenőrzése

Request Headers:

X-Api-KeyYOUR_API_KEY
Content-Typeapplication/json

Request Body:

noncestringAz ellenőrizendő Nonce

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 sikeresen ellenőrizve
400Érvénytelen kérés (hiányzó vagy hibás Nonce)
401Érvénytelen API-kulcs
403Nincs emberként megerősítve (ok: false) – utasítsa el a beküldést
429Sebességkorlát túllépve
500Belső szerverhiba

Időkorlátok, kiesések és kvóta

  • Állítson be időkorlátot a szerveroldali ellenőrzéshez. Kódpéldáink 5 másodpercet használnak.
  • Ha az ellenőrzés nem válaszol időben, a példák ezt „nem megerősített” eredményként kezelik, és elutasítanak. Ha ilyenkor inkább elfogadna, kezelje saját maga a hibát — a döntés az Öné.
  • Ha az első host nem válaszol, miközben a szkript a beállításait és összetevőit tölti be, átvált a másodikra (api.silentshield.io és api-eu.silentshield.io). A szigorú EU-kötésű kulcsok az EU-s hoston maradnak.
  • A szerveroldali ellenőrzéshez nincs automatikus tartalékhost.
  • A havi kvóta felett az API továbbra is ellenőriz, és a szokásos módon válaszol. A 429 azt jelenti, hogy túllépte a kulcsára vonatkozó percenkénti kéréskorlátot.

Tesztelés helyben és tesztdomainen

  • A kulcsa nem működik localhost alatt: az Ön domainjéhez van kötve, és a szkriptet ott elutasítjuk.
  • Teszteljen a domainje egyik aldomainjén, például: staging.sajat-domain.hu. Ez a fődomain kulcsával fut, és nem foglal további domainhelyet.
  • Ha a tesztet és az éles üzemet külön szeretné kiértékelni, hozzon létre egy második kulcsot ugyanahhoz a domainhez. Ez sem foglal további domainhelyet.
  • Küldjön el próbaként egy űrlapot, és ellenőrizze a szerverén a verify-nonce válaszát: kézzel beírt adatoknál ok: true értéknek kell visszajönnie; ellenkező esetben a reason_codes mutatja meg, miért nem.
Tesztdomain beállítása

Verziók és változások

  • Az API a verzióját az elérési útban hordozza: /api/v1. Ugyanezek az útvonalak a /api alatt is elérhetők.
  • A szkriptnek nincs verziószáma: a client.js mindig az aktuális kiadást szolgálja ki, így Önnek semmit sem kell frissítenie.
  • A PHP, Node, Go és Edge SDK-k verziószámmal rendelkeznek; a változások az adott csomag változásnaplójában szerepelnek.
  • Az API és a szkript változásait a változásnaplóban tesszük közzé.

Források

Súgó

Átfogó dokumentáció első lépésekkel, integrációs útmutatókkal, konfigurációs referenciákkal és hibaelhárítással.

Súgó megnyitása

Változásnapló

Legyen naprakész a legújabb funkciókkal, fejlesztésekkel és javításokkal.

Változásnapló megtekintése

Készen áll a kezdésre?

Hozzon létre egy ingyenes fiókot, és kapja meg a kulcsát.

Kezdje el most