Справочник SDK для веб-приложений

Поддерживаемые браузеры:

• Google Chrome версии 52 и выше;
• Microsoft Edge версии 79 и выше;
• Firefox версии 57 и выше;
• Safari версии 11 и выше;
• Opera версии 39 и выше;
• Яндекс Браузер версии 16.9 и выше.

Метод captchaWidget.render() монтирует капчу на страницу и запускает сервис капчи. Метод вызывается один раз на загрузку страницы.

Пример вызова метода:

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

Параметры метода:

Метод возвращает promise-объект с готовностью капчи:

 
promise resolvepromise reject <ОШИБКА>

Коды ошибок:

Метод captchaWidget.execute():

• запускает проверку пользователя;
• отображает всплывающее окно с капчей, если это задано методом captchaWidget.render();
• возвращает токен успешного прохождения капчи для передачи бэкенду.

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

Капча-сессия расходуется первой же проверкой: после успешной проверки повторный вызов метода отклоняется с ошибкой already_checked. Чтобы запустить следующую проверку на той же загрузке страницы, снимите капчу методом captchaWidget.destroy() и смонтируйте ее заново методом captchaWidget.render() с новой ссылкой из ответа метода GET /captchaNotRobot.createSession.

Пример вызова метода:

 
const successToken = await captchaWidget.execute();

Параметры метода captchaWidget.execute():

Метод возвращает promise-объект с результатом проверки:

 
promise resolve <ТОКЕН_ПРОХОЖДЕНИЯ_КАПЧИ>promise reject <ОШИБКА>

Здесь:

• <ТОКЕН_ПРОХОЖДЕНИЯ_КАПЧИ> — токен успешного прохождения капчи, если пользователь прошел капчу;
• <ОШИБКА> — код ошибки.

Коды ошибок:

Для подписки на события используется метод captchaWidget.on(). Имена событий доступны как свойства объекта CaptchaPublicEvents.

Пример вызова метода:

 
import { CaptchaPublicEvents } from '@vkid/captcha';captchaWidget.on(CaptchaPublicEvents.SUCCESS, () => setCanSubmit(true));

События, на которые можно подписаться:

При использовании устаревшего метода captchaWidget.show() события не отправляются. Результат приходит только promise-объектом метода.

Чтобы отменить подписку на события, используйте метод captchaWidget.off().

Пример вызова метода:

 
import { CaptchaPublicEvents } from '@vkid/captcha';captchaWidget.off(CaptchaPublicEvents.SUCCESS, onSuccess);

Метод captchaWidget.hidePopup() скрывает виджет капчи, не прерывая проверку. Сервис продолжает работать, повторный показ виджета мгновенный. Метод ничего не возвращает в ответе.

Пример вызова метода:

 
captchaWidget.hidePopup();

Метод captchaWidget.showPopup() возвращает виджет капчи на экран. Прохождение и состояние проверки при этом не сбрасываются. Метод ничего не возвращает в ответе.

VK Капча SDK вызывает этот метод автоматически при переходе невидимой проверки в видимое задание.

Пример вызова метода:

 
captchaWidget.showPopup();

Метод captchaWidget.close() закрывает виджет капчи. Метод ничего не возвращает в ответе.

Пример вызова метода:

 
captchaWidget.close();

Метод captchaWidget.destroy() убирает капчу со страницы и возвращает виджет в исходное состояние: после него на той же загрузке страницы можно смонтировать следующую капчу методом captchaWidget.render(). Метод ничего не возвращает в ответе.

Метод нужен одностраничным приложениям (SPA, Single Page Application), где экраны сменяются без перезагрузки страницы. В этом случае капча привязывается к жизненному циклу экрана: при появлении экрана вызывается метод captchaWidget.render(), при уходе с этого экрана — captchaWidget.destroy(). У каждого экрана своя капча-сессия и своя ссылка. Если на следующем экране тоже вызывается метод captchaWidget.render() без предшествующего вызова captchaWidget.destroy(), promise-объект отклоняется с ошибкой already_initialized.

Каждому экрану нужен свой экземпляр CaptchaWidget. Одновременно на странице должен работать только один экземпляр капчи. При переходе между экранами сначала вызовите captchaWidget.destroy() на текущем экземпляре, а затем создайте и смонтируйте новый.

Ссылка для следующей капчи должна быть новой: капча-сессия расходуется первой же проверкой. Запросите свежую ссылку методом GET /captchaNotRobot.createSession. Кешировать ссылку в состоянии приложения нельзя: на следующем экране капча смонтируется, но проверка вернет истекший токен. Запрашивайте ссылку в том же коде, который вызывает captchaWidget.render().

Обрабатывайте отклонение promise-объекта с ошибкой destroyed. Метод captchaWidget.destroy() отклоняет незавершенные promise-объекты методов captchaWidget.render() и captchaWidget.execute() с ошибкой destroyed. В React StrictMode эффект в режиме разработки выполняется дважды, поэтому первый вызов captchaWidget.render() отклоняется всегда — в консоли это выглядит как необработанное отклонение promise-объекта.

Перед вызовом captchaWidget.render() проверяйте, что экран еще активен. Между запросом ссылки и ответом бэкенда пользователь может уйти с экрана. Вызванный после этого captchaWidget.destroy() ничего не сделает, потому что капча еще не смонтирована, а вызванный следом captchaWidget.render() смонтирует ее на покинутом экране.

О снятии капчи VK Капча SDK событий не отправляет.

Пример вызова метода:

 
let captchaWidget: CaptchaWidget | undefined;let isScreenActive = false;// Экран появился. В React — эффект компонента, в котором стоит капчаasync function mountCaptcha() {    isScreenActive = true;    captchaWidget = new CaptchaWidget();    captchaWidget.on(CaptchaPublicEvents.SUCCESS, onSuccess);    const { link } = await api.post('/api/captcha/session', { client });    // Пользователь мог уйти с экрана, пока бэкенд отвечал    if (!isScreenActive) {        return;    }    // Уход с экрана до загрузки отклоняет promise-объект кодом destroyed    await captchaWidget.render({ link, lang: 'ru', invisible: true }).catch(handleRenderError);}// Уход с экрана. В React — функция очистки того же эффектаfunction unmountCaptcha() {    isScreenActive = false;    captchaWidget?.destroy();}

Метод captchaWidget.show() отображает виджет капчи пользователю в веб-приложении и используется в случаях, когда решение о необходимости проверки пользователя принимает бэкенд. Виджет капчи отображается во всплывающем окне (iframe).

Параметры метода:

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

 
promise resolve <ТОКЕН_ПРОХОЖДЕНИЯ_КАПЧИ> promise reject <ОШИБКА>

Здесь:

• <ТОКЕН_ПРОХОЖДЕНИЯ_КАПЧИ> — токен успешного прохождения капчи, если пользователь прошел капчу;
• <ОШИБКА> — ошибка close, если пользователь закрыл окно капчи.