Методы установки виджета Yandex SmartCaptcha

Статья создана

Yandex Cloud

Улучшена

Обновлена 21 марта 2024 г.

Автоматический метод подключения
Расширенный метод подключения
Методы window.smartCaptcha

Подключить виджет SmartCaptcha можно одним из двух методов:

Автоматический.
Расширенный.

В зависимости от метода подключения отличается способ передачи параметров для виджета.

Автоматический метод подключения

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

<script src="https://smartcaptcha.yandexcloud.net/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://smartcaptcha.yandexcloud.net/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://smartcaptcha.yandexcloud.net/captcha.js?render=onload&onload=onloadFunction"></script>

В параметре onload передается функция, которая содержит параметры отрисовки виджета. В данном примере это функция onloadFunction.

После загрузки JS-скрипта появляется доступ к объекту window.smartCaptcha с методами для работы с виджетом.

Пример кода onloadFunction

<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';
      test?: boolean;
      webview?: boolean;
      invisible?: boolean;
      shieldPosition?: `top-left` | `center-left` | `bottom-left` | `top-right` | `center-right` | `bottom-right`;
      hideShield?: boolean;
  }
) => WidgetId;

Где:

container — контейнер для виджета. Можно передать DOM-элемент или идентификатор контейнера.
params — объект с параметрами для капчи:
- sitekey — ключ клиентской части.
- callback — функция-обработчик.
- hl — язык виджета.
- test — включение работы капчи в режиме тестирования. Пользователь всегда будет получать задание. Используйте это свойство только для отладки и тестирования.
- webview — запуск капчи в WebView. Используется для повышения точности оценки пользователей при добавлении капчи в мобильные приложения с помощью WebView.
- invisible — невидимая капча.
- shieldPosition — расположение блока с уведомлением об обработке данных.
- hideShield — скрыть блок с уведомлением об обработке данных.

Важно

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

Метод возвращает widgetId — уникальный идентификатор виджета.

Метод getResponse

Метод getResponse возвращает текущее значение токена пользователя.

(widgetId: WidgetId | undefined) => string;

Аргумент widgetId — уникальный идентификатор виджета. Если аргумент не передан, будет возвращен результат первого отрисованного виджета.

Метод execute

Метод execute запускает проверку пользователя. Используется чтобы начать проверку невидимой капчи при каком-то событии, например, при нажатии на кнопку отправки формы аутентификации.

(widgetId: WidgetId | undefined) => void;

Аргумент widgetId — уникальный идентификатор виджета. Если аргумент не передан, проверка будет запущена на первом отрисованном виджете.

Метод reset

Метод reset сбрасывает состояние виджета до начального.

(widgetId: WidgetId | undefined) => void;

Аргумент widgetId — уникальный идентификатор виджета. Если аргумент не передан, к начальному состоянию будет возвращен первый отрисованный виджет.

Метод destroy

Метод destroy удаляет виджет и созданные им обработчики.

(widgetId: WidgetId | undefined) => void;

Аргумент — widgetId, уникальный идентификатор виджета. Если аргумент не передан, будет удален первый отрисованный виджет.

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

(widgetId: widgetId, event: SubscribeEvent, callback: Function) =>
  UnsubscribeFunction;

Где:

widgetId — уникальный идентификатор виджета.

event — событие:

type SubscribeEvent =
| 'challenge-visible'
| 'challenge-hidden'
| 'network-error'
| 'javascript-error'
| 'success'
| 'token-expired';

Описание событий:

Событие	Когда происходит	Сигнатура обработчика
`challenge-visible`	Открытие всплывающего окна с заданием	`() => void`
`challenge-hidden`	Закрытие всплывающего окна с заданием	`() => void`
`network-error`	Возникла сетевая ошибка	`() => void`
`javascript-error`	Возникла критическая ошибка JS	`(error: { filename: string, message: string,` `col: number, line: number }) => void`
`success`	Успешная валидация пользователя	`(token: string) => void`
`token-expired`	Токен прохождения проверки стал невалидным	`() => void`

callback — функция-обработчик:
```
UnsubscribeFunction = () => void;
```

Важно

Ошибка javascript-error указывает на критический сбой в работе JavaScript. Сообщите об этой проблеме пользователю в интерфейсе приложения. При возникновении такой ошибки засчитывать успешное выполнение задания нельзя — это может создать потенциальную уязвимость вашего приложения.

Пример использования:

<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>

Пример встраивания виджета

<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: '<ключ_клиентской_части>',
      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>

Методы установки виджета Yandex SmartCaptcha

Автоматический метод подключенияАвтоматический метод подключения

Расширенный метод подключенияРасширенный метод подключения

Методы window.smartCaptchaМетоды window.smartCaptcha

Метод renderМетод render

Метод getResponseМетод getResponse

Метод executeМетод execute

Метод resetМетод reset

Метод destroyМетод destroy

Метод subscribeМетод subscribe

Была ли статья полезна?

Автоматический метод подключения

Расширенный метод подключения

Методы window.smartCaptcha

Метод render

Метод getResponse

Метод execute

Метод reset

Метод destroy

Метод subscribe