reCAPTCHA v3 API: пошаговое руководство
Интеграция reCAPTCHA v3 включает три последовательных этапа: регистрацию ключей, подключение recaptcha v3 javascript на frontend и проверку токена на backend. Ниже приведен полный процесс.
Шаг 1 — зарегистрируйте свои ключи в Google reCAPTCHA Admin Console
Прежде чем написать хотя бы одну строку кода, вам потребуются учетные данные.
- Перейдите в Google reCAPTCHA Admin Console.
- Заполните поле Label name и выберите reCAPTCHA v3.
- Добавьте все домены, на которых работает ваш сайт (например, example.com, www.example.com).
- Выберите свой проект Google Cloud Platform, если он уже существует. Если нет, он будет создан автоматически.
- Отправьте форму. Google предоставит два ключа:
- Site key — публичный; используется в вашем frontend HTML/JS.
- Secret key — приватный; используется только на вашем backend-сервере. Никогда не раскрывайте его в клиентском коде.
Шаг 2 — загрузите библиотеку JavaScript reCAPTCHA v3
На каждой странице, которую вы хотите защитить, загрузите скрипт recaptcha v3 api, добавив следующий тег в <head> вашего HTML и заменив YOUR_SITE_KEY на ваш реальный ключ:
<script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>
Этот единственный фрагмент инициализирует механизм recaptcha v3 google и начинает пассивно собирать поведенческие сигналы в фоновом режиме — никакой виджет пользователю не показывается.
Шаг 3 — интегрируйте reCAPTCHA в защищаемое действие
В отличие от recaptcha v2, вы не рендерите виджет. Вместо этого вы программно вызываете grecaptcha.execute() в тот момент, когда пользователь инициирует защищенное действие.
Вариант A — кнопка с data-атрибутами (простые формы):
<form id="login-form">
<!-- ваши поля формы -->
<button
class="g-recaptcha"
data-sitekey="YOUR_SITE_KEY"
data-callback="onSubmit"
data-action="login"
type="button">
Войти
</button>
</form>
<script>
function onSubmit(token) {
fetch("/api/login", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ recaptchaToken: token })
});
}
</script>
Вариант B — программный вызов (рекомендуется для AJAX/API-сценариев):
<script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>
<script>
async function submitLogin() {
const token = await new Promise((resolve) => {
grecaptcha.ready(() => {
grecaptcha.execute("YOUR_SITE_KEY", { action: "login" }).then(resolve);
});
});
// Немедленно отправьте токен -- срок его действия истекает через 2 минуты
await fetch("/api/login", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ recaptchaToken: token })
});
}
</script>
Ключевое правило: имя action (например, login, signup, checkout) должно совпадать с тем, что ожидает ваш backend. Это предотвращает повторное использование токенов между разными endpoint.
Шаг 4 — проверьте токен на вашем backend
Ваш сервер получает токен и перенаправляет его на endpoint Google siteverify до обработки пользовательского запроса.
Пример для Node.js (с обработкой ошибок):
import express from "express";
const app = express();
app.use(express.json());
app.post("/api/login", async (req, res) => {
const token = req.body.recaptchaToken;
const params = new URLSearchParams();
params.set("secret", process.env.RECAPTCHA_SECRET);
params.set("response", token);
let data;
try {
const verifyResp = await fetch("https://www.google.com/recaptcha/api/siteverify", {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: params
});
data = await verifyResp.json();
} catch (err) {
console.error("reCAPTCHA verification network error:", err);
return res.status(503).json({ error: "verification_unavailable" });
}
// → переходите к шагу 5
});
Примечание: нативный fetch доступен в Node.js 18+. Для более старых версий используйте node-fetch или axios.
Пример для Python (Flask ≥ 2.0):
import os, requests
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.post("/api/signup") # Требуется Flask >= 2.0
def signup():
token = request.json.get("recaptchaToken")
resp = requests.post(
"https://www.google.com/recaptcha/api/siteverify",
data={"secret": os.environ["RECAPTCHA_SECRET"], "response": token},
timeout=5
)
data = resp.json()
# → переходите к шагу 5
if not data.get("success"):
return jsonify({"error": "recaptcha_failed"}), 403
return jsonify({"ok": True})
Шаг 5 — интерпретируйте оценку и принимайте решение
Endpoint Google siteverify возвращает JSON-ответ. Вот как выглядит успешный ответ:
{
"success": true,
"score": 0.7,
"action": "login",
"challenge_ts": "2026-02-27T10:00:00Z",
"hostname": "example.com"
}
Ваш backend должен по порядку проверить три вещи:
- success имеет значение true— токен валиден и принят Google.
- action совпадает с ожидаемым значением — это подтверждает, что токен был сгенерирован для правильного контекста.
- score достигает вашего порогового значения — 0.5 это рекомендованная Google отправная точка.
Шаг 6 — корректно обрабатывайте ошибки
Ответ siteverify может содержать массив error-codes. Наиболее важные коды, которые нужно обрабатывать:
- timeout-or-duplicate — токен старше 2 минут или уже был использован; повторно вызовите grecaptcha.execute() на стороне клиента, чтобы получить новый токен.
- missing-input-secret / invalid-input-secret — ваш secret key отсутствует или неверен; это ошибка конфигурации, а не ошибка пользователя.
- missing-input-response / invalid-input-response — токен не был отправлен или имеет некорректный формат; проверьте интеграцию на frontend.
- bad-request — сам запрос к siteverify сформирован некорректно.
Никогда не показывайте конечным пользователям сырые коды ошибок — записывайте их в журнал на стороне сервера и выводите общее сообщение «пожалуйста, попробуйте еще раз».
Шаг 7 — тщательно протестируйте интеграцию
Перед выходом в production проверьте весь процесс:
- Откройте защищенную страницу, инициируйте действие и убедитесь, что в браузере генерируется токен.
- Запишите в журнал сырой ответ siteverify на backend, чтобы убедиться в наличии success: true, корректного score и правильного action.
- Для автоматизированного тестирования вы можете использовать CapMonster Cloud, который предоставляет API для решения CAPTCHA, который программно генерирует валидные токены reCAPTCHA v3. Он поддерживает reCAPTCHA v3, v2 и Enterprise и интегрируется через REST API.
- Убедитесь, что ваши сценарии обработки ошибок работают, отправив просроченный или некорректно сформированный токен и проверив, что backend возвращает правильный ответ.
Вопросы конфиденциальности и соответствия требованиям
Поведенческая модель профилирования reCAPTCHA version 3 связана с существенными последствиями для конфиденциальности. Система собирает движения мыши, тайминги нажатия клавиш, отпечатки браузера, IP-адреса и многое другое — данные, которые выходят далеко за рамки строго необходимого для подтверждения того, что перед вами человек.
Для европейских операторов в частности это создает риски с точки зрения GDPR. В рамках заметной правоприменительной меры 2023 года французский орган по защите данных (CNIL) оштрафовал компанию по аренде электроскутеров Cityscoot на €125,000 за множественные нарушения GDPR — включая как сбор избыточных геолокационных данных (отслеживание скутеров каждые 30 секунд), так и использование Google reCAPTCHA без надлежащего согласия пользователя. CNIL постановил, что доступ reCAPTCHA к данным пользовательского устройства требует предварительного согласия в соответствии со статьей 82 французского Закона о защите данных, а не рассматривается просто как пассивный виджет безопасности. Если вы работаете в рамках GDPR, перед развертыванием google recaptcha v3 необходимо заключить надлежащее соглашение об обработке данных с Google и получить соответствующее согласие пользователей.
CapMonster Cloud и reCAPTCHA v3
CapMonster Cloud — это сервис распознавания и автоматизации решения CAPTCHA на базе ИИ, который поддерживает reCAPTCHA v2, v3 и Enterprise, а также многие другие типы CAPTCHA. Для команд разработки и тестирования он предоставляет способ автоматизировать взаимодействие с формами, защищенными reCAPTCHA, без ручного вмешательства — это полезно для интеграционного тестирования, автоматизированных конвейеров мониторинга или легитимных сценариев скрейпинга, где обработка CAPTCHA становится узким местом.
В контексте использования recaptcha v3 CapMonster Cloud выступает как API для решения CAPTCHA: получив целевой URL и site key, он возвращает валидный токен reCAPTCHA, который можно отправить на защищенный endpoint так же, как это сделал бы реальный браузер.
Пример решения reCAPTCHA v3 с использованием CapMonster Cloud:
Создание задачи:
POST
https://api.capmonster.cloud/createTask
Запрос
{
"clientKey": "API_KEY",
"task": {
"type": "RecaptchaV3TaskProxyless",
"websiteURL": "https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta",
"websiteKey": "6Le0xVgUAAAAAIt20XEB4rVhYOODgTl00d8juDob",
"isEnterprise": false,
"minScore": 0.7,
"pageAction": "myverify"
}
}
Ответ
{
"errorId":0,
"taskId":407533072
}
Получение результата задачи:
POST
https://api.capmonster.cloud/getTaskResult
Запрос
{
"clientKey":"API_KEY",
"taskId": 407533072
}
Ответ
{
"errorId":0,
"status":"ready",
"solution": {
"gRecaptchaResponse":"3AHJ_VuvYIBNBW5yyv0zRYJ75VkOKvhKj9_xGBJKnQimF72rfoq3Iy-DyGHMwLAo6a3"
}
}
Подробную документацию по API и примеры интеграции смотрите на сайте capmonster.cloud.
Заключение
reCAPTCHA v3 представляет собой значимый шаг вперед в поиске баланса между защитой от ботов и пользовательским опытом. Полностью перенося верификацию в фоновый режим и заменяя бинарную логику pass/fail на более гибкую оценку риска, recaptcha google v3 позволяет командам безопасности действовать пропорционально — блокировать явных ботов, усиливать проверку для подозрительных сессий и совсем не беспокоить легитимных пользователей.
Компромиссы также присутствуют: интерпретация оценок требует вложений в backend, настройка порогов занимает время, а влияние на конфиденциальность в контексте GDPR нельзя считать незначительным. Но для большинства production-веб-приложений — особенно тех, где неудобство для пользователя при входе, регистрации или оформлении заказа снижает конверсию, — переход с v2 вполне оправдан.
Готовы внедрить reCAPTCHA v3 на своем сайте — или автоматизировать вокруг нее свой конвейер тестирования? Посетите CapMonster Cloud, чтобы изучить возможности ИИ-решения для reCAPTCHA v3, v2 и Enterprise — с подробной документацией API и примерами интеграции, которые помогут вам быстро реализовать ваши задачи.
