Bezpieczna integracja SilentShield z Państwa formularzem

Skrypt klienta, weryfikacja po stronie serwera, klucze i przypadki błędów – pełna integracja w jednym miejscu.

Jak współpracują skrypt i weryfikacja na serwerze

Pełna integracja składa się z dwóch części: skryptu w przeglądarce i weryfikacji na Państwa serwerze.

1
Skrypt się ładuje
Państwa strona ładuje client.js?k=… z kluczem witryny. Skrypt mierzy zachowanie w formularzu.
2
Formularz zostaje wysłany
Przy wysyłaniu skrypt przekazuje pomiar i dodaje do formularza pole behavior_nonce.
3
Państwa serwer pyta
Państwa serwer wysyła behavior_nonce do POST /api/v1/captcha/verify-nonce, z kluczem w nagłówku X-Api-Key.
4
To Państwo decydują
Odpowiedź zawiera ok, verdict, confidence i reason_codes. Jeśli ok ma wartość true, proszę przyjąć zgłoszenie, w przeciwnym razie je odrzucić.

Bez kroku 3 integracja chroni tylko połowicznie: sam skrypt nie zatrzyma żądania wysłanego bezpośrednio na Państwa serwer.

Klucz witryny i klucz serwerowy

Klucz witryny (publiczny)

client.js?k=…

Znajduje się w kodzie źródłowym strony i jest widoczny dla każdego. Wiąże skrypt z Państwa domeną; subdomeny takie jak www. czy staging. są objęte.

Klucz serwerowy (tajny, opcjonalny)

X-Api-Key

Opcjonalnie. Jeśli chcą Państwo, aby wywołania, które kieruje Państwa serwer, zawierały wartość niewidoczną w kodzie źródłowym strony, proszę utworzyć go w panelu przy kluczu, na karcie „Klucz serwerowy”. Powinien znajdować się wyłącznie na Państwa serwerze, nigdy w przeglądarce, i można go w każdej chwili wygenerować ponownie.

Weryfikacja na serwerze działa już z samym kluczem witryny, więc nie muszą Państwo niczego zmieniać. Akceptowane są oba klucze. Z kluczem serwerowym kod Państwa serwera nie zawiera żadnej wartości, którą każdy może odczytać w kodzie źródłowym strony.

Szybki start

Instalacja i osadzanie

Dodanie skryptu i uzyskanie tokena

Weryfikacja na serwerze

Weryfikacja tokena na backendzie

Szybki test z cURL

Weryfikacja nonce z wiersza poleceń

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

Bezpieczeństwo i prywatność

Bez plików cookie – działanie całkowicie bez plików cookie
Bez profili, bez plików cookie – do stosowania zgodnie z RODO
Hosting w EU – weryfikacja i przechowywanie na naszych serwerach w Niemczech
Zgodne z WCAG – dostępne dla wszystkich użytkowników
Kompatybilne z CSP – użycie z 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 i Biblioteki

Pakiet działa na Państwa serwerze (Node.js od 18). W przeglądarce żaden pakiet nie jest potrzebny — tam wystarczy fragment client.js z szybkiego 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

Agenci SI (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

Referencja API

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

POST/api/v1/captcha/verify-nonce

Weryfikuje SilentShield Nonce

Request Headers:

X-Api-KeyYOUR_API_KEY

Content-Typeapplication/json

Request Body:

noncestringNonce do weryfikacji

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 pomyślnie zweryfikowany

400Nieprawidłowe żądanie (brakujące lub nieprawidłowe Nonce)

401Nieprawidłowy klucz API

403Nie potwierdzono jako człowieka (ok: false) – należy odrzucić zgłoszenie

429Przekroczony limit zapytań

500Wewnętrzny błąd serwera

Limity czasu, awarie i limit użycia

Proszę ustawić limit czasu dla weryfikacji na serwerze. Nasze przykłady kodu używają 5 sekund.
Jeśli weryfikacja nie odpowie na czas, przykłady traktują to jako „niepotwierdzone” i odrzucają. Jeśli w takim przypadku wolą Państwo przyjąć zgłoszenie, proszę samodzielnie obsłużyć błąd — decyzja należy do Państwa.
Jeśli pierwszy host nie odpowiada, gdy skrypt ładuje swoje ustawienia i komponenty, przełącza się na drugi (api.silentshield.io i api-eu.silentshield.io). Klucze ze ścisłym powiązaniem z UE pozostają na hoście w UE.
Dla weryfikacji na serwerze nie ma automatycznego hosta zapasowego.
Po przekroczeniu miesięcznego limitu API nadal weryfikuje i odpowiada jak zwykle. Kod 429 oznacza, że przekroczono limit żądań na minutę dla Państwa klucza.

Testowanie lokalnie i w domenie testowej

Państwa klucz nie działa na localhost: jest powiązany z Państwa domeną, a skrypt jest tam odrzucany.
Proszę testować w subdomenie swojej domeny, na przykład staging.moja-domena.pl. Działa ona z kluczem domeny głównej i nie zajmuje dodatkowego miejsca na domenę.
Jeśli chcą Państwo oceniać test i środowisko produkcyjne osobno, proszę utworzyć drugi klucz dla tej samej domeny. On również nie zajmuje dodatkowego miejsca na domenę.
Proszę wysłać testowo formularz i sprawdzić na serwerze odpowiedź verify-nonce: przy danych wpisanych ręcznie powinno wrócić ok: true; w przeciwnym razie reason_codes pokazują, dlaczego nie.

Skonfiguruj domenę testową

Wersje i zmiany

API zawiera swoją wersję w ścieżce: /api/v1. Te same trasy są dostępne pod /api.
Skrypt nie ma numeru wersji: client.js zawsze dostarcza bieżące wydanie, więc nie muszą Państwo niczego aktualizować.
SDK dla PHP, Node, Go i Edge mają numery wersji; zmiany są opisane w dzienniku zmian danego pakietu.
Zmiany w API i skrypcie publikujemy w dzienniku zmian.

Zasoby

Centrum Pomocy

Kompleksowa dokumentacja z przewodnikami na start, samouczkami integracji, opisem konfiguracji i rozwiązywaniem problemów.

Otwórz Centrum Pomocy

Dziennik zmian

Najnowsze funkcje, ulepszenia i poprawki w jednym miejscu.

Zobacz dziennik zmian

Gotowy do rozpoczęcia?

Wystarczy założyć darmowe konto i otrzymać klucz.

Rozpocznij teraz