YaSmartCaptcha - защитите ваши формы от спама умной капчей от Яндекс

Привет!

Представляю вам небольшой пакет, который упростит интеграцию Яндекс SmartCaptcha на ваш сайт.

Это дополнение позволит использовать SmartCaptcha от Яндекс на вашем сайте на MODX в формах, созданных с использованием сниппета FormIt (ну а также других компонентах, являющимися надстройкой над FormIt, такими как AjaxForm, SendIt). Поддерживается как обычная капча с кнопкой «Я не робот», так и невидимая.

Регистрация в Yandex Cloud

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

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

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

Это бесплатно?
На момент публикации (январь 2024) Яндекс дает 250000 бесплатных проверок на спам в месяц, больше уже за деньги.

Настройка компонента

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

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

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

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

Добавление капчи в форму

Вообще принцип работы такой же, как в Google Recaptcha v2, если вы пользовались им ранее, то трудностей быть не должно. Это касается обычной капчи с кнопкой; для невидимой понадобится ещё немного JS, см. раздел ниже.

Шаг 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`
    ..
    ]]

Если проверка не будет пройдена, то хук установит сразу 2 одинаковые ошибки с ключами smart-token и yasmartcaptcha.

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

Невидимая капча

Невидимая капча не показывает кнопку «Я не робот», проверка запускается из JS вашего сайта и показывается пользователю, только если Яндекс сочтёт его подозрительным. Подробнее о самой технологии — в документации Яндекса: yandex.cloud/ru/docs/smartcaptcha/concepts/invisible-captcha

Формы на разных сайтах отправляются по-разному (обычный submit, AJAX, сторонние библиотеки типа AjaxForm), поэтому компонент не пытается угадать, как перехватить отправку вашей формы. Вместо этого он даёт небольшой 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 остаётся неразрешённым: форма не отправляется, повторный клик запускает проверку заново.

Ссылки

Ссылка на github:
https://github.com/createit-ru/YaSmartCaptcha

Скачать пакет:
https://modstore.pro/packages/utilities/yasmartcaptcha
Также ссылка на транспортный пакет есть на github в разделе Releases (правда не гарантирую, что раздел Releases не забуду обновлять).

В заключение

Компонент бесплатный, но если вам понравился и пригодился — можно поблагодарить финансово по ссылке:



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

if ((isset($formit) || isset($login)) && isset($hook)) {