Подключение капчи в React
Для подключения SmartCaptcha в React можно использовать npm-пакет @yandex/smart-captcha.
Установка пакета
Выполните внутри вашего проекта:
npm i -PE @yandex/smart-captcha
yarn add @yandex/smart-captcha
pnpm add @yandex/smart-captcha
Состав пакета
Пакет предоставляет два компонента для работы со SmartCaptcha:
| Компонент | Описание |
|---|---|
SmartCaptcha |
Компонент для валидации пользователя на сайтах с кнопкой Я не робот (обычная капча). |
InvisibleSmartCaptcha |
Компонент для валидации пользователя на сайтах без кнопки Я не робот (невидимая капча). |
Компонент SmartCaptcha
Список доступных свойств:
|
Свойство |
Тип |
Описание |
|
|
|
Ключ клиента. |
|
|
|
Показывать задание пользователю. |
|
|
|
Язык виджета. |
|
|
|
Запуск капчи в тестовом режиме. Пользователь всегда будет получать задание. Используйте это свойство только для отладки и тестирования. |
|
|
|
Запуск капчи в WebView. Используется для повышения точности оценки пользователей при добавлении капчи в мобильные приложения с помощью WebView. |
|
|
|
Расположение блока с уведомлением об обработке данных. |
|
|
|
Скрыть блок с уведомлением об обработке данных. |
|
|
|
Метод вызывается, когда появляется всплывающее окно с заданием. |
|
|
|
Метод вызывается, когда закрывается всплывающее окно с заданием. |
|
|
|
Метод вызывается, когда происходит ошибка сети. |
|
|
|
Метод вызывается, когда происходит критическая ошибка в работе JavaScript. |
|
|
|
Метод вызывается, когда пользователь успешно прошел проверку. В качестве аргумента обработчик получает уникальный токен пользователя. |
|
|
|
Метод вызывается, когда токен, полученный пользователем после прохождения проверки, становится невалидным. |
Пример использования SmartCaptcha:
import { SmartCaptcha } from '@yandex/smart-captcha';
export const ComponentWithCaptcha = () => {
const [token, setToken] = useState('');
return <SmartCaptcha sitekey="<ключ_клиента>" onSuccess={setToken} />;
};
Компонент InvisibleSmartCaptcha
Список доступных свойств:
|
Свойство |
Тип |
Описание |
|
|
|
Ключ клиента. |
|
|
|
Показывать задание пользователю. |
|
|
|
Язык виджета. |
|
|
|
Запуск капчи в тестовом режиме. Пользователь всегда будет получать задание. Используйте это свойство только для отладки и тестирования. |
|
|
|
Запуск капчи в WebView. Используется для повышения точности оценки пользователей при добавлении капчи в мобильные приложения с помощью WebView. |
|
|
|
Расположение блока с уведомлением об обработке данных. |
|
|
|
Скрыть блок с уведомлением об обработке данных. |
|
|
|
Метод вызывается, когда появляется всплывающее окно с заданием. |
|
|
|
Метод вызывается, когда закрывается всплывающее окно с заданием. |
|
|
|
Метод вызывается, когда происходит ошибка сети. |
|
|
|
Метод вызывается, когда происходит критическая ошибка в работе JavaScript. |
|
|
|
Метод вызывается, когда пользователь успешно прошел проверку. В качестве аргумента обработчик получает уникальный токен пользователя. |
|
|
|
Метод вызывается, когда токен, полученный пользователем после прохождения проверки, становится невалидным. |
Важно
Вы обязаны уведомлять пользователей о том, что их данные обрабатывает SmartCaptcha. Если вы скрываете блок с уведомлением, сообщите пользователям иным способом о том, что SmartCaptcha обрабатывает их данные.
Пример использования InvisibleSmartCaptcha:
import { InvisibleSmartCaptcha } from '@yandex/smart-captcha';
export const InvisibleCaptcha = () => {
const [token, setToken] = useState('');
const [visible, setVisible] = useState(false);
const handleChallengeHidden = useCallback(() => setVisible(false), []);
const handleButtonClick = () => setVisible(true);
return (
<>
<button onClick={handleButtonClick}>Validate</button>
<InvisibleSmartCaptcha
sitekey="<ключ_клиента>"
onSuccess={setToken}
onChallengeHidden={handleChallengeHidden}
visible={visible}
/>
</>
);
};
Подписки на события
Оба компонента предоставляют методы для подписки на события в виджете:
onChallengeVisibleonChallengeHiddenonNetworkErroronJavaScriptErroronSuccessonTokenExpired
Эти методы можно использовать, например, чтобы вызвать функцию, когда пользователю показалось задание.
Пример подписки на события:
import { SmartCaptcha, SmartCaptchaProps } from '@yandex/smart-captcha';
export const SubscriptionToCaptcha = () => {
const [token, setToken] = useState('');
const [status, setStatus] = useState('hidden');
const handleChallengeVisible = useCallback(() => setStatus('visible'), []);
const handleChallengeHidden = useCallback(() => setStatus('hidden'), []);
const handleSuccess = useCallback((token: string) => {
setStatus('success');
setToken(token);
}, []);
const handleTokenExpired = useCallback(() => {
setStatus('token-expired');
setToken('');
}, []);
const handleNetworkError: SmartCaptchaProps['onNetworkError'] = useCallback(() => setStatus('network-error'), []);
const handleJavaScriptError: SmartCaptchaProps['onJavaScriptError'] = useCallback((error) => {
setStatus('javascript-error');
logError(error);
}, []);
return (
<>
Status: {status}
<SmartCaptcha
sitekey="<ключ_клиента>"
onChallengeVisible={handleChallengeVisible}
onChallengeHidden={handleChallengeHidden}
onNetworkError={handleNetworkError}
onJavaScriptError={handleJavaScriptError}
onSuccess={handleSuccess}
onTokenExpired={handleTokenExpired}
/>
</>
);
};
Важно
Ошибка javascript-error указывает на критический сбой в работе JavaScript. Сообщите об этой проблеме пользователю в интерфейсе приложения. При возникновении такой ошибки засчитывать успешное выполнение задания нельзя — это может создать потенциальную уязвимость вашего приложения.
Сброс состояния SmartCaptcha
Капча сохраняет свое состояние после прохождения валидации. Чтобы пользователь мог пройти проверку еще раз, настройте сброс состояния. Если этого не сделать, повторный запрос к серверу будет отправлен с тем же одноразовым токеном, что и в первый раз.
Пример настройки сброса состояния:
import { SmartCaptcha } from "@yandex/smart-captcha";
import { useState } from "react";
export default function App() {
const [resetCaptcha, setResetCaptcha] = useState(0);
/* Update the state */
const handleReset = () => setResetCaptcha((prev) => prev + 1);
return (
<div className="App">
<SmartCaptcha
key={resetCaptcha}
sitekey="<ключ_клиента>"
\>
<div\>
);
}