Переход с reCAPTCHA

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

Если ты ещё не создал аккаунт Caputchin и ключ сайта, сначала создай аккаунт; тебе понадобятся публичный ключ (cpt_pub_...) для страницы и секрет (cpt_sec_...) для бэкенда, то же разделение, что и у site key и secret key у 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()`	`detail.token` события `pass`

Как и reCAPTCHA, виджет Caputchin авто-вставляет скрытое поле токена в форму, в которой он сидит, так что если твоя форма уже делала обычный POST, ты меняешь только элемент и имя поля, которое читает твой бэкенд. Смотри добавь виджет для полной клиентской настройки и выбор CDN или npm.

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

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

	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. Сопоставь score, если ты использовал reCAPTCHA v3

reCAPTCHA v3 возвращает score (от 0.0 до 1.0) и просит тебя выбрать порог, ты гадаешь, насколько человечным выглядел запрос. Caputchin работает не так: success это авторитетное прошёл/не прошёл, потому что проверка действительно была пройдена (проверка proof-of-work или игровой раунд, перевыведенный на сервере), а не вероятность.

Если в твоём коде было if (data.score >= 0.5), замени его на if (data.success). Поле score у Caputchin существует только для игровых раундов и является счётом игры (информационным, для твоих собственных таблиц лидеров), никогда не вероятностью того, что это бот, так что не привязывай к нему доступ.

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

Никакого сбора данных посетителей. reCAPTCHA профилирует твоих посетителей; Caputchin не собирает ни IP, ни User-Agent, ни цифровой отпечаток, ни поведенческую телеметрию, протоколу некуда поместить идентификатор посетителя. Смотри философию.
Один виджет, а не v2-против-v3. Нет отдельного невидимого/балльного продукта на выбор; один элемент покрывает галочку и опциональную игру.
Опциональная игра. Вместо сетки светофоров ты можешь превратить проверку в короткую игру, в которую твои посетители и правда играют. Смотри добавь игру.
Строгий CSP остаётся строгим. Caputchin работает под жёсткой Content-Security-Policy; ты разрешаешь несколько источников, а не ослабляешь свою политику. Смотри как Caputchin изолирует игры в песочнице.

Подводные камни

Два ключа, два дома. Публичный ключ (cpt_pub_...) идёт на страницу; секрет (cpt_sec_...) остаётся только на сервере, ровно та же дисциплина, что и у reCAPTCHA. Не отправляй секрет в браузер.
Токен одноразовый. Как и у reCAPTCHA, токен проверяется один раз. Не кэшируй и не повторяй его.
Поменяй имя поля, которое читает твой бэкенд. Скрытое поле это caputchin-token, а не g-recaptcha-response, частый промах в одну строку.

См. также

Добавь виджет: полная клиентская настройка.
Проверь токен на своём бэкенде: авторитетный справочник siteverify.
Примеры бэкенда: вызов проверки на каждом языке.
Добавь игру: преврати проверку в игру.