Integroi SilentShield turvallisesti lomakkeeseesi

Asiakasskripti, palvelinpuolen tarkistus, avaimet ja virhetilanteet – koko integrointi yhdessä paikassa.

Näin skripti ja palvelintarkistus toimivat yhdessä

Täydellisessä integraatiossa on kaksi puolta: skripti selaimessa ja tarkistus palvelimellasi.

1
Skripti latautuu
Sivusi lataa client.js?k=… -tiedoston sivustoavaimellasi. Skripti mittaa käyttäytymistä lomakkeessa.
2
Lomake lähetetään
Lähetettäessä skripti raportoi mittauksen ja lisää lomakkeeseesi kentän behavior_nonce.
3
Palvelimesi kysyy
Palvelimesi lähettää behavior_nonce-arvon osoitteeseen POST /api/v1/captcha/verify-nonce, avaimesi otsakkeessa X-Api-Key.
4
Sinä päätät
Vastaus sisältää kentät ok, verdict, confidence ja reason_codes. Hyväksy lähetys, jos ok on true, muuten hylkää se.

Ilman vaihetta 3 integraatio suojaa vain puoliksi: skripti yksin ei pysäytä pyyntöä, joka lähetetään suoraan palvelimellesi.

Sivustoavain ja palvelinavain

Sivustoavain (julkinen)

client.js?k=…

Se näkyy sivusi lähdekoodissa ja on siten kaikkien nähtävissä. Se sitoo skriptin verkkotunnukseesi; aliverkkotunnukset kuten www. tai staging. sisältyvät siihen.

Palvelinavain (salainen, valinnainen)

X-Api-Key

Valinnainen. Jos haluat, että palvelimesi tekemät kutsut sisältävät arvon, joka ei ole sivusi lähdekoodissa, luo se hallintapaneelissa avaimen kohdalla välilehdellä ”Palvelinavain”. Se kuuluu vain palvelimellesi, ei koskaan selaimeen, ja sen voi luoda uudelleen milloin tahansa.

Palvelintarkistus toimii pelkällä sivustoavaimella, joten sinun ei tarvitse muuttaa mitään. Molemmat avaimet hyväksytään. Palvelinavainta käytettäessä palvelinkoodisi ei sisällä arvoa, jonka kuka tahansa voi lukea sivusi lähdekoodista.

Pika-aloitus

Asenna ja upota

Lisää skripti ja hanki tunniste (token)

Varmenna palvelimella

Validoi tunniste taustaohjelmassasi

Nopea testaus cURL:llä

Varmenna tunnus (nonce) komentoriviltä

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

Turvallisuus ja yksityisyys

Ei evästeitä – täysin evästeetön toiminta
Ei profiileja, ei evästeitä – käytettävissä GDPR:n mukaisesti
EU-isännöinti – tarkistus ja tallennus palvelimillamme Saksassa
WCAG-yhteensopiva – kaikkien käyttäjien saavutettavissa
CSP-yhteensopiva – käytä Content Security Policyn kanssa:

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:t ja Kirjastot

Paketti toimii palvelimellasi (Node.js 18 tai uudempi). Selaimessa et tarvitse pakettia lainkaan — siellä riittää pikaoppaan client.js-katkelma.

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

Tekoälyagentit (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-viite

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

POST/api/v1/captcha/verify-nonce

Varmenna SilentShield Nonce

Request Headers:

X-Api-KeyYOUR_API_KEY

Content-Typeapplication/json

Request Body:

noncestringVarmennettava tunnus (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:

200Tunnus (nonce) varmennettu onnistuneesti

400Virheellinen pyyntö (puuttuva tai väärä tunnus)

401Virheellinen API-avain

403Ei vahvistettu ihmiseksi (ok: false) – hylkää lähetys

429Nopeusrajoitus ylitetty

500Sisäinen palvelinvirhe

Aikakatkaisut, katkokset ja kiintiö

Aseta palvelintarkistukselle aikakatkaisu. Koodiesimerkkimme käyttävät 5 sekuntia.
Jos tarkistus ei vastaa ajoissa, esimerkit käsittelevät sen ”vahvistamattomana” ja hylkäävät. Jos haluat mieluummin hyväksyä tässä tapauksessa, käsittele virhe itse — päätös on sinun.
Jos ensimmäinen palvelin ei vastaa, kun skripti lataa asetuksiaan ja komponenttejaan, se siirtyy toiseen (api.silentshield.io ja api-eu.silentshield.io). Tiukasti EU:hun sidotut avaimet pysyvät EU-palvelimella.
Palvelintarkistukselle ei ole automaattista varapalvelinta.
Kuukausikiintiön ylittyessä API jatkaa tarkistamista ja vastaa tavalliseen tapaan. 429 tarkoittaa, että avaimesi minuuttikohtainen pyyntöraja on ylittynyt.

Testaus paikallisesti ja testiverkkotunnuksessa

Avaimesi ei toimi osoitteessa localhost: se on sidottu verkkotunnukseesi, ja skripti hylätään siellä.
Testaa verkkotunnuksesi aliverkkotunnuksessa, esimerkiksi staging.oma-verkkotunnus.fi. Se toimii päätunnuksen avaimella eikä vie ylimääräistä verkkotunnuspaikkaa.
Jos haluat arvioida testin ja tuotannon erikseen, luo samalle verkkotunnukselle toinen avain. Sekään ei vie ylimääräistä verkkotunnuspaikkaa.
Lähetä testiksi lomake ja tarkista palvelimellasi verify-nonce-vastaus: käsin kirjoitetun syötteen pitäisi palauttaa ok: true; muuten reason_codes kertovat, miksi ei.

Määritä testiverkkotunnus

Versiot ja muutokset

API:n versio on polussa: /api/v1. Samat reitit ovat saatavilla myös polussa /api.
Skriptillä ei ole versionumeroa: client.js toimittaa aina nykyisen julkaisun, joten sinun ei tarvitse päivittää mitään.
PHP:n, Noden, Go:n ja Edgen SDK:illa on versionumerot; muutokset on lueteltu kunkin paketin muutoslokissa.
Julkaisemme API:n ja skriptin muutokset muutoslokissa.

Resurssit

Ohjekeskus

Kattava dokumentaatio, jossa on aloitusoppaat, integraatio-ohjeet, määritysten viiteaineisto ja vianmääritys.

Avaa ohjekeskus

Muutosloki

Pysy ajan tasalla uusimmista ominaisuuksista, parannuksista ja korjauksista.

Näytä muutosloki

Oletko valmis aloittamaan?

Luo ilmainen tili ja saat avaimesi.

Aloita nyt