SilentShieldをフォームに安全に組み込む

クライアントスクリプト、サーバー側検証、キー、エラーケース – 完全な導入手順を一か所に。

クイックスタートテストドメインを設定

スクリプトとサーバー側チェックの連携

完全な統合は2つの部分で構成されます。ブラウザ内のスクリプトと、お客様のサーバーでのチェックです。

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>

セキュリティとプライバシー

Cookieなし – 完全にCookieフリーでの動作
プロファイルなし、Cookieなし – 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秒を使用しています。
チェックが時間内に応答しない場合、コード例では「未確認」として扱い拒否します。その場合に受け付けたい場合は、エラーをご自身で捕捉してください — 判断はお客様に委ねられます。
スクリプトが設定やコンポーネントを読み込む際に最初のホストが応答しない場合、2つ目のホストに切り替わります（api.silentshield.io と api-eu.silentshield.io）。厳格なEU限定設定のキーはEUホストにとどまります。
サーバー側チェックには自動フォールバックホストはありません。
月間利用枠を超えても、APIはチェックを続け、通常どおり応答します。429 は、キーの1分あたりのレート制限を超えたことを意味します。

ローカルおよびテストドメインでのテスト

お客様のキーは localhost では機能しません。キーはお客様のドメインに紐付けられており、そこではスクリプトが拒否されます。
お客様のドメインのサブドメイン（例：staging.your-domain.jp）でテストしてください。メインドメインのキーで動作し、追加のドメイン枠を使用しません。
テスト環境と本番環境を別々に評価したい場合は、同じドメインに2つ目のキーを作成してください。これも追加のドメイン枠を使用しません。
テストとしてフォームを送信し、サーバーで verify-nonce のレスポンスを確認してください。手入力の場合は ok: true が返るはずです。そうでない場合は reason_codes が理由を示します。

テストドメインを設定

バージョンと変更

APIはパスにバージョンを含みます：/api/v1。同じルートは /api でも利用できます。
スクリプトにはバージョン番号がありません。client.js は常に最新のリリースを配信するため、更新は不要です。
PHP、Node、Go、Edge の SDK にはバージョン番号があり、変更点は各パッケージの変更履歴に記載されています。
APIとスクリプトの変更は変更履歴で公開しています。

リソース

ヘルプセンター

はじめにガイド、統合チュートリアル、設定リファレンス、トラブルシューティングを備えた包括的なドキュメントです。

ヘルプセンターを開く

変更履歴

最新の機能、改善、修正を常に把握できます。

変更履歴を見る

始める準備はできましたか？

無料アカウントを作成して、キーを取得してください。

始める