---
type: how-to
title: Переход с reCAPTCHA
summary: "Замени reCAPTCHA на Caputchin с минимальными изменениями: та же двухчастная форма (клиентский виджет плюс серверная проверка) отображается почти один в один, ниже точное до-и-после для каждой части."
---

Caputchin использует ту же двухчастную модель, что и reCAPTCHA, виджет на странице, который выдаёт токен, и серверную проверку, которая его подтверждает, так что переход это в основном механическая замена, а не переписывание. Серверный обмен в особенности намеренно повторяет форму `siteverify` у reCAPTCHA. Это руководство даёт до-и-после для каждой части.

Если ты ещё не создал аккаунт Caputchin и ключ сайта, сначала [создай аккаунт](/docs/getting-started/create-your-account); тебе понадобятся **публичный ключ** (`cpt_pub_...`) для страницы и **секрет** (`cpt_sec_...`) для бэкенда, то же разделение, что и у site key и secret key у 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()` | `detail.token` события [`pass`](/docs/references/widget-methods-and-events) |

Как и reCAPTCHA, виджет Caputchin **авто-вставляет скрытое поле токена** в форму, в которой он сидит, так что если твоя форма уже делала обычный POST, ты меняешь только элемент и имя поля, которое читает твой бэкенд. Смотри [добавь виджет](/docs/getting-started/add-the-widget) для полной клиентской настройки и [выбор CDN или npm](/docs/integration-guides/cdn).

## 2. Замени серверную проверку

Вот где эти двое ближе всего, формы запроса и ответа сходятся почти поле в поле.

| | 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. Сопоставь score, если ты использовал 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)`. Поле `score` у Caputchin существует только для игровых раундов и является счётом **игры** (информационным, для твоих собственных таблиц лидеров), никогда не вероятностью того, что это бот, так что не привязывай к нему доступ.

## Что становится лучше при переходе

- **Никакого сбора данных посетителей.** 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, токен проверяется один раз. Не кэшируй и не повторяй его.
- **Поменяй имя поля, которое читает твой бэкенд.** Скрытое поле это `caputchin-token`, а не `g-recaptcha-response`, частый промах в одну строку.

## См. также

- [Добавь виджет](/docs/getting-started/add-the-widget): полная клиентская настройка.
- [Проверь токен на своём бэкенде](/docs/integration-guides/verify-on-your-backend): авторитетный справочник `siteverify`.
- [Примеры бэкенда](/docs/integration-guides/backend-examples): вызов проверки на каждом языке.
- [Добавь игру](/docs/getting-started/add-a-game): преврати проверку в игру.