Подключиться
Yandex SmartCaptcha

Методы установки виджета 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 с методами для работы с виджетом.

Пример кода 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';
      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>
В этой статье: