---
title: 快速入門
---

# 快速入門

本指南將幫助您在 5 分鐘內完成 CaptchaLa 驗證碼的接入。

::: 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（防重放）
:::


## 1. 註冊帳號

訪問控制台註冊一個免費帳號

[立即註冊 →](https://dash.captcha.la/register)

## 2. 建立應用

在控制台建立一個應用，取得 App Key

## 3. 安裝 SDK

選擇適合您的安裝方式

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

```bash
# or via npm
npm install captchala
```

## 4. 初始化驗證碼

在頁面中初始化驗證碼元件

```html
<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 的有效性

```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": "<from onSuccess>" }
```

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

::: warning
請務必同時檢查 `data.valid === true` **以及** `data.action` 與您預期的場景一致。
Pass token 為單次使用；同一個 `pt_xxx` 不可重複驗證。
:::

## 伺服器端簽發 Token 模式（推薦用於正式環境） {#server-token}

對於敏感操作（登入、註冊、支付）建議使用伺服器端簽發 Token 流程：由您的後端先申請一個短時效的 server_token，再由瀏覽器憑該 Token 初始化驗證碼，可有效防止 app_key 外洩後被濫用。

### 適用場景

- 推薦：註冊、登入、找回密碼、支付、積分兌換，以及任何可被腳本化攻擊的接口。
- 可選：公開表單、搜尋框等低價值、對便捷性要求較高的互動。

### 1. 後端簽發 server_token

在您的伺服器端呼叫 /v1/server/challenge/issue，攜帶 X-App-Key 與 X-App-Secret 標頭。切勿將這兩個標頭暴露給瀏覽器。

```bash
# 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。

```js
// 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](./web-sdk)
- [API 參考](./api-reference)