Integri SilentShield in modo sicuro nel suo modulo

Script client, verifica lato server, chiavi e casi di errore – l'integrazione completa in un unico posto.

Avvio rapido Configura un dominio di prova

Come lavorano insieme lo script e la verifica lato server

Un'integrazione completa ha due metà: lo script nel browser e una verifica sul Suo server.

1
Lo script si carica
La Sua pagina carica client.js?k=… con la Sua chiave del sito. Lo script misura il comportamento nel modulo.
2
Il modulo viene inviato
All'invio, lo script comunica la misurazione e aggiunge il campo behavior_nonce al Suo modulo.
3
Il Suo server verifica
Il Suo server invia behavior_nonce a POST /api/v1/captcha/verify-nonce, con la Sua chiave nell'header X-Api-Key.
4
Lei decide
La risposta contiene ok, verdict, confidence e reason_codes. Accetti l'invio se ok è true, altrimenti lo rifiuti.

Senza il passaggio 3 l'integrazione protegge solo a metà: lo script da solo non blocca una richiesta inviata direttamente al Suo server.

Chiave del sito e chiave server

Chiave del sito (pubblica)

client.js?k=…

Si trova nel codice sorgente della Sua pagina ed è quindi visibile a chiunque. Lega lo script al Suo dominio; i sottodomini come www. o staging. sono inclusi.

Chiave server (segreta, facoltativa)

X-Api-Key

Facoltativo. Se desidera che le chiamate del Suo server portino un valore assente dal codice sorgente della Sua pagina, lo crei nella dashboard, presso la chiave, nella scheda «Chiave server». Va conservato solo sul Suo server, mai nel browser, e può essere rigenerato in qualsiasi momento.

La verifica lato server funziona con la sola chiave del sito, quindi non deve modificare nulla. Entrambe le chiavi sono accettate. Con la chiave server, il codice del Suo server non contiene alcun valore che chiunque possa leggere nel codice sorgente della Sua pagina.

Avvio rapido

Installazione e integrazione

Aggiunga lo script e ottenga un token

Verifica sul server

Convalidi il token sul Suo backend

Test rapido con cURL

Verifica il nonce dalla riga di comando

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

Sicurezza e privacy

Nessun cookie – funzionamento completamente senza cookie
Nessun profilo, nessun cookie – utilizzabile in conformità al GDPR
Hosting nell'EU – verifica e archiviazione sui nostri server in Germania
Conforme a WCAG – accessibile a tutti gli utenti
Compatibile con CSP – utilizzabile con 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 e Librerie

Il pacchetto gira sul Suo server (Node.js 18 o successivo). Nel browser non serve alcun pacchetto: lì basta lo snippet client.js della guida rapida.

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 IA (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

Riferimento API

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

POST/api/v1/captcha/verify-nonce

Verifica SilentShield Nonce

Request Headers:

X-Api-KeyYOUR_API_KEY

Content-Typeapplication/json

Request Body:

noncestringIl Nonce da verificare

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 verificato con successo

400Richiesta non valida (Nonce mancante o errato)

401Chiave API non valida

403Non confermato come umano (ok: false) – rifiuti l’invio

429Limite di velocità superato

500Errore interno del server

Timeout, interruzioni e quota

Imposti un timeout per la verifica lato server. I nostri esempi di codice usano 5 secondi.
Se la verifica non risponde in tempo, gli esempi la considerano «non confermata» e rifiutano. Se in questo caso preferisce accettare, gestisca Lei l'errore — la decisione spetta a Lei.
Se il primo host non risponde mentre lo script carica le proprie impostazioni e i propri componenti, passa al secondo (api.silentshield.io e api-eu.silentshield.io). Le chiavi con vincolo UE rigoroso restano sull'host UE.
Per la verifica lato server non esiste un host di riserva automatico.
Oltre la Sua quota mensile, l'API continua a verificare e risponde come di consueto. Un 429 indica che è stato superato il limite di richieste al minuto per la Sua chiave.

Test in locale e su un dominio di prova

La Sua chiave non funziona su localhost: è legata al Suo dominio e lì lo script viene rifiutato.
Esegua i test su un sottodominio del Suo dominio, ad esempio staging.suo-dominio.it. Funziona con la chiave del dominio principale e non occupa un ulteriore posto dominio.
Se desidera valutare separatamente test e produzione, crei una seconda chiave per lo stesso dominio. Anche questa non occupa un ulteriore posto dominio.
Invii un modulo di prova e controlli sul Suo server la risposta di verify-nonce: un inserimento digitato a mano dovrebbe restituire ok: true; altrimenti i reason_codes mostrano il motivo.

Configura un dominio di prova

Versioni e modifiche

L'API riporta la propria versione nel percorso: /api/v1. Le stesse route sono disponibili sotto /api.
Lo script non ha un numero di versione: client.js fornisce sempre la release attuale, quindi non deve aggiornare nulla.
Gli SDK per PHP, Node, Go ed Edge hanno numeri di versione; le modifiche sono riportate nel changelog di ciascun pacchetto.
Pubblichiamo le modifiche all'API e allo script nel changelog.

Risorse

Centro assistenza

Documentazione completa con guide introduttive, tutorial di integrazione, riferimenti di configurazione e risoluzione dei problemi.

Apri il Centro assistenza

Registro modifiche

Resti aggiornato sulle ultime funzionalità, miglioramenti e correzioni.

Vedi il registro modifiche

È pronto per iniziare?

Crei un account gratuito e ottenga la Sua chiave.

Inizi ora