Переход с Cloudflare Turnstile
Caputchin использует ту же двухчастную модель, что и Cloudflare Turnstile, виджет на странице, который выдаёт токен, и серверную проверку, которая его подтверждает, так что переход это в основном механическая замена, а не переписывание. Turnstile из распространённых провайдеров ближе всех к Caputchin, потому что оба возвращают авторитетное прошёл/не прошёл, а не рисковый счёт, так что нет порога для перенастройки. Это руководство даёт до-и-после для каждой части.
Если ты ещё не создал аккаунт Caputchin и ключ сайта, сначала создай аккаунт; тебе понадобятся публичный ключ (cpt_pub_...) для страницы и секрет (cpt_sec_...) для бэкенда, то же разделение, что и у site key и secret key у Turnstile.
Ментальная модель не меняется
Всё, что ты уже построил вокруг 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() | detail.token события pass |
Как и Turnstile, виджет Caputchin авто-вставляет скрытое поле токена в форму, в которой он сидит, так что если твоя форма уже делала обычный POST, ты меняешь только элемент и имя поля, которое читает твой бэкенд. Смотри добавь виджет для полной клиентской настройки и выбор CDN или npm.
2. Замени серверную проверку
Вот где эти двое ближе всего, формы запроса и ответа сходятся почти поле в поле.
| Turnstile | Caputchin | |
|---|---|---|
| Эндпоинт | POST https://challenges.cloudflare.com/turnstile/v0/siteverify | POST https://caputchin.com/api/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 тоже принимает JSON для вызова проверки, ровно как Caputchin, так что форма тела переносится без изменений. Полный справочник запроса/ответа, включая коды ошибок, на странице проверь токен на своём бэкенде; сниппеты по фреймворкам в примерах бэкенда.
Если твоя интеграция Turnstile читала action или cdata из ответа, заметь, что у Caputchin нет прямого эквивалента; это специфичные для Turnstile метки, которые ты задаёшь на виджете. Аналогичные метаданные Caputchin (в какую игру играли, её счёт) живут в блоке platform ответа и только информационные.
Что переносится, а что становится лучше
- По-прежнему чистое прошёл/не прошёл. Ты сохраняешь простейшее возможное правило доверия,
if (success), без вероятности или порога для поддержки. - Приватность, ради которой ты выбрал Turnstile, сохранена. Caputchin не собирает ни IP, ни User-Agent, ни цифровой отпечаток, ни поведенческую телеметрию; протоколу некуда поместить идентификатор посетителя. Смотри философию.
- Опциональная игра. Вместо невидимого или управляемого испытания ты можешь превратить проверку в короткую игру, в которую твои посетители и правда играют, и это та часть, что выстаивает против ИИ-решателей. Смотри добавь игру.
- Строгий CSP остаётся строгим. Caputchin работает под жёсткой Content-Security-Policy; ты разрешаешь несколько источников, а не ослабляешь свою политику. Смотри как Caputchin изолирует игры в песочнице.
Подводные камни
- Два ключа, два дома. Публичный ключ (
cpt_pub_...) идёт на страницу; секрет (cpt_sec_...) остаётся только на сервере, ровно та же дисциплина, что и у Turnstile. Не отправляй секрет в браузер. - Токен одноразовый. Как и у Turnstile, токен проверяется один раз. Не кэшируй и не повторяй его.
- Поменяй имя поля, которое читает твой бэкенд. Скрытое поле это
caputchin-token, а неcf-turnstile-response, частый промах в одну строку. - Нет
action/cdata. Если ты ветвился на них, перенеси эту логику в другое место; Caputchin их не несёт.
См. также
- Добавь виджет: полная клиентская настройка.
- Проверь токен на своём бэкенде: авторитетный справочник
siteverify. - Примеры бэкенда: вызов проверки на каждом языке.
- Добавь игру: преврати проверку в игру.