Как внедрить reCAPTCHA API: пошаговое руководство для разработчиков React

Понимание reCAPTCHA API и ключевых концепций

Понимание основных концепций и различных версий reCAPTCHA API обеспечивает прочную основу для интеграции. Google предоставляет эту технологию как важный уровень безопасности, помогающий сайтам отличать реальных пользователей от автоматизированных ботов.

Обзор Google reCAPTCHA v2 и v3

Google предлагает reCAPTCHA в двух основных версиях (v2 и v3), а также Enterprise-версию для расширенной защиты:

Каждая версия работает по-своему:

reCAPTCHA v2 требует от пользователей прямого взаимодействия через знакомый чекбокс «Я не робот». Система может показывать визуальные задачи, в которых пользователей просят распознать определённые объекты на изображениях, когда обнаруживается подозрительная активность.
reCAPTCHA v3 работает незаметно в фоновом режиме без какого-либо взаимодействия с пользователем. Вместо просьб решить задачу она отслеживает поведение пользователя и присваивает каждому взаимодействию оценку риска (risk score).

Обе версии требуют пару ключей — site key для frontend-реализации и secret key для backend-верификации.

Как reCAPTCHA защищает от ботов

reCAPTCHA действует как тест Тьюринга, чтобы отличить людей от автоматизированных систем. Система защиты использует следующие компоненты:

Risk Analysis Engine — сложная и адаптивная система анализирует поведение пользователей для выявления потенциально вредоносной активности.
Score-Based Detection — v3 присваивает оценки риска на основе паттернов поведения. Владельцы сайтов могут настраивать выбор действий по отношению к пользователю на основе этих оценок.
Global Intelligence — система использует данные Google по борьбе с мошенничеством, собранные из триллионов транзакций миллиардов пользователей на миллионах сайтов.

reCAPTCHA может предъявлять задачи или полностью блокировать взаимодействия, когда обнаруживает подозрительную активность. Это защищает сайты, минимизируя неудобства для реальных пользователей.

Выбор между reCAPTCHA v2 и v3

Выбор между v2 и v3 должен определяться вашими конкретными требованиями:

Выбирайте v2, когда:

Вам нужно явное подтверждение действий человека
На вашем сайте присутствуют явные точки взаимодействия (например, отправка форм)
Вы предпочитаете традиционные механизмы “challenge — response”

Выбирайте v3, когда:

Пользовательский опыт имеет первостепенное значение, и вы хотите лишний раз нервировать пользователей
Вам нужна точная оценка рисков для настройки политик безопасности
Ваш сайт имеет множество точек взаимодействия, требующих мониторинга

Ваши технические возможности внедрения и требования безопасности также должны играть ключевую роль в этом решении.

Настройка API-ключей reCAPTCHA и конфигурации

Чтобы приступить к настройке reCAPTCHA API, вам нужно получить учётные данные от Google. Далее мы пройдём через процесс регистрации вашего сайта и получения необходимых ключей.

Регистрация вашего сайта в консоли администратора Google reCAPTCHA

Вот как вы можете зарегистрировать свой сайт в консоли администратора Google reCAPTCHA:

Перейдите в консоль администратора Google reCAPTCHA
Войдите, используя учётные данные вашей учётной записи Google
Нажмите «+» или кнопку «Register a new site»
Присвойте имя метке для быстрой идентификации вашего сайта в консоли
Выберите подходящий тип reCAPTCHA (v2 или v3) в соответствии с вашими потребностями
Добавьте ваш домен (домены), где будет использоваться reCAPTCHA
Примите Условия использования (Terms of Service)
Нажмите «Submit» для завершения регистрации

Генерация site key и secret key

После регистрации Google сгенерирует два ключа:

Site Key: вы будете использовать его на frontend для отображения виджета reCAPTCHA
Secret Key: ваш сервер нуждается в нём для верификации ответов пользователей

