---
title: Web SDK
---

# Web SDK

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

::: tip 30 秒在线感受效果
[demo-v1.captcha.la](https://demo-v1.captcha.la) — 纯 HTML + PHP，MIT 协议，每页都可以直接 view-source。

- [popup.html](https://demo-v1.captcha.la/popup.html) — 弹窗模式
- [float.html](https://demo-v1.captcha.la/float.html) — 浮层模式
- [bind.html](https://demo-v1.captcha.la/bind.html) — 绑定按钮
- [inline.html](https://demo-v1.captcha.la/inline.html) — 内嵌模式
- [server-token.html](https://demo-v1.captcha.la/server-token.html) — 服务端签发 token（防重放）
:::

## 快速开始

```html
<!-- 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>
```

## 完整对接流程

一个登录表单的端到端示例。三步:渲染验证码、拿到 token、服务端校验。

### 1. 前端 —— 渲染验证码并拿到 token

```html
<form id="login-form" method="post" action="/login">
  <input name="username" placeholder="用户名" required />
  <input name="password" type="password" placeholder="密码" required />

  <!-- 验证码渲染在这里 -->
  <div id="captcha"></div>
  <!-- pass token 通过这个隐藏字段随表单回传服务端 -->
  <input type="hidden" name="captcha_token" id="captcha_token" />

  <button type="submit">登录</button>
</form>

<script src="https://cdn.captcha-cdn.net/captchala-loader.js"></script>
<script>
  loadCaptchala(function () {
    Captchala.init({
      appKey: 'YOUR_APP_KEY',
      product: 'embed',     // 内联勾选框 + 挑战
      action: 'login',      // 必须和服务端校验时一致
      lang: 'auto',
    })
      .onSuccess(function (res) {
        // res.token 是单次性 pt_ token —— 放到表单上
        document.getElementById('captcha_token').value = res.token;
      })
      .onError(function (err) {
        console.error('captcha error:', err.message);
      })
      .appendTo('#captcha');
  });
</script>
```

### 2. 服务端 —— 信任请求前先校验 token

表单提交后,服务端在校验密码**之前**先校验 `captcha_token`。推荐用官方 SDK,也可直接调 API。

::: code-group

```php [PHP]
use Captchala\Client;

$client = new Client('YOUR_APP_KEY', 'YOUR_APP_SECRET');
$result = $client->validate($_POST['captcha_token'], false, $_SERVER['REMOTE_ADDR']);

if (!$result->isValid()) {
    http_response_code(400);
    exit('人机验证未通过');
}
// 通过 —— 继续你正常的登录逻辑
```

```js [Node.js]
const r = await fetch('https://apiv1.captcha.la/v1/validate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-App-Key': 'YOUR_APP_KEY',
    'X-App-Secret': 'YOUR_APP_SECRET',
  },
  body: JSON.stringify({
    pass_token: req.body.captcha_token,
    client_ip: req.ip, // 可选,建议传
  }),
});
const { data } = await r.json();
if (!data || !data.valid) return res.status(400).send('人机验证未通过');
// 通过 —— 继续你正常的登录逻辑
```

```bash [cURL]
curl -X POST https://apiv1.captcha.la/v1/validate \
  -H "X-App-Key: YOUR_APP_KEY" \
  -H "X-App-Secret: YOUR_APP_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "pass_token": "pt_xxx", "client_ip": "1.2.3.4" }'
```

:::

### 3. 决策

token 是**单次性**且**绑定 action** 的。`valid` 为 false 就拒绝;并确认 `action` 与你期望的场景一致(别在 `pay` 接口接受 `login` 的 token)。整个闭环就这样。

> **生产建议:** 加上服务端签发的 `serverToken`(sct_),防止挑战被无限刷新。见下方[服务端校验](#服务端校验)和 [API 参考](./api-reference)。完整可跑示例:
> [PHP demo](https://github.com/Captcha-La/captchala-php-demo) ·
> [Node demo](https://github.com/Captcha-La/captchala-node-demo)。

## 安装

### CDN 引入

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

### NPM 安装

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

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

## 调用模式

### 弹窗模式

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

### 浮动模式

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

### 绑定模式

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

### 嵌入模式

```js
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 | float | embed | bind |
| `action` | string | `default` | 业务场景（如 login、register、pay）。服务端会根据场景应用不同的安全策略。 |
| `lang` | string | `auto` | BCP-47 标签（如 `en`、`ja`、`pt-BR`），或 `auto` 跟随 `navigator.language`。详见下文 [支持的语言](/zh-CN/supported-languages)（共 54 种）。 |
| `serverToken` | string | — | 服务端签发的一次性 token（sct_xxx）。强烈推荐生产环境使用 —— 避免用户无限刷新挑战 |
| `onServerTokenExpired` | `() => Promise<string>` | — | serverToken 过期时触发，返回新 token 让 SDK 续挂（不中断验证流程） |
| `enableVoice` | boolean | `true` | 是否显示语音验证入口（视觉障碍用户无障碍支持） |

## 服务端校验

`onSuccess` 回调之后，将 `res.token`（以 `pt_` 开头）发送到您自己的后端，再在服务端调用校验接口：

```bash
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>" }
```

完整的校验接口见 [API 参考](./api-reference)。