마이그레이션 가이드

hCaptcha에서 CaptchaLa로 마이그레이션

10분 이내에 끝나는 즉시 교체. 폼 형태는 동일하면서도 위젯이 더 빠르고, 이미지 분류 단계가 없으며, 당신의 트래픽은 당신의 것으로 남습니다.

hhCaptchaCurrent setup~10 minCaptchaLaDrop-in target

코드 변경 예시

Before — hCaptcha
<div class="h-captcha" data-sitekey="YOUR_SITE_KEY"></div>
<script src="https://js.hcaptcha.com/1/api.js" async defer></script>
After — CaptchaLa
<button id="login-btn">Sign in</button>
<script src="https://cdn.captcha-cdn.net/captchala-loader.js"></script>
<script>
  loadCaptchala(() => Captchala.init({ appKey: 'YOUR_APP_KEY', action: 'login' })
    .onSuccess(res => onToken(res.token))
    .bindTo('#login-btn'));
</script>
Before — hCaptcha server verify (Node)
const res = await fetch('https://api.hcaptcha.com/siteverify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    secret: process.env.HCAPTCHA_SECRET,
    response: req.body['h-captcha-response'],
  }),
})
const data = await res.json()
if (!data.success) return res.status(400).json({ error: 'bot' })
After — CaptchaLa server verify (Node)
const res = await fetch('https://apiv1.captcha.la/v1/validate', {
  method: 'POST',
  headers: {
    'X-App-Key': process.env.CAPTCHALA_APP_KEY,
    'X-App-Secret': process.env.CAPTCHALA_APP_SECRET,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ pass_token: req.body['captchala-token'] }),
})
const { data } = await res.json()
if (!data || !data.valid) return res.status(400).json({ error: 'bot' })

마이그레이션 단계

  1. 1

    가입하고 App Key + Secret 받기

    무료 CaptchaLa 계정을 만들고 사이트를 추가한 뒤, App Key(공개)와 App Secret(서버용)을 복사하세요. 카드 등록은 필요 없습니다.

  2. 2

    위젯 태그 교체

    h-captcha 클래스를 captchala로, data-sitekey를 data-app-key로, script src를 당사 CDN URL로 바꾸세요. 구조는 동일하게 유지됩니다.

  3. 3

    숨김 필드명 변경

    hCaptcha는 h-captcha-response를, CaptchaLa는 captchala-token을 삽입합니다. 폼 핸들러에서 이름으로 참조한다면 필드명을 찾아 바꾸세요.

  4. 4

    서버 검증 업데이트

    엔드포인트를 apiv1.captcha.la/v1/validate로 변경하세요. 당사는 JSON을 사용하므로(hCaptcha는 form-urlencoded 사용) Content-Type과 본문을 업데이트하세요. valid 플래그(data.valid)는 여전히 응답에 있으므로 분기 코드는 그대로 유지됩니다.

  5. 5

    점진적으로 배포

    폼 하나에 먼저 CaptchaLa를 적용하고 몇 시간 동안 전환율과 챌린지 비율을 측정하세요. 이미지 분류 단계가 사라지기 때문에 대부분의 팀은 곧바로 완료율이 유지되거나 개선되는 것을 확인합니다.

자주 묻는 질문

내 hCaptcha 계정은 어떻게 되나요?

아무 일도 없습니다. 그대로 두고 요청만 보내지 않으면 됩니다. 계약도, 통지 절차도 없습니다. 계정은 휴면 상태로 남습니다. 정식으로 닫고 싶다면 hCaptcha에 셀프서비스 계정 삭제 옵션이 있습니다.

Core Web Vitals가 개선되나요?

보통은 그렇습니다. hCaptcha 위젯은 폼 페이지의 LCP에 일반적으로 400~600ms를 추가합니다. CaptchaLa 위젯은 <100ms를 목표로 합니다. 정확한 차이는 페이지의 다른 예산에 따라 달라지지만, 폼이 많은 페이지에서는 차이가 뚜렷합니다.

내가 사용 중인 hCaptcha Enterprise 기능은 어떻게 되나요?

대부분의 엔터프라이즈 기능(맞춤 테마, 고급 위험 점수, 분석 대시보드)은 CaptchaLa 표준 플랜에 직접 대응하는 항목이 있습니다. 문서의 마이그레이션 페이지에 각 기능과 그에 해당하는 CaptchaLa 항목이 나열되어 있습니다.