Методы установки виджета Yandex SmartCaptcha
Подключить виджет SmartCaptcha можно одним из двух методов:
- Автоматический.
- Расширенный.
В зависимости от метода подключения отличается способ передачи параметров для виджета.
Автоматический метод подключения
В автоматическом методе JS-скрипт, который выполняет загрузку виджета на странице пользователя, добавляется на страницу по ссылке:
<script src="https://captcha-api.yandex.ru/captcha.js" defer></script>
После загрузки JS-скрипт ищет все контейнеры, которые подходят для загрузки в них виджета, и отрисовывает в них виджеты.
Для загрузки виджета подходят элементы div
с классом smart-captcha
:
<div class="smart-captcha"></div>
Параметры для отрисовки виджета задаются через data-атрибуты контейнера.
Пример контейнера с параметрами для отрисовки виджета:
<div
class="smart-captcha"
data-sitekey="<Ключ_клиентской_части>"
data-hl="<Язык>"
></div>
Где:
Data-атрибут | Значение | Значение по умолчанию |
---|---|---|
data-sitekey |
string |
Отсутствует |
data-hl |
'ru' | 'en' | 'be' | 'kk' | 'tt' | 'uk' | 'uz' | 'tr' |
window.navigator.language |
data-callback |
string |
Отсутствует |
<html>
<head>
<meta charset="UTF-8">
<title>Форма аутентификации</title>
<script>
function callback(token) {
console.log(callback);
}
</script>
<script src="https://captcha-api.yandex.ru/captcha.js" async defer></script>
</head>
<body>
<p>Введите логин и пароль:</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="<Ключ_клиентской_части>"
data-hl="en"
data-callback="callback"
></div>
<input type="submit" value="Submit" />
</form>
</body>
</html>
Расширенный метод подключения
В расширенном методе JS-скрипт, который выполняет загрузку виджета на странице пользователя, добавляется на страницу по ссылке:
<script src="https://captcha-api.yandex.ru/captcha.js?render=onload&onload=onloadFunction"></script>
В параметре onload
передается функция, которая содержит параметры отрисовки виджета. В данном примере это функция onloadFunction
.
После загрузки JS-скрипта появляется доступ к объекту window.smartCaptcha
с методами для работы с виджетом.
<div id="<идентификатор_контейнера>"></div>
<script>
function onloadFunction() {
if (window.smartCaptcha) {
const container = document.getElementById('<идентификатор_контейнера>');
const widgetId = window.smartCaptcha.render(container, {
sitekey: '<Ключ_клиентской_части>',
hl: '<Язык>',
});
}
}
</script>
Методы window.smartCaptcha
Метод render
Метод render
служит для отрисовки виджета.
(
container: HTMLElement | string,
params: {
sitekey: string;
callback?: (token: string) => void;
hl?: 'ru' | 'en' | 'be' | 'kk' | 'tt' | 'uk' | 'uz' | 'tr';
invisible?: boolean;
shieldPosition?: `top-left` | `center-left` | `bottom-left` | `top-right` | `center-right` | `bottom-right`;
hideShield?: boolean;
}
) => WidgetId;
Где:
container
— контейнер для виджета. Можно передать DOM-элемент или идентификатор контейнера.params
— объект с параметрами для капчи:sitekey
— ключ клиентской части;callback
— функция-обработчик;hl
— язык виджета;invisible
— невидимая капча;shieldPosition
— расположение блока с уведомлением об обработке данных;hideShield
— скрыть блок с уведомлением об обработке данных.
Важно
Вы обязаны уведомлять пользователей о том, что их данные обрабатывает SmartCaptcha. Если вы скрываете блок с уведомлением, сообщите пользователям иным способом о том, что SmartCaptcha обрабатывает их данные.
Метод возвращает widgetId
- уникальный идентификатор виджета.
Метод getResponse
Метод getResponse
возвращает текущее значение токена пользователя.
(widgetId: WidgetId | undefined) => string;
Аргумент widgetId
— уникальный идентификатор виджета. Если аргумент не передан, будет возвращен результат первого отрисованного виджета.
Метод reset
Метод reset
сбрасывает состояние виджета до начального.
(widgetId: WidgetId | undefined) => void;
Аргумент widgetId
— уникальный идентификатор виджета. Если аргумент не передан, к начальному состоянию будет возвращен первый отрисованный виджет.
Метод destroy
Метод destroy
удаляет виджет и созданные им обработчики.
(widgetId: WidgetId | undefined) => void;
Аргумент — widgetId
, уникальный идентификатор виджета. Если аргумент не передан, будет удален первый отрисованный виджет.
Метод subscribe
Метод subscribe
позволяет подписывать обработчики на определенные события виджета.
Например, можно следить за открытием и закрытием всплывающего окна с заданием. Это может быть полезно для показа клавиатуры на мобильных устройствах.
(widgetId: widgetId, event: SubscribeEvent, callback: Function) =>
UnsubscribeFunction;
Где:
-
widgetId
— уникальный идентификатор виджета. -
event
— событие:type SubscribeEvent = | 'challenge-visible' | 'challenge-hidden' | 'network-error' | 'success';
Описание событий:
Событие Когда происходит Сигнатура обработчика challenge-visible
Открытие всплывающего окна с заданием () => void
challenge-hidden
Закрытие всплывающего окна с заданием () => void
network-error
Возникла сетевая ошибка () => void
success
Успешная валидация пользователя (token: string) => void
-
callback
— функция-обработчик:UnsubscribeFunction = () => void;
Пример использования:
<div id="container"></div>
<script
src="https://captcha-api.yandex.ru/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>
<script
src="https://captcha-api.yandex.ru/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: '<Ключ_клиентской_части>',
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>