CapMonster Cloud API
Расширение для браузеров
Как добавить CAPTCHA в HTML: простое руководство для разработчиков
Добавление CAPTCHA в HTML-форму — одна из самых эффективных первых линий защиты от ботов, спама и автоматизированных атак. Независимо от того, защищаете ли вы страницу входа, форму обратной связи или процесс оформления заказа, правильно выбранная CAPTCHA и ее корректная реализация могут существенно повлиять на результат.
Это руководство пошагово покажет, как добавить HTML-код CAPTCHA в ваш проект, и рассмотрит четыре популярных варианта: reCAPTCHA v2 (Checkbox и Invisible), Cloudflare Turnstile, Prosopo Procaptcha и Altcha. Для каждого из них вы получите подробное объяснение, рабочие примеры HTML-кода и рекомендации по проверке на сервере, локальному тестированию и устранению неполадок.
Что нужно перед началом работы
Практически любое решение CAPTCHA строится вокруг одной и той же базовой концепции: вы регистрируете свой сайт у провайдера CAPTCHA, получаете пару ключей CAPTCHA (публичный site key и приватный secret key) и используете эти ключи для встраивания виджета и проверки ответов.
Вот где нужно зарегистрироваться у каждого провайдера, прежде чем вы напишете хотя бы одну строку HTML:
Во время регистрации вас попросят указать доменное имя сайта. Для локальной разработки добавьте localhost в список разрешённых доменов (подробнее об этом в разделе тестирования).
reCAPTCHA v2 Checkbox — пошаговая инструкция
Классический флажок ("I'm not a robot") — самый узнаваемый captcha html-виджет. Он отображает видимый чекбокс и, при необходимости, визуальное задание с изображениями.
Шаг 1: зарегистрируйтесь и получите свои ключи CAPTCHA
Перейдите на google.com/recaptcha/admin и выберите reCAPTCHA v2 → "I'm not a robot" Checkbox. Добавьте свой домен (включая localhost для локального тестирования) и отправьте форму. Вы получите Site Key и Secret Key.
Шаг 2: добавьте скрипт reCAPTCHA API
Разместите следующий тег <script> в разделе <head> вашего HTML или перед закрывающим тегом </body>:
<script src="https://www.google.com/recaptcha/api.js" async defer></script>Атрибуты async и defer обеспечивают загрузку скрипта без блокировки отрисовки страницы.
Шаг 3: добавьте div виджета в форму
Разместите элемент <div> внутри формы, непосредственно перед кнопкой отправки. Замените YOUR_SITE_KEY на полученный site key.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Форма обратной связи</title>
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
</head>
<body>
<form action="/submit" method="POST">
<label for="email">Электронная почта:</label>
<input type="email" id="email" name="email" required>
<label for="message">Сообщение:</label>
<textarea id="message" name="message" required></textarea>
<!-- Виджет reCAPTCHA v2 Checkbox -->
<div class="g-recaptcha" data-sitekey="YOUR_SITE_KEY"></div>
<button type="submit">Отправить</button>
</form>
</body>
</html>Шаг 4: что происходит при отправке формы
Когда пользователь проходит проверку и отправляет форму, скрипт Google автоматически добавляет в данные формы скрытое поле с именем g-recaptcha-response. Ваш бэкенд считывает этот токен и отправляет его в API верификации Google вместе с вашим секретным ключом.
reCAPTCHA v2 Invisible — пошаговая инструкция
Invisible reCAPTCHA полностью убирает видимый чекбокс. Вместо этого она выполняет анализ рисков в фоновом режиме и запускает визуальную проверку только при обнаружении подозрительного поведения — в результате большинство пользователей даже не испытают какого-либо неудобства.
Шаг 1: зарегистрируйтесь с правильным типом
В консоли администратора Google reCAPTCHA выберите reCAPTCHA v2 → Invisible reCAPTCHA. Для этого будет сгенерирован другой site key — не используйте одни и те же ключи для разных типов CAPTCHA.
Шаг 2: загрузите API-скрипт
Используйте тот же тег script, что и для варианта Checkbox:
<script src="https://www.google.com/recaptcha/api.js" async defer></script>Шаг 3: привяжите CAPTCHA к кнопке отправки
Вместо отдельного <div> вы добавляете атрибуты CAPTCHA прямо к кнопке отправки <button>, указывая JavaScript-колбэк, который будет вызван после завершения проверки.
Определите функцию-колбэк, которая программно отправит форму после успешной верификации.
Полный пример HTML-формы
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Регистрация</title>
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
</head>
<body>
<form id="signup-form" action="/signup" method="POST">
<label for="username">Имя пользователя:</label>
<input type="text" id="username" name="username" required>
<!-- Invisible reCAPTCHA: привязана к кнопке -->
<button
class="g-recaptcha"
data-sitekey="YOUR_SITE_KEY"
data-callback="onSubmit"
data-size="invisible">
Создать аккаунт
</button>
</form>
<script>
function onSubmit(token) {
document.getElementById("signup-form").submit();
}
</script>
</body>
</html>Когда пользователь нажимает кнопку, reCAPTCHA выполняет фоновый анализ, вызывает onSubmit(token) с токеном ответа, а ваш колбэк отправляет форму. Токен включается в тело POST-запроса как g-recaptcha-response.
Cloudflare Turnstile — пошаговая инструкция
Cloudflare Turnstile — это CAPTCHA-альтернатива с приоритетом на приватность, которая не отслеживает пользователей, не устанавливает cookie для профилирования и не показывает задания с картинками. Она предлагает три режима виджета:
Шаг 1: создайте виджет в Cloudflare Dashboard
Войдите в свою учётную запись Cloudflare, перейдите в раздел Application security → Turnstile, нажмите Add widget, введите свой домен и выберите тип виджета. Скопируйте Site Key и запишите свой Secret Key.
Шаг 2: добавьте скрипт Turnstile
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>Шаг 3: добавьте div виджета в форму
<div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>Turnstile автоматически добавляет в форму скрытое поле с именем cf-turnstile-response. Для стандартной отправки формы дополнительный JavaScript не требуется.
Полный пример HTML-формы
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Вход</title>
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
</head>
<body>
<form action="/login" method="POST">
<label for="password">Пароль:</label>
<input type="password" id="password" name="password" required>
<!-- Виджет Cloudflare Turnstile -->
<div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>
<button type="submit">Войти</button>
</form>
</body>
</html>Режим Managed в Turnstile будет определять — на основе сигналов браузера — нужно ли показывать задание или пропустить пользователя без него. Для тестирования Cloudflare предоставляет специальные фиктивные site key (рассматриваются в разделе тестирования).
Prosopo Procaptcha — пошаговая инструкция
Prosopo Procaptcha — это ориентированная на Web3 CAPTCHA с приоритетом на приватность, разработанная как прямая drop-in-замена reCAPTCHA. Она не зависит от инфраструктуры Google и изначально построена с учётом приватности пользователей как ключевого принципа.
Шаг 1: получите ключ CAPTCHA от Prosopo
Зарегистрируйтесь на prosopo.io, чтобы получить Site Key.
Шаг 2: загрузите bundle Procaptcha
Добавьте скрипт Procaptcha:
<script src="https://js.prosopo.io/js/procaptcha.bundle.js" async defer></script>Шаг 3: добавьте виджет в форму
Разместите <div> с классом procaptcha и вашим site key в атрибуте data-sitekey.
Полный пример HTML-формы
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Регистрация</title>
<script type="module" src="https://js.prosopo.io/js/procaptcha.bundle.js" async defer></script>
</head>
<body>
<form action="/register" method="POST">
<label for="email">Электронная почта:</label>
<input type="email" id="email" name="email" required>
<!-- Виджет Prosopo Procaptcha -->
<div class="procaptcha" data-sitekey="YOUR_SITE_KEY"></div>
<button type="submit">Зарегистрироваться</button>
</form>
</body>
</html>Шаг 4: отправка токена
При отправке формы Procaptcha добавляет в неё скрытое поле с именем procaptcha-response. Передайте этот токен в API верификации Prosopo вместе с вашим секретным ключом на бэкенде.
Altcha — пошаговая инструкция
Altcha — это полностью open-source CAPTCHA с самостоятельным хостингом, использующая механизм proof-of-work — браузер пользователя выполняет небольшую вычислительную задачу вместо решения визуальной головоломки. Она не собирает пользовательские данные, не устанавливает tracking-cookie и полностью соответствует GDPR. Поскольку она работает на вашем хостинге, зависимость от сторонних сервисов отсутствует.
Шаг 1: загрузите виджет Altcha
Регистрация не требуется. Подключите скрипт кастомного элемента:
<script async defer type="module"
src="https://cdn.jsdelivr.net/gh/altcha-org/altcha/dist/altcha.min.js">
</script>Шаг 2: настройте endpoint задания
Для Altcha требуется серверный endpoint, который генерирует криптографическое задание (с использованием HMAC secret key, который вы задаёте сами). Этот endpoint вызывается виджетом перед отправкой формы, чтобы получить новое задание. Библиотека Altcha для вашего фреймворка берёт эту задачу на себя. URL endpoint'а передаётся виджету через атрибут challengeurl.
Шаг 3: добавьте виджет в HTML-форму
Полный пример HTML-формы
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Обратная связь</title>
<script async defer type="module"
src="https://cdn.jsdelivr.net/gh/altcha-org/altcha/dist/altcha.min.js">
</script>
</head>
<body>
<form action="/feedback" method="POST">
<label for="feedback">Ваш отзыв:</label>
<textarea id="feedback" name="feedback" required></textarea>
<!-- Виджет Altcha -- указывает на ваш собственный endpoint challenge -->
<altcha-widget challengeurl="/api/altcha-challenge"></altcha-widget>
<button type="submit">Отправить</button>
</form>
</body>
</html>Шаг 4: отправка токена
После завершения proof-of-work Altcha заполняет скрытое поле altcha с payload’ом в кодировке base64. Ваш бэкенд проверяет этот payload по вашему HMAC secret — внешний API-вызов не требуется.
Проверка на бэкенде — как это работает
Независимо от того, какую CAPTCHA вы используете, шаблон серверной проверки остаётся одинаковым:
- Извлеките токен из тела POST-запроса, используя имя поля, специфичное для каждого провайдера (g-recaptcha-response, cf-turnstile-response, procaptcha-response или altcha).
- Отправьте токен на endpoint проверки провайдера — это POST-запрос, который включает ваш secret key и токен пользователя (а для reCAPTCHA при необходимости ещё и IP-адрес пользователя).
- Разберите JSON-ответ — провайдеры возвращают индикатор успеха или ошибки. reCAPTCHA и Turnstile используют поле success: true/false; Prosopo использует verified: true/false; Altcha проверяется локально по вашему HMAC secret. Некоторые провайдеры также возвращают hostname и временную метку задания.
- Примите или отклоните отправку — если проверка не пройдена, верните пользователю ошибку и не обрабатывайте данные формы. Если всё прошло успешно, продолжайте обычную обработку.
Endpoint'ы проверки по провайдерам:
- reCAPTCHA v2: https://www.google.com/recaptcha/api/siteverify
- Cloudflare Turnstile: https://challenges.cloudflare.com/turnstile/v0/siteverify
- Prosopo: https://api.prosopo.io/siteverify
- Altcha: локально — проверяется по вашему собственному HMAC secret, внешний вызов не требуется
⚠️ Никогда не используйте site key для проверки на бэкенде — всегда используйте secret key. Путаница в этих ключах — одна из самых распространённых ошибок при интеграции.
Тестирование CAPTCHA HTML на локальном сервере
Для локального тестирования CAPTCHA требуется несколько дополнительных шагов, поскольку большинство провайдеров проверяют доменные имена.
- reCAPTCHA v2: добавьте localhost в список разрешённых доменов в консоли администратора Google reCAPTCHA. Виджет будет нормально отображаться и работать на http://localhost.
- Cloudflare Turnstile: используйте официальные тестовые site key от Cloudflare. Ключ 1x00000000000000000000AA всегда даёт успешный результат, а 2x00000000000000000000AB всегда даёт ошибку. Вы также можете использовать успешный site key (1x00000000000000000000AA) вместе с secret key 3x0000000000000000000000000000000AA на бэкенде, чтобы сымитировать ошибку "timeout-or-duplicate". Перед деплоем обязательно замените все тестовые ключи на реальные production-ключи.
- Prosopo Procaptcha: localhost поддерживается из коробки — дополнительная настройка не требуется.
- Altcha: поскольку решение развёртывается у вас, с localhost оно работает нативно. Просто убедитесь, что ваш endpoint тоже запущен локально.
Используйте DevTools → вкладку Network в браузере, чтобы убедиться, что API-скрипт CAPTCHA загружается (HTTP 200) и что POST-запрос формы содержит ожидаемое поле токена.
Устранение типичных проблем
Виджет CAPTCHA не отображается
- Ещё раз проверьте, что site key соответствует зарегистрированному типу CAPTCHA (ключи для checkbox не будут работать с invisible, и наоборот).
- Убедитесь, что тег API <script> присутствует и загружается без ошибки 404 или ошибки CORS в DevTools.
- Убедитесь, что домен, указанный при регистрации, совпадает с доменом, с которого вы отдаёте страницу, включая наличие или отсутствие www.
Токен отсутствует в POST-запросе формы
- Скрытое поле добавляется только после завершения проверки. Если пользователь отправит форму раньше, токен не будет передан.
- Для Invisible reCAPTCHA убедитесь, что колбэк onSubmit вызывает form.submit() после того, как токен стал доступен, а не раньше.
- Для Altcha проверьте, что ваш endpoint доступен и возвращает корректный challenge.
Проверка на бэкенде возвращает ошибку
- Убедитесь, что вы отправляете на endpoint проверки именно secret key, а не site key.
- Токены обычно одноразовые — если вы повторно отправляете один и тот же POST-запрос во время тестирования, каждый раз нужно генерировать новый токен.
- Проверьте рассинхронизацию времени: некоторые провайдеры (особенно Altcha) отклоняют слишком старые challenge.
Ошибка "Invalid domain" или несоответствие sitekey
- При работе с localhost убедитесь, что в списке разрешённых доменов указан именно localhost, а не 127.0.0.1.
- Для Turnstile во время локальной разработки переключитесь на тестовый site key.
Виджет скрыт или перекрывается другими элементами
- Виджеты CAPTCHA рендерятся в iframe с фиксированным z-index. Если у другого элемента (например, модального оверлея, липкого заголовка и т. п.) более высокий z-index, он может перекрывать виджет.
- Задайте явный z-index для родительского контейнера или проверьте, не обрезает ли iframe свойство overflow: hidden у родительских элементов.
Замечание по доступности для людей с ограниченными возможностями: все четыре провайдера из этого руководства предлагают доступные альтернативы. reCAPTCHA и Turnstile поддерживают аудиопроверки; Prosopo и Altcha по умолчанию спроектированы так, чтобы свести неудобство для пользователя к минимуму и максимально снизить зависимость от визуальных головоломок.
Автоматизация и тестирование CAPTCHA с CapMonster Cloud
Когда ваша CAPTCHA-интеграция уже запущена, вам может понадобиться программное тестирование — для QA-пайплайнов, интеграционных тестов или автоматизированного мониторинга. Решать CAPTCHA вручную при каждом запуске тестов в большом масштабе нереалистично.
CapMonster Cloud — это AI-сервис для автоматизированного решения CAPTCHA, который поддерживает все четыре типа CAPTCHA, рассмотренные в этом руководстве: reCAPTCHA v2 (checkbox и invisible), Cloudflare Turnstile, Prosopo Procaptcha и Altcha. Он работает через простой API: вы отправляете задачу с URL целевой страницы и site key, а сервис возвращает готовый токен, который можно подставить в вашу форму.
Как это вписывается в рабочий процесс разработчика:
- Автоматизированное интеграционное тестирование: запуск end-to-end тестов на формах, защищённых CAPTCHA, в CI/CD-пайплайнах без ручного участия.
- Проверка QA: убедиться, что ваш бэкенд корректно валидирует и отклоняет токены при разных условиях.
- Пайплайны сбора данных, где взаимодействие со страницами, защищёнными CAPTCHA, является частью авторизованного сценария.
CapMonster Cloud совместим с широко используемым API-интерфейсом, поэтому интегрируется со многими существующими фреймворками автоматизации с минимальной настройкой. Вы отправляете задачу, содержащую URL страницы и site key, опрашиваете API на предмет результата и получаете токен, который затем подставляете в форму как значение соответствующего скрытого поля.
Заключение
Интеграция CAPTCHA не требует сложной инфраструктуры — достаточно тега script, элемента виджета, правильной пары ключей CAPTCHA и серверной проверки токена. У каждого варианта из этого руководства есть свои сильные стороны: reCAPTCHA v2 — проверенное временем и широко используемое решение; Turnstile создаёт минимум неудобства для пользователя и лучше подходит с точки зрения приватности; Prosopo предлагает Web3-ориентированную альтернативу без зависимости от Google; а Altcha даёт полный контроль благодаря open-source инфраструктуре с самостоятельным хостингом.
Готовы начать? Выберите CAPTCHA, которая соответствует вашим требованиям к приватности, UX и инфраструктуре, зарегистрируйте свой site key и используйте примеры кода выше, чтобы встроить её в форму за считанные минуты. Если вам нужно автоматизировать тестирование или QA для защищённых форм, CapMonster Cloud поддерживает всех четырёх провайдеров и напрямую интегрируется в ваши существующие пайплайны.
