Widget installation methods Yandex SmartCaptcha
There are two methods to connect a SmartCaptcha widget:
- Automatic
- Advanced
Depending on the connection method, different widget parameter transmission methods are used.
Automatic connection method
In the automatic method, a JS script that loads the widget on the user page is added to the page by a link:
<script src="https://smartcaptcha.yandexcloud.net/captcha.js" defer></script>
After uploading, the JS script searches for all containers suitable for loading a widget into them, and draws widgets in them.
You can load the widget using the div
elements with the smart-captcha
class:
<div class="smart-captcha"></div>
Parameters for rendering the widget are set via container data attributes.
Example of a container with parameters for rendering a widget:
<div
class="smart-captcha"
data-sitekey="<client_part_key>"
data-hl="<language>"
></div>
Where:
Data attribute | Value | Default value |
---|---|---|
data-sitekey |
string |
None |
data-hl |
'ru' | 'en' | 'be' | 'kk' | 'tt' | 'uk' | 'uz' | 'tr' |
window.navigator.language |
data-callback |
string |
None |
Example of embedding the widget
<html>
<head>
<meta charset="UTF-8">
<title>Authentication form</title>
<script>
function callback(token) {
console.log(callback);
}
</script>
<script src="https://smartcaptcha.yandexcloud.net/captcha.js" async defer></script>
</head>
<body>
<p>Enter your username and password:</p>
<form id="auth_form" action="" method="POST">
<input id="csrf_token" name="csrf_token" type="hidden" />
<label for="username">Name</label>
<input id="username" type="text" name="user" />
<label for="userpass">Password</label>
<input id="userpass" type="password" name="password" />
<div
id="captcha-container"
class="smart-captcha"
data-sitekey="<client_part_key>"
data-hl="en"
data-callback="callback"
></div>
<input type="submit" value="Submit" />
</form>
</body>
</html>
Advanced connection method
In the advanced method, a JS script that loads the widget on the user page is added to the page by a link:
<script src="https://smartcaptcha.yandexcloud.net/captcha.js?render=onload&onload=onloadFunction"></script>
In the onload
parameter, a function is provided that contains parameters for rendering the widget. In this example, this is the onloadFunction
function.
After loading the JS script, an access to the window.smartCaptcha
object is shown along with methods for the widget.
Sample onloadFunction code
<div id="<container_ID>"></div>
<script>
function onloadFunction() {
if (window.smartCaptcha) {
const container = document.getElementById('<container_ID>');
const widgetId = window.smartCaptcha.render(container, {
sitekey: '<client_part_key>',
hl: '<language>',
});
}
}
</script>
window.smartCaptcha methods
render method
The render
method is used to draw the widget.
(
container: HTMLElement | string,
params: {
sitekey: string;
callback?: (token: string) => void;
hl?: 'ru' | 'en' | 'be' | 'kk' | 'tt' | 'uk' | 'uz' | 'tr';
test?: boolean;
webview?: boolean;
invisible?: boolean;
shieldPosition?: `top-left` | `center-left` | `bottom-left` | `top-right` | `center-right` | `bottom-right`;
hideShield?: boolean;
}
) => WidgetId;
Where:
container
: Container for the widget. You can transmit a DOM element or ID of the container.params
: Object with parameters for the CAPTCHA:sitekey
: Client-side key.callback
: Handler function.hl
: Widget language.test
: Running CAPTCHA in test mode. The user will always get a challenge. Use this property for debugging and testing only.webview
: Running CAPTCHA in WebView. You can use it to make user response validation more precise when adding CAPTCHA to mobile apps via WebView.invisible
: Invisible CAPTCHA.shieldPosition
: Position of the data processing notice section.hideShield
: Hide the data processing notice section.
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.
The method returns widgetId
, that is, a unique widget ID.
GetResponse method
The getResponse
method returns the current value of the user token.
(widgetId: WidgetId | undefined) => string;
widgetId
argument: Unique widget ID. If no argument is provided, the result of the first rendered widget is returned.
Execute method
The execute
method starts user validation. It is used to initiate the invisible CAPTCHA test at a certain event, e.g., when the user clicks the Submit button of an authentication form.
(widgetId: WidgetId | undefined) => void;
widgetId
argument: Unique widget ID. If the argument is not provided, the test will be run on the first rendered widget.
reset method
The reset
method resets the widget to the initial state.
(widgetId: WidgetId | undefined) => void;
widgetId
argument: Unique widget ID. If no argument has been passed, the first rendered widget is reset.
destroy method
The destroy
method deletes widgets and any listeners they create.
(widgetId: WidgetId | undefined) => void;
The widgetId
argument is a unique widget ID. If the argument is not passed, the first rendered widget will be deleted.
subscribe method
The subscribe
method enables you to subscribe listeners to certain widget events.
For instance, you can listen for the opening and closing of a challenge pop-up window. This may be useful for displaying the keyboard on mobile devices.
(widgetId: widgetId, event: SubscribeEvent, callback: Function) =>
UnsubscribeFunction;
Where:
-
widgetId
: Unique widget ID. -
event
: Event:type SubscribeEvent = | 'challenge-visible' | 'challenge-hidden' | 'network-error' | 'javascript-error' | 'success' | 'token-expired';
Event descriptions:
Event When it occurs Handler signature challenge-visible
Opening the challenge pop-up window () => void
challenge-hidden
Closing the challenge pop-up window () => void
network-error
A network error occurred () => void
javascript-error
A critical JS error occurred (error: { filename: string, message: string,
col: number, line: number }) => void
success
Successful user validation (token: string) => void
token-expired
Invalidated verification token () => void
-
callback
: Listener function:UnsubscribeFunction = () => void;
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.
Usage example:
<div id="container"></div>
<script
src="https://smartcaptcha.yandexcloud.net/captcha.js?render=onload&onload=onloadFunction"
async
defer
></script>
<script>
function onloadFunction() {
if (window.smartCaptcha) {
const container = document.getElementById('container');
const widgetId = window.smartCaptcha.render(container, {
/* params */
});
const unsubscribe = window.smartCaptcha.subscribe(
widgetId,
'challenge-visible',
() => console.log('challenge is visible')
);
}
}
</script>
Example of embedding the widget
<form>
<div id="captcha-container"></div>
<button id="smartcaptcha-demo-submit" disabled="1">Submit</button>
</form>
<script
src="https://smartcaptcha.yandexcloud.net/captcha.js?render=onload&onload=smartCaptchaInit"
defer
></script>
<script>
function callback(token) {
console.log(token);
if (token) {
document
.getElementById('smartcaptcha-demo-submit')
.removeAttribute('disabled');
} else {
document
.getElementById('smartcaptcha-demo-submit')
.setAttribute('disabled', '1');
}
}
function smartCaptchaInit() {
if (!window.smartCaptcha) {
return;
}
window.smartCaptcha.render('captcha-container', {
sitekey: '<client_part_key>',
callback: callback,
});
}
function smartCaptchaReset() {
if (!window.smartCaptcha) {
return;
}
window.smartCaptcha.reset();
}
function smartCaptchaGetResponse() {
if (!window.smartCaptcha) {
return;
}
var resp = window.smartCaptcha.getResponse();
console.log(resp);
alert(resp);
}
</script>