Web SDK

Web SDK 支持所有现代浏览器，提供多种集成方式。

30 秒在线感受效果

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

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

快速开始

<!-- 1. Load via CDN (or npm install captchala) -->
<script src="https://cdn.captcha-cdn.net/captchala-loader.js"></script>

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

<script>
loadCaptchala(function () {
  Captchala.init({
    appKey: 'YOUR_APP_KEY',
    product: 'bind',
    action: 'login',
    lang: 'auto',
  })
  .onSuccess(res => sendToBackend(res.token))
  .onError(err => console.error(err.message))
  .bindTo('#login-btn');
});
</script>

安装

CDN 引入

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

NPM 安装

npm install captchala
# or framework wrappers
npm install @captcha-la/vue
npm install @captcha-la/react

import Captchala from 'captchala';
import 'captchala/dist/captchala.css';

调用模式

弹窗模式

Captchala.init({ appKey: 'YOUR_APP_KEY', product: 'popup', action: 'login' })
  .bindTo('#login-btn')
  .onSuccess(res => sendToBackend(res.token));

浮动模式

Captchala.init({ appKey: 'YOUR_APP_KEY', product: 'float', action: 'browse' })
  .appendTo('#captcha-container')
  .onSuccess(res => sendToBackend(res.token));

绑定模式

Captchala.init({ appKey: 'YOUR_APP_KEY', product: 'bind', action: 'login' })
  .bindTo('#submit-button')
  .onSuccess(res => submitForm(res.token));   // fires only after challenge passes

嵌入模式

Captchala.init({ appKey: 'YOUR_APP_KEY', product: 'embed', action: 'register' })
  .appendTo('#captcha-container')
  .onSuccess(res => sendToBackend(res.token));

常用配置项

参数	类型	默认值	说明
appKey	string	—	应用 Key（必填）
product	string	popup	展示模式：popup
action	string	default	业务场景（如 login、register、pay）。服务端会根据场景应用不同的安全策略。
lang	string	auto	BCP-47 标签（如 en、ja、pt-BR），或 auto 跟随 navigator.language。详见下文 支持的语言（共 54 种）。
serverToken	string	—	服务端签发的一次性 token（sct_xxx）。强烈推荐生产环境使用 —— 避免用户无限刷新挑战
onServerTokenExpired	() => Promise<string>	—	serverToken 过期时触发，返回新 token 让 SDK 续挂（不中断验证流程）
enableVoice	boolean	true	是否显示语音验证入口（视觉障碍用户无障碍支持）

服务端校验

After onSuccess, send res.token (prefix pt_) to your own backend, then validate it server-side:

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": "<token>", "client_ip": "<end-user IP>" }

完整的校验接口见 API 参考。