SilentShield

Интегрирайте SilentShield сигурно във Вашия формуляр

Клиентски скрипт, проверка от страна на сървъра, ключове и случаи на грешки – цялата интеграция на едно място.

Бърз стартНастройте тестов домейн

Как работят заедно скриптът и проверката на сървъра

Пълното интегриране има две половини: скриптът в браузъра и проверка на Вашия сървър.

  1. 1

    Скриптът се зарежда

    Вашата страница зарежда client.js?k=… с Вашия ключ за сайта. Скриптът измерва поведението във формуляра.

  2. 2

    Формулярът се изпраща

    При изпращане скриптът докладва измерването и добавя полето behavior_nonce към Вашия формуляр.

  3. 3

    Вашият сървър проверява

    Вашият сървър изпраща behavior_nonce до POST /api/v1/captcha/verify-nonce, с Вашия ключ в заглавката X-Api-Key.

  4. 4

    Вие решавате

    Отговорът съдържа ok, verdict, confidence и reason_codes. Приемете изпращането, ако ok е true, в противен случай го отхвърлете.

Без стъпка 3 интеграцията защитава само наполовина: скриптът сам по себе си не спира заявка, изпратена директно до Вашия сървър.

Ключ за сайта и сървърен ключ

Ключ за сайта (публичен)

client.js?k=…

Той стои в изходния код на Вашата страница и е видим за всеки. Той свързва скрипта с Вашия домейн; поддомейни като www. или staging. са включени.

Сървърен ключ (таен, по избор)

X-Api-Key

По избор. Ако искате заявките на Вашия сървър да носят стойност, която не стои в изходния код на Вашата страница, създайте го в таблото при ключа, в раздела „Сървърен ключ“. Той трябва да е само на Вашия сървър, никога в браузъра, и може да бъде генериран наново по всяко време.

Проверката на сървъра работи само с ключа за сайта, така че не е нужно да променяте нищо. Приемат се и двата ключа. Със сървърния ключ кодът на Вашия сървър не съдържа стойност, която всеки може да прочете в изходния код на Вашата страница.

Бърз старт

1

Инсталиране и вграждане

Добавете скрипта и получете токен

2

Проверка на сървъра

Валидирайте токена във вашия бекенд

Бърз тест с cURL

Проверете nonce от командния ред

# Проверка на 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>

Сигурност и поверителност

  • Без бисквитки – изцяло безбисквитна работа
  • Без профили, без бисквитки – може да се използва в съответствие с GDPR
  • Хостинг в EU – проверка и съхранение на нашите сървъри в Германия
  • WCAG съвместимо – достъпно за всички потребители
  • CSP съвместимо – използвайте с 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-та и Библиотеки

Пакетът работи на вашия сървър (Node.js от 18 нагоре). В браузъра не ви трябва никакъв пакет — там е достатъчен client.js фрагментът от бързия старт.

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

ИИ агенти (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

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

POST/api/v1/captcha/verify-nonce

Проверете SilentShield Nonce

Request Headers:

X-Api-KeyYOUR_API_KEY
Content-Typeapplication/json

Request Body:

noncestringNonce за проверка

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 успешно проверен
400Невалидна заявка (липсващ или некоректен Nonce)
401Невалиден API ключ
403Не е потвърдено като човек (ok: false) – отхвърлете изпращането
429Превишен лимит на заявките
500Вътрешна сървърна грешка

Времеви ограничения, прекъсвания и квота

  • Задайте времево ограничение за проверката на сървъра. Нашите примери с код използват 5 секунди.
  • Ако проверката не отговори навреме, примерите я третират като „непотвърдена“ и отхвърлят. Ако в този случай предпочитате да приемете, прихванете грешката сами — решението е Ваше.
  • Ако първият хост не отговори, докато скриптът зарежда своите настройки и компоненти, той преминава към втория (api.silentshield.io и api-eu.silentshield.io). Ключовете със строго обвързване с ЕС остават на хоста в ЕС.
  • За проверката на сървъра няма автоматичен резервен хост.
  • След изчерпване на месечната Ви квота API продължава да проверява и отговаря както обикновено. 429 означава, че ограничението на заявките в минута за Вашия ключ е превишено.

Тестване локално и на тестов домейн

  • Вашият ключ не работи на localhost: той е обвързан с Вашия домейн и скриптът там се отхвърля.
  • Тествайте на поддомейн на Вашия домейн, например staging.vashiyat-domeyn.bg. Той работи с ключа на основния домейн и не заема допълнително място за домейн.
  • Ако искате да оценявате тестовата и живата среда поотделно, създайте втори ключ за същия домейн. И той не заема допълнително място за домейн.
  • Изпратете тестово формуляр и проверете отговора от verify-nonce на Вашия сървър: при ръчно въведени данни трябва да се върне ok: true; в противен случай reason_codes показват защо не.
Настройте тестов домейн

Версии и промени

  • API носи версията си в пътя: /api/v1. Същите маршрути са достъпни и под /api.
  • Скриптът няма номер на версия: client.js винаги доставя текущото издание, така че не е нужно да обновявате нищо.
  • SDK за PHP, Node, Go и Edge имат номера на версии; промените са описани в дневника на промените на съответния пакет.
  • Публикуваме промените в API и скрипта в дневника на промените.

Ресурси

Помощен център

Подробна документация с ръководства за начало, указания за интеграция, справочник за конфигурацията и отстраняване на проблеми.

Към помощния център

Дневник на промените

Бъдете в крак с най-новите функции, подобрения и корекции.

Преглед на дневника на промените

Готови ли сте да започнете?

Създайте безплатен акаунт и получете своя ключ.

Започнете сега