快速入门

本指南将帮助您在 5 分钟内完成 CaptchaLa 验证码的接入。

30 秒在线感受效果

demo-v1.captcha.la — 纯 HTML + PHP，MIT 协议，每页都可以直接 view-source。

• popup.html — 弹窗模式
• float.html — 浮层模式
• bind.html — 绑定按钮
• inline.html — 内嵌模式
• server-token.html — 服务端签发 token（防重放）

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. 初始化验证码

在页面中初始化验证码组件

<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. 服务端验证

在服务端验证 Token 的有效性

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.

服务端签发 Token 模式（推荐用于生产环境）

对于敏感操作（登录、注册、支付）推荐使用服务端签发 Token 流程：由您的后端先申请一个短时效的 server_token，再由浏览器凭该 Token 初始化验证码。可有效防止 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

将 Token 传给 CaptchaLa 组件。SDK 会在调用 验证初始化 初始化挑战时携带该 Token。

// 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 写入前端代码、移动端应用或公开仓库，必须只保留在服务端。
• 在控制台启用「要求服务端签发验证 Token」，即可拒绝所有未携带 server_token 的挑战请求。
• 建议使用较短的 ttl（默认 300 秒，最大 900 秒），并优先选择 max_uses=1，降低 Token 泄漏带来的风险。

下一步

• Web SDK
• API 参考