Как подключить и использовать API reCAPTCHA v2
В 2026 году интеграция reCAPTCHA v2 по-прежнему остаётся одной из базовых задач для разработчиков, которые занимаются защитой сайта. У Google reCAPTCHA v2 есть два основных варианта: знакомый всем чекбокс «I'm not a robot» и невидимый режим, который срабатывает в фоне. Но суть в обоих случаях одна: на стороне клиента виджет создаёт одноразовый токен, а сервер проверяет его через API Google, и только после этого запрос можно считать надёжным.
В этом руководстве мы пройдём весь путь шаг за шагом: от регистрации сайта и встраивания HTML-виджета до серверной проверки токена и разбора типичных ошибок. Отдельно затронем и тему автоматизации — что делать, если reCAPTCHA v2 появляется в сценариях, где человек участвовать не может. А если хотите сначала посмотреть на тему шире, начните с нашей страницы о решении reCAPTCHA v2.
Мнение специалиста — Владлен Власов, эксперт в области разработки и веб-безопасности
«Детали интеграции reCAPTCHA v2 важны и в 2026 году, потому что эта капча до сих пор используется почти повсеместно. Ошибки на этапе серверной проверки — или её полное отсутствие — всё ещё остаются одной из самых частых проблем безопасности, которые я вижу на форумах для разработчиков. Установка клиентского виджета — это только половина работы».
Что такое reCAPTCHA v2 и как она работает?
reCAPTCHA v2 — это сервис Google, который помогает отличать живых пользователей от ботов. Работает он просто: сначала браузер показывает виджет и получает токен после действия пользователя, а затем сервер проверяет этот токен через API Google.
В версии с чекбоксом пользователь нажимает «Я не робот», а дальше Google уже в фоне оценивает риск. Если системе что-то кажется подозрительным, она показывает задание с картинками. Невидимая версия работает ещё проще: чекбокса нет, проверка запускается автоматически, обычно при отправке формы, и дополнительное задание появляется только при необходимости.
Понимать разницу между v2 и другими версиями важно ещё на этапе выбора интеграции. Подробный технический разбор есть в материале reCAPTCHA v2, v3 и Enterprise: ключевые различия.
Что нужно перед интеграцией reCAPTCHA v2
Перед тем как писать код, вам понадобятся две вещи от Google: Site Key и Secret Key.
Регистрация сайта
- Перейдите на google.com/recaptcha/admin/create и войдите в свой аккаунт Google.
- Укажите название сайта (Label) и выберите тип reCAPTCHA v2 — checkbox или invisible.
- Добавьте домен в поле Domains. Для локального тестирования укажите localhost.
- Выберите существующий проект Google Cloud Platform (GCP) или создайте новый. С начала 2026 года все ключи reCAPTCHA привязываются к проекту GCP.
- Примите Условия использвоания сервиса и нажмите Submit.
После этого Google покажет два ключа:
- Site Key — публичный ключ, который вы вставляете в HTML.
- Secret Key — приватный ключ, который должен использоваться только на сервере. В клиентский код его добавлять нельзя.
В продакшене вам понадобится HTTPS. На localhost во время разработки reCAPTCHA может работать и по HTTP, но для рабочего сайта нужно защищённое соединение и исходящий HTTPS-доступ к www.google.com для проверки токенов.
Как добавить reCAPTCHA v2 в HTML-форму
Подключение скрипта reCAPTCHA
Добавьте следующий тег скрипта в <head> страницы или прямо перед закрывающим тегом </body>:
<script src="https://www.google.com/recaptcha/api.js" async defer></script>Атрибуты async defer нужны для того, чтобы скрипт не тормозил загрузку страницы.
Размещение виджета с data-sitekey
Для обычного варианта с чекбоксом добавьте в форму div с классом g-recaptcha и вашим Site Key:
<form method="POST" action="/submit">
*<!-- поля вашей формы -->*
<div class="g-recaptcha" data-sitekey="YOUR_SITE_KEY"></div>
<button type="submit">Submit</button>
</form>Когда страница загрузится, скрипт Google сам превратит этот div в рабочий виджет. После успешного прохождения reCAPTCHA он заполнит скрытое поле g-recaptcha-response, и это поле уйдёт вместе с формой.
Настройка invisible-варианта
В невидимом варианте reCAPTCHA привязывается не к отдельному виджету, а сразу к кнопке отправки:
<form method="POST" action="/submit">
*<!-- поля вашей формы -->*
<button
class="g-recaptcha"
data-sitekey="YOUR_SITE_KEY"
data-callback="onSubmit"
data-action="submit"
type="submit">
Submit
</button>
</form>
<script>
function onSubmit(token) {
document.getElementById('your-form-id').submit();
}
</script>Функция data-callback получает токен и запускает уже реальную отправку формы. Если не добавить этот callback, форма после прохождения reCAPTCHA просто не отправится.
Серверная проверка через API siteverify
Встроить виджет — это только половина дела. Чтобы интеграция reCAPTCHA v2 действительно работала как защита, токен нужно обязательно проверять на сервере. Если сервер эту проверку не делает, от ботов такая CAPTCHA по сути не защищает.
Сценарий выглядит так: пользователь проходит проверку в виджете → Google возвращает в браузер токен g-recaptcha-response → этот токен вместе с формой уходит на ваш сервер → сервер отправляет через POST токен и ваш Secret Key на https://www.google.com/recaptcha/api/siteverify → Google возвращает JSON-ответ с результатом проверки.
POST-запрос к siteverify
Эндпоинт проверки принимает POST-запрос с двумя обязательными параметрами:
| Параметр | Описание |
| secret | Ваш Secret Key |
| response | Токен g-recaptcha-response, который пришёл с клиента |
| remoteip (необязательно) | IP-адрес пользователя |
Разбор JSON-ответа и обработка ошибок
Если проверка прошла успешно, ответ будет таким:
{
"success": true,
"challenge_ts": "2026-06-17T10:00:00Z",
"hostname": "yourdomain.com",
"error-codes": []
}Если проверка не прошла, вы получите "success": false и один или несколько кодов ошибок:
| Код ошибки | Что это значит |
| missing-input-secret | Параметр Secret Key не был передан |
| invalid-input-secret | Secret Key неверный или передан в неправильном формате |
| missing-input-response | Клиент не отправил токен |
| invalid-input-response | Токен недействителен или имеет неправильный формат |
| timeout-or-duplicate | Токен истёк или уже был использован раньше |
Перед дальнейшей обработкой всегда проверяйте, что success === true. Ориентироваться только на отсутствие кодов ошибок — плохая идея.
Пример серверной проверки на PHP
Ниже — полный пример серверной проверки. Просто замените $YOUR_SECRET_KEY на ваш реальный Secret Key.
<?php
declare(strict_types=1);
function verifyRecaptchaV2(
string $token,
string $YOUR_SECRET_KEY,
?string $remoteIp = null
): array {
if ($token === "") {
return [
"ok" => false,
"message" => "reCAPTCHA token was not received.",
"data" => null,
];
}
$postFields = [
"secret" => $YOUR_SECRET_KEY,
"response" => $token,
];
if ($remoteIp !== null && $remoteIp !== "") {
$postFields["remoteip"] = $remoteIp;
}
$ch = curl_init("https://www.google.com/recaptcha/api/siteverify");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query($postFields),
CURLOPT_TIMEOUT => 10,
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_SSL_VERIFYPEER => true,
CURLOPT_SSL_VERIFYHOST => 2,
]);
$responseBody = curl_exec($ch);
$curlError = curl_error($ch);
$httpCode = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($responseBody === false || $curlError !== "") {
return [
"ok" => false,
"message" => "Failed to send a request to Google reCAPTCHA.",
"data" => null,
];
}
if ($httpCode < 200 || $httpCode >= 300) {
return [
"ok" => false,
"message" => "Google reCAPTCHA returned an unexpected HTTP status.",
"data" => null,
];
}
$data = json_decode($responseBody, true);
if (!is_array($data)) {
return [
"ok" => false,
"message" => "Failed to parse the Google reCAPTCHA response.",
"data" => null,
];
}
if (!empty($data["success"])) {
return [
"ok" => true,
"message" => "reCAPTCHA verification passed successfully.",
"data" => $data,
];
}
$errors =
isset($data["error-codes"]) && is_array($data["error-codes"])
? implode(", ", $data["error-codes"])
: "unknown_error";
return [
"ok" => false,
"message" => "reCAPTCHA verification failed: " . $errors,
"data" => $data,
];
}Использование reCAPTCHA v2 в JavaScript
После интеграции вы можете работать с виджетом напрямую через JavaScript API. Ниже — основные методы и callbacks, которые пригодятся на практике.
| Метод / Callback | Назначение |
| grecaptcha.render() | Вручную отрисовать виджет в нужном контейнере |
| grecaptcha.getResponse() | Получить текущий токен ответа (если CAPTCHA ещё не пройдена, вернётся пустая строка) |
| grecaptcha.reset() | Сбросить текущую проверку, чтобы пользователь мог пройти её заново |
| callback | Срабатывает после успешного прохождения проверки и получает токен |
| expired-callback | Срабатывает, если токен истёк до отправки формы |
Практические примеры на JavaScript
Получить сгенерированный токен:
const token = grecaptcha.getResponse();Сбросить виджет после неудачного запроса:
grecaptcha.reset();Динамически отрисовать виджет (это особенно удобно в SPA или когда контейнер появляется в DOM уже после загрузки страницы):
function onSolved(token) {
document.querySelector('textarea[name="g-recaptcha-response"]').value = token;
document.getElementById('contact-form').submit();
}
grecaptcha.render('captcha-container', {
sitekey: 'YOUR_SITE_KEY',
callback: onSolved,
'expired-callback': () => grecaptcha.reset(),
});Проверить, прошёл ли пользователь CAPTCHA, перед отправкой:
if (!grecaptcha.getResponse()) {
alert('Complete the CAPTCHA first.');
return;
}Про expired-callback легко забыть: если пользователь прошёл CAPTCHA, но слишком долго не отправлял форму, токен незаметно истечёт. В итоге форма уйдёт с недействительным токеном, а сервер вернёт ошибку timeout-or-duplicate.
Распространённые ошибки интеграции и способы их исправить
Даже у простой интеграции reCAPTCHA v2 есть типовые точки, где всё может сломаться.
| Проблема | Вероятная причина | Что делать |
| Виджет не отображается | Нет тега скрипта или его блокирует CSP | Добавьте https://www.google.com в CSP-директивы script-src и frame-src |
| invalid-input-secret при проверке | Secret Key неверный или относится к другому проекту | Проверьте Admin Console и убедитесь, что используете нужный Secret Key |
| timeout-or-duplicate | Токен старше ~2 минут или был отправлен повторно | Попросите пользователя пройти CAPTCHA заново и не используйте один токен дважды |
| invalid-input-response | Токен не дошёл до сервера | Логируйте req.body['g-recaptcha-response'], чтобы проверить, попадает ли он в обработчик |
| Ошибка несоответствия домена в консоли | Домен не добавлен в Admin Console | Укажите точный домен в настройках reCAPTCHA Admin Console |
| Виджет ломается при смене маршрута в SPA | После изменения DOM виджет не был отрисован заново | Повторно вызовите grecaptcha.render() или сделайте сброс через grecaptcha.reset() |
| missing-input-response в AJAX-формах | Поле с токеном не добавлено в AJAX-запрос | Получите токен через grecaptcha.getResponse() и добавьте его в тело запроса fetch или XHR |
И важный момент: отсутствие токена никогда нельзя считать успешной проверкой. Если g-recaptcha-response нет, запрос нужно сразу отклонять.
reCAPTCHA v2 в автоматизации: решение капч через API
Вы добавили reCAPTCHA v2 на сайт — теперь логично проверить, как она ведёт себя в реальных сценариях. И если не хочется решать CAPTCHA вручную при каждом тесте, можно передать публичные параметры reCAPTCHA в CapMonster Cloud, получить валидный токен и использовать его в своей интеграции.
API CapMonster Cloud для решения reCAPTCHA v2 работает по простой схеме из четырёх шагов:
- Отправьте задачу с URL нужной страницы и sitekey.
- Опросите API и дождитесь результата.
- Подставьте полученный токен в g-recaptcha-response.
- Отправьте форму, пока токен не истёк.
CapMonster Cloud предлагает API для решения reCAPTCHA v2, построенный именно по такой схеме возврата токена. Практический разбор смотрите в материале Как обойти reCAPTCHA v2 в 2026 году: рабочие методы.
Ключевая мысль — Владлен Власов, эксперт в области разработки и веб-безопасности
«Разработчик, который внедряет reCAPTCHA на сайт, и инженер по автоматизации, который сталкивается с ней в пайплайне, по сути решают зеркальные задачи. Когда понимаешь обе стороны, работать становится проще: более строгую серверную интеграцию труднее обойти, а грамотно выстроенный Solver API работает надёжнее, когда токены истекают или страница меняется».
Часто задаваемые вопросы
Заключение
Чтобы интеграция API reCAPTCHA v2 действительно работала как надо, нужны две вещи: корректно подключённый виджет на клиенте и обязательная серверная проверка через siteverify, которая реально решает, пускать запрос дальше или нет. Для большинства проектов самым понятным и безопасным стартом остаётся версия с чекбоксом — её проще внедрить, проверить и она обычно не вызывает вопросов у пользователей. Невидимый вариант стоит выбирать тогда, когда снижение неудобства для пользователя действительно важно, а логика с callback у вас настроена без сбоев. Если же в ваших сценариях автоматизации нужно работать с reCAPTCHA v2 программно, схема с использованием сервисов решения reCAPTCHA v2 вполне понятна — главное помнить, что токен живёт недолго, поэтому получать и отправлять его нужно без задержек.
Автоматизируйте обход reCAPTCHA v2 в своих процессах
Если reCAPTCHA v2 регулярно встречается в ваших сценариях автоматизации, вручную решать её каждый раз быстро становится неудобно и просто неэффективно. CapMonster Cloud предлагает API для решения reCAPTCHA v2, которое работает по той же логике, что и описанная в этом руководстве интеграция: передаёте sitekey и URL страницы — получаете готовый токен, который можно сразу использовать.
- Подходит и для браузерной автоматизации, и для прямых HTTP-сценариев
- Использует простую и понятную схему: создание задачи и получение результата
- Хорошо вписывается в процессы автоматизации, связанные с reCAPTCHA
Посмотреть, как это работает на практике, можно на странице обзора reCAPTCHA v2.
