Bắt đầu nhanh

Hướng dẫn này sẽ giúp bạn tích hợp CaptchaLa CAPTCHA trong 5 phút.

Xem nó hoạt động trong 30 giây

demo-v1.captcha.la — HTML + PHP thuần, giấy phép MIT, có thể view-source mọi trang.

• popup.html — chế độ popup
• float.html — widget nổi
• bind.html — gắn vào nút
• inline.html — nhúng trong dòng
• server-token.html — token do máy chủ phát hành (chống replay)

1. Tạo tài khoản

Đăng ký tài khoản miễn phí trong dashboard

Đăng ký ngay →

2. Tạo ứng dụng

Tạo ứng dụng trong dashboard để lấy App Key

3. Cài đặt SDK

Chọn cách cài đặt bạn muốn

<!-- 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. Khởi tạo CAPTCHA

Khởi tạo thành phần CAPTCHA trong trang của bạn

<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. Xác minh phía server

Xác minh token trên server của bạn

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.

Chế độ Token do server cấp (khuyến nghị cho production)

Đối với các thao tác nhạy cảm (đăng nhập, đăng ký, thanh toán), chúng tôi khuyến nghị luồng token do server cấp: backend của bạn sẽ yêu cầu một server_token có thời gian sống ngắn trước, sau đó trình duyệt dùng token đó để khởi tạo CAPTCHA. Cách này giúp ngăn lạm dụng khi app_key bị lộ.

Khi nào nên dùng

• Khuyến nghị: đăng ký, đăng nhập, đặt lại mật khẩu, thanh toán, đổi điểm và mọi endpoint có thể bị kẻ tấn công tự động hóa bằng script.
• Tùy chọn: biểu mẫu công khai, ô tìm kiếm và các tương tác giá trị thấp nơi sự tiện lợi quan trọng hơn.

1. Backend cấp server_token

Gọi /v1/server/challenge/issue từ chính server của bạn, dùng header X-App-Key và X-App-Secret. Không bao giờ để lộ các header này ra trình duyệt.

# 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. Frontend render CaptchaLa với server_token

Truyền token vào thành phần CaptchaLa. SDK sẽ chuyển tiếp nó đến khởi tạo xác minh khi khởi tạo challenge.

// 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));

Lưu ý bảo mật

• Không bao giờ đặt app_secret trong mã frontend, ứng dụng mobile hoặc repository công khai. Nó phải luôn nằm ở phía server.
• Bật "Require server-issued challenge token" trong dashboard để từ chối mọi challenge được thử mà không có server_token.
• Hãy giữ ttl ngắn (mặc định 300 giây, tối đa 900 giây) và ưu tiên max_uses=1 để giảm tác động nếu token bị lộ.

Bước tiếp theo

• Web SDK
• Tài liệu API