Показ капчи по запросу фронтенда

1. Установите VK Капча SDK.

2. Добавьте во фронтенд импорт класса CaptchaWidget и объекта CaptchaPublicEvents:

   npm, yarn, pnpm

   JS-скрипт

    
   import { CaptchaPublicEvents, CaptchaWidget } from "@vkid/captcha";

    
   const { CaptchaPublicEvents, CaptchaWidget } = await window.vkidCaptcha;

3. Создайте экземпляр виджета капчи:

    
   const captchaWidget = new CaptchaWidget();

4. Подпишитесь на события с помощью метода SDK captchaWidget.on().

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

   Встроенная капча

   Всплывающее окно

   Если сервис оценит пользователя как подозрительного, невидимая капча будет автоматически заменена на видимую. При этом VK Капча SDK отправит событие captcha: challenge visible, а после прохождения капчи — captcha: challenge hidden.

   Пример:

    
   captchaWidget.on(CaptchaPublicEvents.SUCCESS, onSuccess);captchaWidget.on(CaptchaPublicEvents.CHALLENGE_VISIBLE, onChallengeVisible);captchaWidget.on(CaptchaPublicEvents.CHALLENGE_HIDDEN, onChallengeHidden);captchaWidget.on(CaptchaPublicEvents.TOKEN_EXPIRED, onTokenExpired);

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

   Пример:

    
   captchaWidget.on(CaptchaPublicEvents.SUCCESS, () => setCanSubmit(true));captchaWidget.on(CaptchaPublicEvents.TOKEN_EXPIRED, onTokenExpired);

   Пример:

    
   captchaWidget.on(CaptchaPublicEvents.SUCCESS, onSuccess);captchaWidget.on(CaptchaPublicEvents.TOKEN_EXPIRED, onTokenExpired);

5. Получите от бэкенда ссылку для запуска виджета капчи.

6. Монтируйте капчу на страницу. Воспользуйтесь методом SDK captchaWidget.render().

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

   Встроенная капча

   Всплывающее окно

   В параметре invisible укажите значение true.

   Пример:

    
   await captchaWidget.render({   link,   lang: 'ru',   invisible: true,   notice: { position: 'bottom-left', draggable: true },});

   Для невидимой капчи VK Капча SDK отобразит пользователю автоматическое уведомление об обработке данных.

   В параметре container укажите HTML-элемент или CSS-селектор, в который нужно встроить виджет капчи.

   Пример:

    
   await captchaWidget.render({   link,   lang: 'ru',   container: '<ЭЛЕМЕНТ_ДЛЯ_ВСТРАИВАНИЯ_КАПЧИ>'});

   Если CSS-селектор не найдет элементов, вместо встроенной капчи отобразится всплывающее окно. Это не считается ошибкой.

   Параметры container и invisible не указывайте.

   Пример:

    
   await captchaWidget.render({   link,   lang: 'ru'});

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

7. На целевом действии вызовите метод SDK captchaWidget.execute().

   Метод вернет promise-объект с результатом прохождения капчи: токен успешного прохождения капчи, если пользователь прошел капчу, или ошибку.

8. Обработайте результат прохождения капчи:

   • Если promise-объект содержит токен успешного прохождения капчи, отправьте его бэкенду для валидации.
   • Определите, что будет происходить во фронтенде в случае, когда promise-объект вернул ошибку. Коды ошибок описаны в статье Справочник SDK для веб-приложений.

9. (Опционально) Для одностраничного приложения (SPA, Single Page Application), где экраны сменяются без перезагрузки страницы, используйте метод SDK captchaWidget.destroy(), чтобы убрать предыдущую капчу со страницы.

Примеры кода на TypeScript:

 
import { CaptchaPublicEvents, CaptchaWidget } from '@vkid/captcha';const captchaWidget = new CaptchaWidget();// Подписки ставим до монтажа, чтобы не потерять ранние событияcaptchaWidget.on(CaptchaPublicEvents.SUCCESS, onSuccess);captchaWidget.on(CaptchaPublicEvents.CHALLENGE_VISIBLE, onChallengeVisible);captchaWidget.on(CaptchaPublicEvents.CHALLENGE_HIDDEN, onChallengeHidden);captchaWidget.on(CaptchaPublicEvents.TOKEN_EXPIRED, onTokenExpired);// Монтаж капчи на страницуconst { link } = await api.post('/api/captcha/session');await captchaWidget.render({   link,   lang: 'ru',   invisible: true,   notice: { position: 'bottom-left', draggable: true },});// Целевое действиеasync function onSubmit({ login, password }: Credentials) {   const captchaToken = await captchaWidget.execute();   await api.post('/api/login', { login, password, captchaToken });}

 
import { CaptchaPublicEvents, CaptchaWidget } from '@vkid/captcha';const captchaWidget = new CaptchaWidget();// Подписки ставим до монтажа, чтобы не потерять ранние событияcaptchaWidget.on(CaptchaPublicEvents.SUCCESS, () => setCanSubmit(true));captchaWidget.on(CaptchaPublicEvents.TOKEN_EXPIRED, onTokenExpired);// Монтаж — один раз на загрузку страницыconst { link } = await api.post('/api/captcha/session');await captchaWidget.render({   link,   lang: 'ru',   container: '<ЭЛЕМЕНТ_ДЛЯ_ВСТРАИВАНИЯ_КАПЧИ>'});// Целевое действиеasync function onSubmit({ login, password }: Credentials) {   const captchaToken = await captchaWidget.execute();   await api.post('/api/login', { login, password, captchaToken });}

 
import { CaptchaPublicEvents, CaptchaWidget } from '@vkid/captcha';const captchaWidget = new CaptchaWidget();// Подписки ставим до монтажа, чтобы не потерять ранние событияcaptchaWidget.on(CaptchaPublicEvents.SUCCESS, onSuccess);captchaWidget.on(CaptchaPublicEvents.TOKEN_EXPIRED, onTokenExpired);// Монтаж — один раз на загрузку страницыconst { link } = await api.post('/api/captcha/session');await captchaWidget.render({   link,   lang: 'ru'});// Целевое действиеasync function onSubmit({ login, password }: Credentials) {   const captchaToken = await captchaWidget.execute();   await api.post('/api/login', { login, password, captchaToken });}