Web SDK

Web SDK hỗ trợ mọi trình duyệt hiện đại với nhiều cách tích hợp.

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)

Bắt đầu nhanh

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

Cài đặt

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';

Các chế độ

Chế độ popup

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

Chế độ nổi

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

Chế độ bind

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

Chế độ nhúng

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

Tùy chọn phổ biến

Tham số	Kiểu	Mặc định	Mô tả
appKey	string	—	Application Key (bắt buộc)
product	string	popup	Chế độ hiển thị: popup
action	string	default	Ngữ cảnh nghiệp vụ (ví dụ: login, register, pay). Server áp dụng chính sách bảo mật khác nhau theo từng scene.
lang	string	en	Ngôn ngữ được hỗ trợ: zh-CN / zh-TW / en / ja / ko / ms / vi / id
serverToken	string	—	Token dùng một lần (sct_xxx) do server của bạn cấp. Rất nên dùng trong production để tránh lạm dụng refresh challenge không giới hạn.
onServerTokenExpired	() => Promise<string>	—	Được gọi khi serverToken hết hạn; trả về token mới để SDK tiếp tục mà không làm gián đoạn luồng.
enableVoice	boolean	true	Hiển thị điểm vào audio captcha (hỗ trợ trợ năng cho người khiếm thị).

Xác thực phía máy chủ

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

Xem Tham chiếu API để biết endpoint xác thực đầy đủ.