YaSmartCaptcha

Это дополнение позволит использовать SmartCaptcha от Яндекс на вашем сайте на MODX в формах, созданных с использованием сниппета FormIt (Login).

Быстрый старт

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

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

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

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

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

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

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

[[!YaSmartCaptcha]]

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

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

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

У сниппета единственный параметр tpl, имеющий значение по-умолчанию tpl.YaSmartCaptcha.

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

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

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

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

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

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

Подключение

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

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

Сниппет выведет контейнер капчи (чанк tpl.YaSmartCaptcha.Invisible); поле smart-token виджет создаёт внутри контейнера сам, добавлять его в разметку вручную не нужно. 3. Хук YaSmartCaptcha в FormIt подключается так же, как и для обычной капчи. 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-элемент формы.

Дополнительно на контейнере можно указать атрибуты 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 остаётся неразрешённым: форма не отправляется, повторный клик запускает проверку заново.

Если Яндекс недоступен

Если сервис проверки не отвечает или возвращает ошибку 5xx, пользователь по умолчанию пропускается, а причина записывается в журнал ошибок MODX. Чтобы отклонять такие отправки, отключите настройку yasmartcaptcha_fail_open.