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

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

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

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

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

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

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

## 2. 서버 verify 바꾸기

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

| | hCaptcha | Caputchin |
|---|---|---|
| 엔드포인트 | `POST https://api.hcaptcha.com/siteverify` | `POST https://verify.caputchin.com/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":"..."}`)으로 바꾸세요. 필드 자체는 그대로입니다. 전체 요청/응답 레퍼런스는 [백엔드에서 토큰 검증하기](/docs/integration-guides/verify-on-your-backend)에 있고; 프레임워크 스니펫은 [백엔드 예제](/docs/integration-guides/backend-examples)에 있습니다.

## 3. hCaptcha Enterprise를 썼다면 점수 버리기

hCaptcha Enterprise는 위험 `score`(**높은** 숫자가 **더 많은** 위험을 뜻하는)를 돌려주고 임계값을 고르라고 요청합니다. Caputchin은 그렇게 동작하지 **않습니다**: `success`는 권위 있는 통과/실패인데, 검증이 실제로 풀렸기 때문입니다(proof-of-work 확인, 또는 [서버에서 다시 도출되는 게임 라운드](/docs/understanding-caputchin/gaming-anti-cheat)), 위험 추정이 아닙니다.

코드에 `if (data.score < 0.7)`가 있었다면, 그것을 `if (data.success)`로 바꾸세요. Caputchin의 `score` 필드는 무관합니다: 그것은 게임 라운드에만 존재하고 **게임의** 점수이니(정보 제공용, 당신 자신의 리더보드를 위한), 절대 위험이나 봇 가능성이 아니므로, 그것에 접근을 게이트하지 마세요. (방향도 반대임에 유의하세요. hCaptcha의 점수는 위험과 함께 오르고; Caputchin의 것은 게임 수행과 함께 오릅니다.)

## 옮겨 가는 것, 그리고 나아지는 것

- **당신이 hCaptcha를 고른 그 프라이버시 자세, 유지됨.** Caputchin은 IP도, User-Agent도, 지문도, 행동 텔레메트리도 수집하지 않습니다; 프로토콜에 방문자 식별자를 둘 곳이 없으니, 새거나 팔릴 것도 없습니다. [철학](/docs/understanding-caputchin/philosophy)을 보세요.
- **선택적 게임.** 이미지 선택 챌린지 대신, 검증을 방문자가 진짜로 하는 짧은 게임으로 바꿀 수 있으며, 그것이 AI 풀이기에 버티는 부분입니다. [게임 추가](/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_...`)은 서버 측에만, 바로 hCaptcha의 규율입니다. 시크릿을 브라우저로 보내지 마세요.
- **토큰은 일회용.** hCaptcha처럼, 토큰은 한 번 검증합니다. 그것을 캐시하거나 리플레이하지 마세요.
- **백엔드가 읽는 필드 이름을 바꾸세요.** 숨겨진 필드는 `h-captcha-response`가 아니라 `caputchin-token`이며, 흔한 한 줄 실수입니다.
- **본문 형식.** verify 요청을 폼 인코딩이 아니라 JSON으로 보내세요.

## 함께 보기

- [위젯 추가](/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): 검증을 게임으로 바꾸기.