SilentShield를 양식에 안전하게 통합하기

클라이언트 스크립트, 서버 측 검증, 키, 오류 사례 – 전체 통합을 한곳에서.

빠른 시작 테스트 도메인 설정

스크립트와 서버 확인이 함께 작동하는 방식

완전한 통합은 두 부분으로 이루어집니다: 브라우저의 스크립트와 귀하의 서버에서의 확인입니다.

1
스크립트 로드
페이지가 사이트 키와 함께 client.js?k=…를 로드합니다. 스크립트는 양식에서의 행동을 측정합니다.
2
양식 제출
제출 시 스크립트는 측정 결과를 보고하고 양식에 behavior_nonce 필드를 추가합니다.
3
서버의 확인 요청
귀하의 서버가 behavior_nonce를 POST /api/v1/captcha/verify-nonce로 보내며, 키는 X-Api-Key 헤더에 담습니다.
4
결정은 귀하가 합니다
응답에는 ok, verdict, confidence, reason_codes가 포함됩니다. ok가 true이면 제출을 수락하고, 그렇지 않으면 거부하십시오.

3단계가 없으면 통합은 절반만 보호합니다: 스크립트만으로는 귀하의 서버로 직접 보내진 요청을 막을 수 없습니다.

사이트 키와 서버 키

사이트 키(공개)

client.js?k=…

페이지 소스에 포함되어 누구나 볼 수 있습니다. 스크립트를 귀하의 도메인에 연결하며, www. 또는 staging. 같은 하위 도메인도 포함됩니다.

서버 키(비밀, 선택 사항)

X-Api-Key

선택 사항입니다. 서버가 보내는 호출에 페이지 소스에 없는 값을 사용하려면 대시보드에서 해당 키의 “서버 키” 탭에서 생성하십시오. 서버에만 두고 브라우저에는 절대 두지 마십시오. 언제든지 다시 생성할 수 있습니다.

서버 확인은 사이트 키만으로 작동하므로 아무것도 변경하지 않으셔도 됩니다. 두 키 모두 허용됩니다. 서버 키를 사용하면 서버 코드에 페이지 소스에서 누구나 읽을 수 있는 값이 포함되지 않습니다.

퀵스타트

설치 및 삽입

스크립트를 추가하고 토큰 받기

서버에서 확인

백엔드에서 토큰 유효성 검사

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

AI 에이전트 (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:

noncestring확인할 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 성공적으로 확인됨

400잘못된 요청 (Nonce 누락 또는 오류)

401잘못된 API 키

403사람으로 확인되지 않음(ok: false) – 제출을 거부하십시오

429요청 속도 제한 초과

500내부 서버 오류

시간 제한, 장애 및 할당량

서버 확인에 시간 제한을 설정하십시오. 당사 코드 예제는 5초를 사용합니다.
확인이 제때 응답하지 않으면 예제는 이를 “확인되지 않음”으로 처리하고 거부합니다. 이 경우 수락하는 편을 원하시면 오류를 직접 처리하십시오 — 결정은 귀하의 몫입니다.
스크립트가 설정과 구성 요소를 불러오는 동안 첫 번째 호스트가 응답하지 않으면 두 번째 호스트로 전환합니다(api.silentshield.io 및 api-eu.silentshield.io). 엄격한 EU 바인딩이 설정된 키는 EU 호스트에 머뭅니다.
서버 확인에는 자동 대체 호스트가 없습니다.
월간 할당량을 초과해도 API는 계속 확인하고 평소와 같이 응답합니다. 429는 키의 분당 요청 한도를 초과했음을 의미합니다.

로컬 및 테스트 도메인에서 테스트

귀하의 키는 localhost에서 작동하지 않습니다: 키는 귀하의 도메인에 연결되어 있으며, 그곳에서는 스크립트가 거부됩니다.
귀하 도메인의 하위 도메인(예: staging.your-domain.kr)에서 테스트하십시오. 기본 도메인의 키로 작동하며 추가 도메인 슬롯을 사용하지 않습니다.
테스트와 운영 환경을 따로 평가하려면 같은 도메인에 두 번째 키를 생성하십시오. 이 키도 추가 도메인 슬롯을 사용하지 않습니다.
테스트로 양식을 제출하고 서버에서 verify-nonce 응답을 확인하십시오: 직접 입력한 경우 ok: true가 반환되어야 하며, 그렇지 않으면 reason_codes가 그 이유를 보여 줍니다.

테스트 도메인 설정

버전 및 변경 사항

API는 경로에 버전을 포함합니다: /api/v1. 동일한 경로는 /api에서도 사용할 수 있습니다.
스크립트에는 버전 번호가 없습니다: client.js는 항상 최신 릴리스를 제공하므로 업데이트할 필요가 없습니다.
PHP, Node, Go, Edge용 SDK에는 버전 번호가 있으며, 변경 사항은 각 패키지의 변경 로그에 기재됩니다.
API와 스크립트의 변경 사항은 변경 로그에 게시합니다.

리소스

도움말 센터

시작 가이드, 연동 튜토리얼, 설정 레퍼런스, 문제 해결을 담은 종합 문서입니다.

도움말 센터 열기

변경 이력

최신 기능, 개선 사항 및 수정 사항을 확인하세요.

변경 이력 보기

시작할 준비가 되셨나요?

무료 계정을 만들고 키를 받으세요.

시작하기