Connecting a CAPTCHA in React
To connect SmartCaptcha in React, you can use the @yandex/smart-captcha npm package.
Install the package
In your project, run:
npm i -PE @yandex/smart-captcha
yarn add @yandex/smart-captcha
pnpm add @yandex/smart-captcha
Package contents
The package provides two components to work with SmartCaptcha:
| Component | Description |
|---|---|
SmartCaptcha |
Website user validation component with the "I’m not a robot" button (standard CAPTCHA). |
InvisibleSmartCaptcha |
Website user validation component without the "I’m not a robot" button (invisible CAPTCHA). |
SmartCaptcha component
Available properties:
|
Property |
Type |
Description |
|
|
|
Client key. |
|
|
|
Show the challenge to the user. |
|
|
|
Widget language. |
|
|
|
Running CAPTCHA in the test mode. The user will always get a challenge. Use this property for debugging and testing only. |
|
|
|
Running CAPTCHA in WebView. You can use it to make the user response validation more precise when adding CAPTCHA to mobile apps via WebView. |
|
|
|
Position of the shield with the data processing notice. |
|
|
|
Hide the shield with the data processing notice. |
|
|
|
The method is invoked when a pop-up window with a challenge appears. |
|
|
|
The method is invoked when a pop-up window with a challenge closes. |
|
|
|
The method is invoked when a network error occurs. |
|
|
|
The method is invoked when a critical JavaScript error occurs. |
|
|
|
The method is invoked when the user passes the challenge. The handler gets a unique user token as an argument. |
|
|
|
The method is invoked when the token obtained by the user after passing the challenge becomes invalid. |
SmartCaptcha usage example:
import { SmartCaptcha } from '@yandex/smart-captcha';
export const ComponentWithCaptcha = () => {
const [token, setToken] = useState('');
return <SmartCaptcha sitekey="<client_key>" onSuccess={setToken} />;
};
InvisibleSmartCaptcha component
Available properties:
|
Property |
Type |
Description |
|
|
|
Client key. |
|
|
|
Show the challenge to the user. |
|
|
|
Widget language. |
|
|
|
Running CAPTCHA in the test mode. The user will always get a challenge. Use this property for debugging and testing only. |
|
|
|
Running CAPTCHA in WebView. You can use it to make the user response validation more precise when adding CAPTCHA to mobile apps via WebView. |
|
|
|
Position of the shield with the data processing notice. |
|
|
|
Hide the shield with the data processing notice. |
|
|
|
The method is invoked when a pop-up window with a challenge appears. |
|
|
|
The method is invoked when a pop-up window with a challenge closes. |
|
|
|
The method is invoked when a network error occurs. |
|
|
|
The method is invoked when a critical JavaScript error occurs. |
|
|
|
The method is invoked when the user passes the challenge. The handler gets a unique user token as an argument. |
|
|
|
The method is invoked when the token obtained by the user after passing the challenge becomes invalid. |
Warning
You must notify users that their data is processed by SmartCaptcha. If you hide the notice shield, find another way to tell users that SmartCaptcha processes their data.
InvisibleSmartCaptcha usage example:
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="<client_key>"
onSuccess={setToken}
onChallengeHidden={handleChallengeHidden}
visible={visible}
/>
</>
);
};
Subscriptions to events
Both components provide methods for subscribing to events in the widget:
onChallengeVisibleonChallengeHiddenonNetworkErroronJavascriptErroronSuccessonTokenExpired
You can use these methods, for example, to invoke a function when a challenge is shown to the user.
Example of a subscription to events:
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="<client_key>"
onChallengeVisible={handleChallengeVisible}
onChallengeHidden={handleChallengeHidden}
onNetworkError={handleNetworkError}
onJavascriptError={handleJavaScriptError}
onSuccess={handleSuccess}
onTokenExpired={handleTokenExpired}
/>
</>
);
};
Warning
javascript-error indicates a critical failure in the JavaScript operation. Notify the user about this issue through the application interface. When such an error occurs, you cannot consider the job successfully completed, as it could potentially create a vulnerability in your application.
Resetting a SmartCaptcha state
A CAPTCHA retains its state after a user is validated. To enable a user to pass validation again, configure a state reset. If this is not done, a repeat request will be sent to the server with the same one-time token as the first time.
State reset configuration example:
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="<client_key>"
\>
<div\>
);
}