---
type: how-to
title: reCAPTCHA에서 이전하기
summary: "최소한의 변경으로 reCAPTCHA를 Caputchin으로 바꾸세요: 같은 2부 구조(클라이언트 위젯과 서버 측 verify)가 거의 일대일로 대응합니다. 각 조각의 정확한 전후 비교가 여기 있습니다."
---

Caputchin은 reCAPTCHA와 같은 2부 모델을 씁니다. 페이지에서 토큰을 만드는 위젯, 그리고 그것을 확인하는 서버 측 확인이라, 이전은 대부분 기계적인 교체이지 다시 쓰기가 아닙니다. 특히 서버 교환은 일부러 reCAPTCHA의 `siteverify` 모양을 본떴습니다. 이 가이드는 각 조각의 전후 비교를 줍니다.

아직 Caputchin 계정과 사이트 키를 만들지 않았다면, 먼저 [계정 만들기](/docs/getting-started/create-your-account)를 하세요; 페이지용 **공개 키**(`cpt_pub_...`)와 백엔드용 **시크릿**(`cpt_sec_...`)이 필요하며, reCAPTCHA의 사이트 키와 시크릿 키와 같은 분할입니다.

## 멘탈 모델은 그대로입니다

```mermaid
flowchart LR
  A["페이지의 위젯"] -->|token| B["당신의 폼 / 요청"]
  B -->|token| C["당신의 백엔드"]
  C -->|secret + token| D["siteverify 엔드포인트"]
  D -->|success?| C
```

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` 이벤트](/docs/references/widget-methods-and-events)의 `detail.token` |

reCAPTCHA처럼, Caputchin 위젯은 자기가 자리한 폼에 **숨겨진 토큰 필드를 자동 주입**하니, 폼이 이미 평범한 POST를 했다면 요소와 백엔드가 읽는 필드 이름만 바꿉니다. 전체 클라이언트 설정은 [위젯 추가](/docs/getting-started/add-the-widget), CDN 대 npm 선택은 [그 선택](/docs/integration-guides/cdn)을 보세요.

## 2. 서버 verify 바꾸기

둘이 가장 가까운 곳입니다. 요청과 응답 모양이 거의 필드별로 줄을 맞춥니다.

| | reCAPTCHA | Caputchin |
|---|---|---|
| 엔드포인트 | `POST https://www.google.com/recaptcha/api/siteverify` | `POST https://verify.caputchin.com/v1/siteverify` |
| 요청 필드 | `secret`, `response` | `secret`, `response`(동일) |
| 응답 | `{ success, challenge_ts, hostname, "error-codes" }` | `{ success, challenge_ts, hostname, error-codes, score? }` |
| 신뢰 규칙 | `success === true`일 때만 행동 | `success === true`일 때만 행동(동일) |

대부분의 스택에서 검증 코드에 대한 유일한 변경은 URL과 시크릿 값입니다. 오류 코드를 포함한 전체 요청/응답 레퍼런스는 [백엔드에서 토큰 검증하기](/docs/integration-guides/verify-on-your-backend)에 있고; 프레임워크 스니펫은 [백엔드 예제](/docs/integration-guides/backend-examples)에 있습니다.

## 3. reCAPTCHA v3을 썼다면 점수 대응하기

reCAPTCHA v3은 `score`(0.0에서 1.0)를 돌려주고 임계값을 고르라고 요청합니다. 요청이 얼마나 사람다워 보였는지 추측하는 셈입니다. Caputchin은 그렇게 동작하지 **않습니다**: `success`는 권위 있는 통과/실패인데, 검증이 실제로 풀렸기 때문입니다(proof-of-work 확인, 또는 [서버에서 다시 도출되는 게임 라운드](/docs/understanding-caputchin/gaming-anti-cheat)), 확률이 아닙니다.

코드에 `if (data.score >= 0.5)`가 있었다면, 그것을 `if (data.success)`로 바꾸세요. Caputchin의 `score` 필드는 게임 라운드에만 존재하고 **게임의** 점수이니(정보 제공용, 당신 자신의 리더보드를 위한), 절대 봇 가능성이 아니므로, 그것에 접근을 게이트하지 마세요.

## 옮기면 나아지는 것

- **방문자 데이터 수집 없음.** reCAPTCHA는 당신의 방문자를 프로파일링합니다; Caputchin은 IP도, User-Agent도, 지문도, 행동 텔레메트리도 수집하지 않으며, 프로토콜에 방문자 식별자를 둘 곳이 없습니다. [철학](/docs/understanding-caputchin/philosophy)을 보세요.
- **v2 대 v3이 아니라 하나의 위젯.** 사이에서 고를 별도의 보이지 않는/점수 제품이 없습니다; 한 요소가 체크박스와 선택적 게임을 덮습니다.
- **선택적 게임.** 신호등 격자 대신, 검증을 방문자가 진짜로 하는 짧은 게임으로 바꿀 수 있습니다. [게임 추가](/docs/getting-started/add-a-game)를 보세요.
- **엄격한 CSP는 엄격한 채로.** Caputchin은 빡빡한 Content-Security-Policy 아래에서 돌아갑니다; 정책을 느슨하게 하는 대신 몇 개의 오리진을 허용합니다. [Caputchin이 게임을 샌드박싱하는 방법](/docs/understanding-caputchin/game-sandboxing#the-csp-you-set-on-your-own-page)을 보세요.

## 함정

- **두 키, 두 집.** 공개 키(`cpt_pub_...`)는 페이지에; 시크릿(`cpt_sec_...`)은 서버 측에만, 바로 reCAPTCHA의 규율입니다. 시크릿을 브라우저로 보내지 마세요.
- **토큰은 일회용.** reCAPTCHA처럼, 토큰은 한 번 검증합니다. 그것을 캐시하거나 리플레이하지 마세요.
- **백엔드가 읽는 필드 이름을 바꾸세요.** 숨겨진 필드는 `g-recaptcha-response`가 아니라 `caputchin-token`이며, 흔한 한 줄 실수입니다.

## 함께 보기

- [위젯 추가](/docs/getting-started/add-the-widget): 전체 클라이언트 설정.
- [백엔드에서 토큰 검증하기](/docs/integration-guides/verify-on-your-backend): 권위 있는 `siteverify` 레퍼런스.
- [백엔드 예제](/docs/integration-guides/backend-examples): 각 언어로 된 verify 호출.
- [게임 추가](/docs/getting-started/add-a-game): 검증을 게임으로 바꾸기.