hCaptcha에서 이전하기
Caputchin은 hCaptcha와 같은 2부 모델을 씁니다. 페이지에서 토큰을 만드는 위젯, 그리고 그것을 확인하는 서버 측 확인이라, 이전은 대부분 기계적인 교체이지 다시 쓰기가 아닙니다. 특히 서버 교환은 hCaptcha 자체가 따르는 siteverify 모양을 본떴습니다. 이 가이드는 각 조각의 전후 비교를 줍니다.
아직 Caputchin 계정과 사이트 키를 만들지 않았다면, 먼저 계정 만들기를 하세요; 페이지용 공개 키(cpt_pub_...)와 백엔드용 시크릿(cpt_sec_...)이 필요하며, hCaptcha의 사이트 키와 시크릿 키와 같은 분할입니다.
멘탈 모델은 그대로입니다
hCaptcha를 둘러싸 이미 지은 모든 것, 위젯 렌더링, 토큰 수집, 서버로 POST, 요청을 신뢰하기 전에 검증, 그대로입니다. 이름과 엔드포인트만 바뀝니다.
1. 클라이언트 스니펫 바꾸기
| hCaptcha | Caputchin | |
|---|---|---|
| 스크립트 | <script src="https://js.hcaptcha.com/1/api.js" async defer> | <script src="https://cdn.jsdelivr.net/npm/@caputchin/widget@3/dist/widget.js"> |
| 요소 | <div class="h-captcha" data-sitekey="..."> | <caputchin-widget sitekey="cpt_pub_..."> |
| 폼의 토큰 필드 | h-captcha-response(자동 주입) | caputchin-token(자동 주입) |
| JS에서 토큰 읽기 | hcaptcha.getResponse() | pass 이벤트의 detail.token |
hCaptcha처럼, Caputchin 위젯은 자기가 자리한 폼에 숨겨진 토큰 필드를 자동 주입하니, 폼이 이미 평범한 POST를 했다면 요소와 백엔드가 읽는 필드 이름만 바꿉니다. 전체 클라이언트 설정은 위젯 추가, CDN 대 npm 선택은 그 선택을 보세요.
2. 서버 verify 바꾸기
둘이 가장 가까운 곳입니다. 요청과 응답 모양이 거의 필드별로 줄을 맞춥니다.
| hCaptcha | Caputchin | |
|---|---|---|
| 엔드포인트 | POST https://api.hcaptcha.com/siteverify | POST https://caputchin.com/api/v1/siteverify |
| 요청 필드 | secret, response | secret, response(동일) |
| 응답 | { success, challenge_ts, hostname, "error-codes", score? } | { success, challenge_ts, hostname, error-codes, score? } |
| 신뢰 규칙 | success === true일 때만 행동 | success === true일 때만 행동(동일) |
형식에 관한 한 가지: hCaptcha의 verify 엔드포인트는 application/x-www-form-urlencoded를 기대하는 반면, Caputchin의 것은 JSON을 받습니다. 기존 코드가 폼 인코딩된 필드를 보냈다면, 본문을 Content-Type: application/json과 함께 JSON({"secret":"...","response":"..."})으로 바꾸세요. 필드 자체는 그대로입니다. 전체 요청/응답 레퍼런스는 백엔드에서 토큰 검증하기에 있고; 프레임워크 스니펫은 백엔드 예제에 있습니다.
3. hCaptcha Enterprise를 썼다면 점수 버리기
hCaptcha Enterprise는 위험 score(높은 숫자가 더 많은 위험을 뜻하는)를 돌려주고 임계값을 고르라고 요청합니다. Caputchin은 그렇게 동작하지 않습니다: success는 권위 있는 통과/실패인데, 검증이 실제로 풀렸기 때문입니다(proof-of-work 확인, 또는 서버에서 다시 도출되는 게임 라운드), 위험 추정이 아닙니다.
코드에 if (data.score < 0.7)가 있었다면, 그것을 if (data.success)로 바꾸세요. Caputchin의 score 필드는 무관합니다: 그것은 게임 라운드에만 존재하고 게임의 점수이니(정보 제공용, 당신 자신의 리더보드를 위한), 절대 위험이나 봇 가능성이 아니므로, 그것에 접근을 게이트하지 마세요. (방향도 반대임에 유의하세요. hCaptcha의 점수는 위험과 함께 오르고; Caputchin의 것은 게임 수행과 함께 오릅니다.)
옮겨 가는 것, 그리고 나아지는 것
- 당신이 hCaptcha를 고른 그 프라이버시 자세, 유지됨. Caputchin은 IP도, User-Agent도, 지문도, 행동 텔레메트리도 수집하지 않습니다; 프로토콜에 방문자 식별자를 둘 곳이 없으니, 새거나 팔릴 것도 없습니다. 철학을 보세요.
- 선택적 게임. 이미지 선택 챌린지 대신, 검증을 방문자가 진짜로 하는 짧은 게임으로 바꿀 수 있으며, 그것이 AI 풀이기에 버티는 부분입니다. 게임 추가를 보세요.
- 엄격한 CSP는 엄격한 채로. Caputchin은 빡빡한 Content-Security-Policy 아래에서 돌아갑니다; 정책을 느슨하게 하는 대신 몇 개의 오리진을 허용합니다. Caputchin이 게임을 샌드박싱하는 방법을 보세요.
함정
- 두 키, 두 집. 공개 키(
cpt_pub_...)는 페이지에; 시크릿(cpt_sec_...)은 서버 측에만, 바로 hCaptcha의 규율입니다. 시크릿을 브라우저로 보내지 마세요. - 토큰은 일회용. hCaptcha처럼, 토큰은 한 번 검증합니다. 그것을 캐시하거나 리플레이하지 마세요.
- 백엔드가 읽는 필드 이름을 바꾸세요. 숨겨진 필드는
h-captcha-response가 아니라caputchin-token이며, 흔한 한 줄 실수입니다. - 본문 형식. verify 요청을 폼 인코딩이 아니라 JSON으로 보내세요.
함께 보기
- 위젯 추가: 전체 클라이언트 설정.
- 백엔드에서 토큰 검증하기: 권위 있는
siteverify레퍼런스. - 백엔드 예제: 각 언어로 된 verify 호출.
- 게임 추가: 검증을 게임으로 바꾸기.