クイックスタート

このガイドでは、5分でCaptchaLa CAPTCHAの導入を完了できます。

30 秒で動作を確認

demo-v1.captcha.la — 純粋な HTML + PHP、MIT ライセンス、全ページでソース表示可能。

• popup.html — ポップアップモード
• float.html — フローティング
• bind.html — ボタンにバインド
• inline.html — インライン埋め込み
• server-token.html — サーバー発行トークン（リプレイ防止）

1. アカウント登録

ダッシュボードで無料アカウントを登録

今すぐ登録 →

2. アプリ作成

ダッシュボードでアプリを作成し、App Keyを取得

3. SDK導入

適切なインストール方法を選択

<!-- CDN loader (recommended): auto-fallback CDN, ~6 KB gzip -->
<script src="https://cdn.captcha-cdn.net/captchala-loader.js"></script>

# or via npm
npm install captchala

4. CAPTCHA初期化

ページでCAPTCHAコンポーネントを初期化

<button id="login-btn">Sign in</button>

<script>
loadCaptchala(function () {
  Captchala.init({
    appKey: 'YOUR_APP_KEY',
    product: 'bind',          // popup | float | bind | embed
    action: 'login',
    lang: 'auto',
  })
  .onSuccess(function (res) {
    // res.token starts with pt_ — POST it to your backend
    submitLogin(res.token);
  })
  .onError(function (err) { console.error(err.message); })
  .bindTo('#login-btn');     // popup/bind use bindTo; float/embed use appendTo
});
</script>

5. サーバー側検証

サーバー側でトークンの有効性を検証

POST https://apiv1.captcha.la/v1/validate
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "pass_token": "<from onSuccess>", "client_ip": "<end-user IP>" }

{
  "code": 0,
  "data": {
    "valid": true,
    "action": "login",
    "challenge_id": "ch_xxx",
    "uid": null,
    "client_ip": "1.2.3.4",
    "risk_score": 12
  }
}

WARNING

Always check data.valid === true and data.action matches the scene you expected. Pass tokens are single-use; the same pt_xxx cannot be validated twice.

サーバー発行トークンモード（本番環境推奨）

機密性の高い操作（ログイン、登録、決済）では、バックエンドが先に短寿命の server_token を取得し、ブラウザがそれを使って CAPTCHA を初期化するフローを推奨します。app_key が漏洩した場合の悪用を防げます。

利用シーン

• 推奨：登録、ログイン、パスワードリセット、決済、ポイント交換などスクリプト攻撃の対象になり得るエンドポイント。
• 任意：公開フォームや検索など、利便性を優先する低リスクな操作。

1. バックエンドで server_token を発行

自社サーバーから /v1/server/challenge/issue を呼び出し、X-App-Key と X-App-Secret ヘッダーを付与します。これらのヘッダーをブラウザに露出させないでください。

# Server-side only — never call this from a browser
curl -X POST https://apiv1.captcha.la/v1/server/challenge/issue \
  -H "X-App-Key: YOUR_APP_KEY" \
  -H "X-App-Secret: YOUR_APP_SECRET" \
  -d "action=login&ttl=300&max_uses=1&bind_ip=1.2.3.4"

# → { "code": 0, "data": { "server_token": "sct_...", "expires_in": 300 } }

2. フロントエンドで server_token を使って CaptchaLa を描画

CaptchaLa コンポーネントにトークンを渡します。SDK が 検証の初期化 の呼び出し時に自動的に送信します。

// Browser fetches the token from YOUR backend, not from CaptchaLa directly
const { serverToken } = await fetch('/api/captcha/issue').then(r => r.json());

Captchala.init({
  appKey: 'YOUR_APP_KEY',
  serverToken,             // single-use, short-lived
  product: 'popup',
  action: 'login',
})
.appendTo('#captcha-container')
.onSuccess(res => submitForm(res.token));

セキュリティ上の注意

• app_secret をフロントエンドコード、モバイルアプリ、公開リポジトリに含めないでください。必ずサーバー側に保持します。
• ダッシュボードで「サーバー発行トークンを必須にする」を有効にすると、server_token の無いチャレンジ要求を拒否できます。
• ttl は短め（デフォルト 300 秒、最大 900 秒）にし、max_uses=1 を推奨します。

次のステップ

• Web SDK
• APIリファレンス