Quickstart

Panduan ini akan membantu Anda mengintegrasikan CaptchaLa CAPTCHA dalam 5 menit.

Lihat dalam 30 detik

demo-v1.captcha.la — HTML + PHP murni, lisensi MIT, view-source di setiap halaman.

• popup.html — mode popup
• float.html — widget mengambang
• bind.html — ikat ke tombol
• inline.html — sematan inline
• server-token.html — token terbitan server (anti-replay)

1. Buat Akun

Daftar akun gratis di dashboard

Daftar Sekarang →

2. Buat Aplikasi

Buat aplikasi di dashboard untuk mendapatkan App Key Anda

3. Instal SDK

Pilih metode instalasi yang Anda inginkan

<!-- 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. Inisialisasi CAPTCHA

Inisialisasi komponen CAPTCHA di halaman Anda

<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. Verifikasi Server

Verifikasi token di server Anda

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.

Mode Token yang Diterbitkan Server (direkomendasikan untuk production)

Untuk aksi sensitif (login, register, payment) kami merekomendasikan alur token yang diterbitkan server: backend Anda terlebih dahulu meminta server_token yang berumur pendek, lalu browser menggunakan token tersebut untuk menginisialisasi CAPTCHA. Ini mencegah penyalahgunaan bila app_key bocor.

Kapan digunakan

• Direkomendasikan: register, login, reset password, payment, penukaran poin, dan endpoint apa pun yang bisa di-script oleh penyerang.
• Opsional: form publik biasa, kotak pencarian, dan interaksi bernilai rendah ketika kenyamanan lebih penting.

1. Backend menerbitkan server_token

Panggil /v1/server/challenge/issue dari server Anda sendiri, menggunakan header X-App-Key dan X-App-Secret. Jangan pernah mengekspos header ini ke browser.

# 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 merender CaptchaLa dengan server_token

Teruskan token ke komponen CaptchaLa Anda. SDK akan meneruskannya ke inisialisasi verifikasi saat menginisialisasi 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));

Catatan keamanan

• Jangan pernah menaruh app_secret di kode frontend, aplikasi mobile, atau repository publik. Rahasia ini harus tetap berada di sisi server.
• Aktifkan "Require server-issued challenge token" di dashboard untuk menolak challenge yang dicoba tanpa server_token.
• Jaga ttl tetap pendek (default 300 detik, maks 900 detik) dan utamakan max_uses=1 untuk mengurangi dampak kebocoran token.

Langkah berikutnya

• Web SDK
• Referensi API