Эти ключи работают в паре для защиты вашего сайта. Site key сообщает сервису reCAPTCHA Google, какой из ваших сайтов отправляет запрос, в то время как secret key позволяет вашему backend безопасно взаимодействовать с серверами Google для верификации ответов.

Безопасное хранение secret key

Ваш secret key является критически важным для запросов верификации. Вы никогда не должны помещать этот ключ в исходный код или показывать его в client-side коде.

Лучший способ хранить эти ключи — как переменные окружения в .env-файлах:

# .env file
GOOGLE_RECAPTCHA_KEY=your_site_key_here
GOOGLE_RECAPTCHA_SECRET=your_secret_key_here

Затем ваше приложение может получить доступ к этим переменным:

В Node.js: process.env.GOOGLE_RECAPTCHA_KEY
В PHP: $_ENV['GOOGLE_RECAPTCHA_KEY']

Убедитесь, что добавили ваши .env-файлы в .gitignore, чтобы случайно не закоммитить конфиденциальную информацию в ваш репозиторий.

Вы всегда можете вернуться в консоль администратора позже, чтобы изменить настройки, такие как домены или приоритеты безопасности.

Frontend-интеграция с reCAPTCHA v2 в React

Следующий важный шаг после получения API-ключей — интегрировать reCAPTCHA v2 в ваше React-приложение. Эта frontend-настройка позволяет вашему сайту эффективно отображать задачу верификации пользователям.

Установка react-google-recaptcha через npm

Вашему проекту нужен специализированный React-компонент для Google reCAPTCHA v2. Выполните эту команду в вашем терминале:

text

npm install --save react-google-recaptcha

Рендеринг компонента ReCAPTCHA с site key

Компонент нужно импортировать в файл вашей формы после установки:

import ReCAPTCHA from "react-google-recaptcha";
import { useRef } from "react";

function ContactForm() {
 const captchaRef = useRef(null);

 return (
   <form>
     {/* Поля формы */}
     <ReCAPTCHA
       sitekey={process.env.REACT_APP_SITE_KEY}
       ref={captchaRef}
     />
     <button type="submit">Submit</button>
   </form>
 );
}

Свойство sitekey связывает компонент с вашим ранее сгенерированным API-ключом.

Обработка токена с помощью onChange callback

reCAPTCHA создаёт токен ответа (response token), который вам нужно отправить на ваш backend при успешной верификации:

function onChange(value) {
 console.log("Captcha value:", value);
 // Сохранение токена или отправка формы
}

// Добавление в свойства компонента
<ReCAPTCHA
 sitekey={process.env.REACT_APP_SITE_KEY}
 onChange={onChange}
 ref={captchaRef}
/>

Токен нужно извлечь и сбросить во время отправки формы:

const handleSubmit = (e) => {
 e.preventDefault();
 const token = captchaRef.current.getValue();
 captchaRef.current.reset(); // Сброс после использования
 // Отправка токена в backend
}

Использование параметра 'hl' для локализации

Язык виджета можно настроить с помощью свойства hl для многоязычных сайтов:

<ReCAPTCHA
 sitekey={process.env.REACT_APP_SITE_KEY}
 onChange={onChange}
 hl="fr" // Выбор французского языка
/>

Backend-верификация с помощью Google reCAPTCHA API

Backend должен проверить подлинность токена reCAPTCHA после того, как frontend захватил его. Этот шаг верификации определяет, могут ли пользователи продолжить действия на сайте.

POST-запрос к https://www.google.com/recaptcha/api/siteverify

Ваш backend должен отправить POST-запрос к endpoint верификации Google для проверки токена. Запрос требует два основных параметра:

POST-параметры:

https://www.google.com/recaptcha/api/siteverify

secret: ваш secret key reCAPTCHA
response: токен, полученный с frontend
remoteip: (опционально) IP-адрес пользователя

Endpoint работает как с GET-, так и с POST-запросами, но POST обеспечивает лучшую безопасность.

Валидация токена с использованием secret key

Вы никогда не должны раскрывать свой secret key. Лучшая практика — хранить его в переменных окружения, а не в коде вашего приложения:

