---
type: how-to
title: Cloudflare Turnstile에서 이전하기
summary: "최소한의 변경으로 Cloudflare Turnstile을 Caputchin으로 바꾸세요: 같은 클라이언트 위젯 더하기 서버 verify 구조가 거의 일대일로 대응하고, Turnstile처럼 결과는 깔끔한 통과/실패입니다. 전후 비교가 여기 있습니다."
---

Caputchin은 Cloudflare Turnstile과 같은 2부 모델을 씁니다. 페이지에서 토큰을 만드는 위젯, 그리고 그것을 확인하는 서버 측 확인이라, 이전은 대부분 기계적인 교체이지 다시 쓰기가 아닙니다. Turnstile은 흔한 제공자 중 Caputchin에 가장 가까운데, 둘 다 위험 점수가 아니라 권위 있는 통과/실패를 돌려주기 때문이라, 다시 조율할 임계값이 없습니다. 이 가이드는 각 조각의 전후 비교를 줍니다.

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

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

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

Turnstile을 둘러싸 이미 지은 모든 것, 위젯 렌더링, 토큰 수집, 서버로 POST, 요청을 신뢰하기 전에 검증, 그대로입니다. 이름과 엔드포인트만 바뀝니다.

## 1. 클라이언트 스니펫 바꾸기

| | Turnstile | Caputchin |
|---|---|---|
| 스크립트 | `<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer>` | `<script src="https://cdn.jsdelivr.net/npm/@caputchin/widget@3/dist/widget.js">` |
| 요소 | `<div class="cf-turnstile" data-sitekey="...">` | `<caputchin-widget sitekey="cpt_pub_...">` |
| 폼의 토큰 필드 | `cf-turnstile-response`(자동 주입) | `caputchin-token`(자동 주입) |
| JS에서 토큰 읽기 | `turnstile.getResponse()` | [`pass` 이벤트](/docs/references/widget-methods-and-events)의 `detail.token` |

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

## 2. 서버 verify 바꾸기

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

| | Turnstile | Caputchin |
|---|---|---|
| 엔드포인트 | `POST https://challenges.cloudflare.com/turnstile/v0/siteverify` | `POST https://verify.caputchin.com/v1/siteverify` |
| 요청 필드 | `secret`, `response` | `secret`, `response`(동일) |
| 응답 | `{ success, challenge_ts, hostname, "error-codes", action, cdata }` | `{ success, challenge_ts, hostname, error-codes }` |
| 신뢰 규칙 | `success === true`일 때만 행동 | `success === true`일 때만 행동(동일) |

대부분의 스택에서 검증 코드에 대한 유일한 변경은 URL과 시크릿 값입니다; 둘 다 이미 `success`로 분기하니, 옮길 점수 임계값이 없습니다. Turnstile도 Caputchin과 똑같이 verify 호출에 JSON을 받으니, 본문 모양이 그대로 옮겨 갑니다. 오류 코드를 포함한 전체 요청/응답 레퍼런스는 [백엔드에서 토큰 검증하기](/docs/integration-guides/verify-on-your-backend)에 있고; 프레임워크 스니펫은 [백엔드 예제](/docs/integration-guides/backend-examples)에 있습니다.

Turnstile 연동이 응답에서 `action`이나 `cdata`를 읽었다면, Caputchin에는 직접적인 등가물이 없음에 유의하세요; 그것들은 당신이 위젯에 설정하는 Turnstile 고유의 라벨입니다. Caputchin의 유사한 메타데이터(어떤 게임을 했는지, 그 점수)는 응답의 `platform` 블록에 살며 정보 제공용일 뿐입니다.

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

- **여전히 깔끔한 통과/실패.** 가능한 한 가장 단순한 신뢰 규칙, `if (success)`를 유지하며, 유지할 확률이나 임계값이 없습니다.
- **당신이 Turnstile을 고른 그 프라이버시 자세, 유지됨.** 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_...`)은 서버 측에만, 바로 Turnstile의 규율입니다. 시크릿을 브라우저로 보내지 마세요.
- **토큰은 일회용.** Turnstile처럼, 토큰은 한 번 검증합니다. 그것을 캐시하거나 리플레이하지 마세요.
- **백엔드가 읽는 필드 이름을 바꾸세요.** 숨겨진 필드는 `cf-turnstile-response`가 아니라 `caputchin-token`이며, 흔한 한 줄 실수입니다.
- **`action` / `cdata` 없음.** 그것들로 분기했다면, 그 로직을 다른 곳으로 옮기세요; Caputchin은 그것들을 지니지 않습니다.

## 함께 보기

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