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