// Пример для Node.js

const verifyRecaptcha = async (token) => {
 const response = await fetch('https://www.google.com/recaptcha/api/siteverify', {
   method: 'POST',
   headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
   body: new URLSearchParams({
     secret: process.env.RECAPTCHA_SECRET,
     response: token
   }).toString()
 });
 return await response.json();
};

Использование URLSearchParams обеспечивает правильное URL-кодирование всех параметров, что предотвращает ошибки при обработке специальных символов в токене.

Обработка успешных и неудачных ответов

API возвращает JSON-объект, структура которого различается для v2 и v3.

Для reCAPTCHA v2:

success: булево значение, указывающее статус верификации
challenge_ts: временная метка верификации
hostname: сайт, на котором была решена reCAPTCHA
error-codes: массив сообщений об ошибках (если применимо)

Для reCAPTCHA v3 (дополнительно к полям v2):

score: значение от 0.0 до 1.0, указывающее на легитимность взаимодействия (где 1.0 означает высокую вероятность легитимного пользователя)
action: имя действия, указанное при генерации токена

Пример обработки ответа для v2:

const result = await verifyRecaptcha(token);
if (result.success) {
 // Продолжить обработку формы
} else {
 // Обработка ошибки проверки
 console.error('Verification failed:', result['error-codes']);
}

Пример обработки ответа для v3 с проверкой score:

const result = await verifyRecaptcha(token);
if (result.success && result.score > 0.5 && result.action === 'login') {
 // Продолжить обработку формы
} else if (result.success && result.score <= 0.5) {
 // Низкий балл - возможно, бот
 console.warn('Low score detected:', result.score);
} else {
 // Проверка не удалась
 console.error('Verification failed:', result['error-codes']);
}

Обработка кодов ошибок:

Массив error-codes может содержать следующие значения:

missing-input-secret: Параметр secret отсутствует
invalid-input-secret: Параметр secret недействителен или неправильный
missing-input-response: Параметр response (токен) отсутствует
invalid-input-response: Параметр response недействителен или истёк
bad-request: Запрос недействителен или неправильно сформирован
timeout-or-duplicate: Токен уже использован или истёк срок его действия

Пример полной обработки с error-codes:

const result = await verifyRecaptcha(token);
if (result.success) {
 // Успех — переходим к обработке формы
 return { verified: true };
} else {
 // Обработка конкретных кодов ошибок
 const errors = result['error-codes'] || [];
 if (errors.includes('timeout-or-duplicate')) {
   return { verified: false, message: 'Token expired. Please try again.' };
 } else if (errors.includes('invalid-input-response')) {
   return { verified: false, message: 'Invalid verification token.' };
 } else if (errors.includes('missing-input-secret') || errors.includes('invalid-input-secret')) {
   console.error('Server configuration error:', errors);
   return { verified: false, message: 'Server error. Please contact support.' };
 } else {
   return { verified: false, message: 'Verification failed. Please try again.' };
 }
}

Ограничения на истечение срока действия и одноразовое использование токена

Каждый токен reCAPTCHA действует две минуты и работает только один раз. Вы можете улучшить пользовательский опыт с помощью следующих стратегий обновления токена:

Создавайте новые токены прямо перед отправкой формы
Настройте автоматическое обновление токена для длинных форм
Показывайте дружественные сообщения об ошибках, когда токены истекают

Тестирование reCAPTCHA с помощью CapMonster Cloud

CapMonster Cloud предоставляет автоматизированное решение reCAPTCHA для тестирования, QA и сред разработки. Сервис решает reCAPTCHA v2, v3 и Enterprise версии программно через REST API, возвращая токены, которые ваше приложение принимает как токены реальных пользователей.

Это обеспечивает всестороннее тестирование защищенных форм, CI/CD пайплайнов и нагрузочное тестирование без ручного решения. Команды QA могут проверять реализации в различных сценариях и диапазонах оценок, в то время как разработчики тестируют логику верификации, обработку ошибок и поведение истечения токенов.

