Web SDK

Web SDK는 모든 최신 브라우저를 지원하며 여러 통합 방식을 제공합니다.

30초 만에 실제 동작 확인

demo-v1.captcha.la — 순수 HTML + PHP, MIT 라이선스, 모든 페이지 view-source 가능.

• popup.html — 팝업 모드
• float.html — 플로팅
• bind.html — 버튼 바인딩
• inline.html — 인라인 임베드
• server-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

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

호출 모드

팝업 모드

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

플로트 모드

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

바인드 모드

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

임베드 모드

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
action	string	default	비즈니스 장면(예: login, register, pay). 서버는 장면별로 다른 보안 정책을 적용합니다.
lang	string	en	지원 언어: zh-CN / zh-TW / en / ja / ko / ms / vi / id
serverToken	string	—	서버가 발급한 단일 사용 token(sct_xxx). 프로덕션에서 강력히 권장됩니다. challenge 무한 새로고침 남용을 막습니다.
onServerTokenExpired	() => Promise<string>	—	serverToken 이 만료될 때 호출됩니다. 흐름을 끊지 않도록 새 token을 반환하세요.
enableVoice	boolean	true	오디오 CAPTCHA 진입점을 표시합니다 (시각 장애 사용자를 위한 접근성 지원).

서버 측 검증

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

전체 검증 엔드포인트는 API 레퍼런스를 참고하세요.