Переход с hCaptcha

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

Если ты ещё не создал аккаунт Caputchin и ключ сайта, сначала создай аккаунт; тебе понадобятся публичный ключ (cpt_pub_...) для страницы и секрет (cpt_sec_...) для бэкенда, то же разделение, что и у site key и secret key у hCaptcha.

Ментальная модель не меняется

Всё, что ты уже построил вокруг 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()`	`detail.token` события `pass`

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

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

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

	hCaptcha	Caputchin
Эндпоинт	`POST https://api.hcaptcha.com/siteverify`	`POST https://caputchin.com/api/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 ожидает application/x-www-form-urlencoded, а у Caputchin принимает JSON. Если твой существующий код слал поля в form-encoded виде, переключи тело на JSON ({"secret":"...","response":"..."}) с Content-Type: application/json. Сами поля не меняются. Полный справочник запроса/ответа на странице проверь токен на своём бэкенде; сниппеты по фреймворкам в примерах бэкенда.

3. Откажись от score, если ты использовал hCaptcha Enterprise

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

Если в твоём коде было if (data.score < 0.7), замени его на if (data.success). Поле score у Caputchin никак не связано: оно существует только для игровых раундов и является счётом игры (информационным, для твоих собственных таблиц лидеров), никогда не риском или вероятностью бота, так что не привязывай к нему доступ. (Заметь, что направление тоже обратное, счёт hCaptcha растёт с риском; у Caputchin растёт с игровым результатом.)

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

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

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

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

См. также

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