Воспользуйтесь этим дополнением для защиты форм, созданных с использованием FormIt, от спама с помощью капчи от Яндекс.
Компонент совместим со сниппетами FormIt и Login. Поддерживается как обычная капча с кнопкой «Я не робот», так и невидимая.

Регистрация в Yandex Cloud
Перед началом работы ознакомьтесь с инструкцией и зарегистрируйтесь в сервисе:
https://yandex.cloud/ru/docs/smartcaptcha/quickstart

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

После прохождения регистрации создайте свою первую капчу и вы получите 2 ключа (клиентский и серверный). У Яндекса хорошая и понятная документация, проблем быть не должно.

Настройка компонента
Перейдите в системные настройки, выберите пространство yasmartcaptcha, и пропишите оба ключа:

• yasmartcaptcha_client_key — Клиентский ключ
• yasmartcaptcha_server_key — Серверный ключ

Также доступны дополнительные настройки:

• yasmartcaptcha_enabled — глобально включить или выключить капчу на сайте, в том числе её рендеринг на страницах и проверку в хуках. По умолчанию включена.
• yasmartcaptcha_send_user_ip — передавать ли IP пользователя в Яндекс. По идее это может улучшить работу сервиса SmartCaptcha.
• yasmartcaptcha_invisible — использовать невидимую капчу вместо обычной, подробнее в разделе ниже.
• yasmartcaptcha_fail_open — пропускать ли пользователя, если сервис проверки Яндекса недоступен или отвечает с ошибкой. По умолчанию включена, то есть недоступность Яндекса не блокирует ваши формы; причина при этом записывается в журнал ошибок MODX.

Добавление капчи в форму
Шаг 1. В том месте, где вам нужно добавить капчу, добавьте некешированный вызов сниппета:

[[!YaSmartCaptcha]]

Данный сниппет подключит на страницу (перед закрывающимся body) скрипт от Яндекса:

https://smartcaptcha.cloud.yandex.ru/captcha.js

и добавит html блок с капчей.

У сниппета единственный параметр tpl. Если его не указывать, чанк выбирается автоматически: tpl.YaSmartCaptcha для обычной капчи или tpl.YaSmartCaptcha.Invisible, если включена настройка yasmartcaptcha_invisible.

Шаг 2. Добавьте хук YaSmartCaptcha к FormIt, например:

[[!FormIt?
    &hooks=`YaSmartCaptcha,email`
    ..
    ]]

Естественно, этот хук идет до других, например email.

Если проверка не будет пройдена, то хук установит 2 ошибки: smart-token и yasmartcaptcha.
Первая (smart-token) соответствует названию hidden поля, которое добавляет Яндекс SmartCaptcha в вашу форму.
Вторая (yasmartcaptcha) соответствует названию компонента и более понятна.

Можете использовать любой ключ для показа ошибки, они равнозначны.

Если все сделано правильно, то может быть 2 вида ошибки с текстами:
— Не удалось пройти проверку на робота, попробуйте еще раз. (если поле smart-token не заполнено, например пользователь не прошёл проверку)
— Проверка не пройдена, попробуйте еще раз. (если Яндекс не подтвердил токен)

Невидимая капча
Невидимая капча не показывает кнопку «Я не робот», проверка запускается из JS вашего сайта и показывается пользователю, только если Яндекс сочтёт его подозрительным.

Формы на разных сайтах отправляются по-разному (обычный submit, AJAX, сторонние библиотеки), поэтому компонент не пытается угадать, как перехватить отправку вашей формы. Вместо этого он даёт небольшой JS API, а момент запуска проверки и саму отправку формы вы контролируете сами.

Подключение

1. В системных настройках включите yasmartcaptcha_invisible.
2. Вызов сниппета остаётся прежним, но он должен находиться внутри тега

   <form>

   :
   

   <form method="post">
       [[!YaSmartCaptcha]]
       ..
   </form>

   Сниппет выведет контейнер капчи (чанк tpl.YaSmartCaptcha.Invisible); поле smart-token виджет создаёт внутри контейнера сам, добавлять его в разметку вручную не нужно.
   
3. Хук YaSmartCaptcha в FormIt подключается так же, как и для обычной капчи (см. Шаг 2 выше).
4. В JS сайта перед отправкой формы вызовите

   YaSmartCaptcha.execute(form)

   .

Если вы подключаете скрипт Яндекса вручную (поле yasmartcaptcha_service_js очищено), добавьте к нему параметры

?render=onload&onload=YaSmartCaptchaInit

и подключите

assets/components/yasmartcaptcha/js/yasmartcaptcha.js

раньше него.

JS API

• YaSmartCaptcha.execute(form)

  — запускает проверку и возвращает Promise с токеном. Проверка показывается пользователю только если Яндекс сочтёт его подозрительным.

• YaSmartCaptcha.reset(form)

  — сбрасывает капчу. Вызывайте после каждой отправки формы: токен одноразовый и действует 5 минут.

В обоих методах form — это DOM-элемент формы (не jQuery-объект; для jQuery используйте

jqForm[0]

).

Дополнительно на контейнере можно указать атрибуты data-hide-shield (скрыть уведомление об обработке данных, в этом случае Яндекс требует показать его самостоятельно) и data-test (тестовый режим).

Примеры
Обычная форма:

form.addEventListener('submit', async (e) => {
    e.preventDefault();
    await YaSmartCaptcha.execute(form);
    form.submit();
});

Отправка через fetch:

form.addEventListener('submit', async (e) => {
    e.preventDefault();
    await YaSmartCaptcha.execute(form);
    const response = await fetch(form.action, {method: 'POST', body: new FormData(form)});
    // ..обработка ответа..
    YaSmartCaptcha.reset(form);
});

Если пользователь закрыл окно проверки, Promise остаётся неразрешённым: форма не отправляется, повторный клик запускает проверку заново.

Полная документация и исходный код компонента: https://github.com/createit-ru/YaSmartCaptcha