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

## 安裝

### 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` | 業務場景 |
| `lang` | string | `en` | 支援語言：zh-CN / zh-TW / en / ja / ko / ms / vi / id |
| `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)。