CapMonster Cloud интегрируется с помощью простых вызовов API, поддерживая популярные фреймворки, такие как Selenium, Puppeteer и Playwright. Он устраняет постоянные помехи от CAPTCHA во время разработки, проверяя вашу интеграцию с Google reCAPTCHA и ускоряя циклы разработки перед развертыванием в production.

Пример решения reCAPTCHA v3 с помощью Playwright и официальной библиотеки Node.js от CapMonster Cloud

▶ Показать код


const { chromium } = require('playwright');
const { 
  CapMonsterCloudClientFactory, 
  ClientOptions, 
  RecaptchaV3ProxylessRequest 
} = require('@zennolab_com/capmonstercloud-client');

(async () => {
  const TARGET_URL = 'https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta';
  const SITE_KEY = '6Le0xVgUAAAAAIt20XEB4rVhYOODgTl00d8juDob';
  const API_KEY = 'your_capmonster_cloud_api_key';

  const cmcClient = CapMonsterCloudClientFactory.Create(
    new ClientOptions({ clientKey: API_KEY })
  );

  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();
  await page.goto(TARGET_URL, { waitUntil: 'domcontentloaded' });

  const recaptchaRequest = new RecaptchaV3ProxylessRequest({
    websiteURL: TARGET_URL,
    websiteKey: SITE_KEY,
    minScore: 0.6,
    pageAction: 'myverify',
  });

  const solution = await cmcClient.Solve(recaptchaRequest);
  const token = solution.solution?.gRecaptchaResponse;

  if (!token) {
    console.error('Токен пустой, проверьте sitekey и URL');
    await browser.close();
    return;
  }

  console.log('Токен получен:', token);

  await page.evaluate((t) => {
    const input = document.querySelector('#v3_token');
    if (input) input.value = t;

    const form = document.querySelector('#v3_form');
    if (form) {
      form.submit();
      return;
    }

    if (typeof window.onSubmit === 'function') {
      window.onSubmit(t);
      return;
    }

    if (window.___grecaptcha_cfg) {
      const clients = window.___grecaptcha_cfg.clients;
      for (const clientKey in clients) {
        const client = clients[clientKey];
        for (const prop in client) {
          const cb = client[prop]?.callback;
          if (typeof cb === 'function') {
            cb(t);
            return;
          }
        }
      }
    }

    console.warn('Форма и callback не найдены');
  }, token);

  console.log('Токен вставлен и callback вызван (если доступен)');

  await page.waitForTimeout(5000);
  await browser.close();
})();

Также вы можете ознакомиться с подробными инструкциями по решению, интеграции и тестированию капч на нашем сайте:

reCAPTCHA v2
reCAPTCHA v3
reCAPTCHA Enterprise
и другими типами капч, поддерживаемыми нашим сервисом.

Заключение

Google reCAPTCHA API защищает ваши сайты от автоматизированных атак при минимальном влиянии на пользовательский опыт. Ключевые различия между reCAPTCHA v2 и v3 в большинстве реализаций заключаются в том, что V2 использует видимый пользователю виджет с чекбоксом, в то время как v3 незаметно присваивает оценки риска, не требуя взаимодействия с пользователем.

Ключевым моментом вашей реализации должно стать правильное хранение API-ключей. Практика показывает, что переменные окружения обеспечивают максимальную безопасность ваших secret key, что защищает целостность системы верификации. Эти ключи никогда не должны появляться в клиентском коде или репозиториях.

React-приложениям нужны специфические компоненты для интеграции reCAPTCHA, а токены reCAPTCHA имеют ограничения — они истекают через две минуты и работают только один раз. Поэтому для создания плавного пользовательского опыта стройте корректные стратегии управления токенами.

Теперь у вас есть всё необходимое для устойчивой интеграции reCAPTCHA в ваши React-приложения. Этот подход значительно сократит bot-трафик и автоматизированные злоупотребления на ваших сайтах, а легитимные пользователи смогут легко взаимодействовать с вашими приложениями.