SDK reference for web applications

Supported browsers:

• Google Chrome version 52 and above;
• Microsoft Edge version 79 and above;
• Firefox version 57 and above;
• Safari version 11 and above;
• Opera version 39 and above;
• Yandex Browser version 16.9 and above.

The captchaWidget.render() method mounts the captcha onto the page and starts the captcha service. The method is called once per page load.

Example of a method call:

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

Method parameters:

The method returns a promise object with captcha readiness:

 
promise resolvepromise reject <ERROR>

Error codes:

The captchaWidget.execute() method:

• starts the user check;
• displays a pop-up window with the captcha, if this is set by the captchaWidget.render() method;
• returns a token of successful captcha completion to pass to the backend.

The method is called once per mounted captcha session. Usually, it is triggered in response to a user's target action, such as submitting a form, but it can also be called by a backend response that initiated the captcha.

The captcha session is consumed by the first check: after a successful check, a repeated call to the method is rejected with the already_checked error. To run the next check on the same page load, remove the captcha with the captchaWidget.destroy() method and mount it again with the captchaWidget.render() method using a new link from the response of the GET /captchaNotRobot.createSession method.

Example of a method call:

 
const successToken = await captchaWidget.execute();

Parameters of the captchaWidget.execute() method:

The method returns a promise object with the check result:

 
promise resolve <CAPTCHA_COMPLETION_TOKEN>promise reject <ERROR>

Here:

• <CAPTCHA_COMPLETION_TOKEN> — token of successful captcha completion, if the user passed the captcha;
• <ERROR> — error code.

Error codes:

The captchaWidget.on() method is used to subscribe to events. Event names are available as properties of the CaptchaPublicEvents object.

Example of a method call:

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

Events you can subscribe to:

When using the deprecated captchaWidget.show() method, events are not sent. The result comes only as a promise object of the method.

To unsubscribe from events, use the captchaWidget.off() method.

Example of a method call:

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

The captchaWidget.hidePopup() method hides the captcha widget without interrupting the check. The service continues to run, and the widget can be shown again instantly. The method returns nothing in the response.

Example of a method call:

 
captchaWidget.hidePopup();

The captchaWidget.showPopup() method returns the captcha widget to the screen. The completion and state of the check are not reset. The method returns nothing in the response.

VK Капча SDK calls this method automatically when an invisible check transitions to a visible task.

Example of a method call:

 
captchaWidget.showPopup();

The captchaWidget.close() method closes the captcha widget. The method returns nothing in the response.

Example of a method call:

 
captchaWidget.close();

The captchaWidget.destroy() method removes the captcha from the page and returns the widget to its initial state: after it, the next captcha can be mounted on the same page load using the captchaWidget.render() method. The method returns nothing in the response.

The method is needed for single-page applications (SPA, Single Page Application), where screens change without a page reload. In this case, the captcha is tied to the screen lifecycle: when the screen appears, the captchaWidget.render() method is called; when leaving this screen — captchaWidget.destroy(). Each screen has its own captcha session and its own link. If the next screen also calls the captchaWidget.render() method without a preceding captchaWidget.destroy() call, the promise object is rejected with the already_initialized error.

Each screen needs its own instance of CaptchaWidget. Only one captcha instance should be running on the page at a time. When switching between screens, first call captchaWidget.destroy() on the current instance, then create and mount a new one.

The link for the next captcha must be new: the captcha session is consumed by the first check. Request a fresh link using the GET /captchaNotRobot.createSession method. You cannot cache the link in the application state: on the next screen, the captcha will be mounted, but the check will return an expired token. Request the link in the same code that calls captchaWidget.render().

Handle the rejection of the promise object with the destroyed error. The captchaWidget.destroy() method rejects unfinished promise objects of the captchaWidget.render() and captchaWidget.execute() methods with the destroyed error. In React StrictMode, the effect is executed twice in development mode, so the first call to captchaWidget.render() is always rejected — in the console, it looks like an unhandled promise rejection.

Before calling captchaWidget.render(), check that the screen is still active. Between requesting the link and the backend response, the user may leave the screen. A captchaWidget.destroy() called after that will do nothing, because the captcha has not yet been mounted, and the captchaWidget.render() called next will mount it on the abandoned screen.

VK Капча SDK does not send any events about captcha removal.

Example of a method call:

 
let captchaWidget: CaptchaWidget | undefined;let isScreenActive = false;// Screen appeared. In React — the effect of the component containing the captchaasync function mountCaptcha() {    isScreenActive = true;    captchaWidget = new CaptchaWidget();    captchaWidget.on(CaptchaPublicEvents.SUCCESS, onSuccess);    const { link } = await api.post('/api/captcha/session', { client });    // The user may have left the screen while the backend was responding    if (!isScreenActive) {        return;    }    // Leaving the screen before loading rejects the promise object with the destroyed code    await captchaWidget.render({ link, lang: 'ru', invisible: true }).catch(handleRenderError);}// Leaving the screen. In React — the cleanup function of the same effectfunction unmountCaptcha() {    isScreenActive = false;    captchaWidget?.destroy();}

The captchaWidget.show() method displays the captcha widget to the user in a web application and is used in cases where the backend decides whether a user check is necessary. The captcha widget is displayed in a pop-up window (iframe).

Method parameters:

The method returns a promise object with the captcha completion result:

 
promise resolve <CAPTCHA_COMPLETION_TOKEN> promise reject <ERROR>

Here:

• <CAPTCHA_COMPLETION_TOKEN> — token of successful captcha completion, if the user passed the captcha;
• <ERROR> — the close error, if the user closed the captcha window.