Showing captcha on frontend request

1. Install VK Капча SDK.

2. Add the import of the CaptchaWidget class and the CaptchaPublicEvents object to the frontend:

   npm, yarn, pnpm

   JS script

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

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

3. Create an instance of the captcha widget:

    
   const captchaWidget = new CaptchaWidget();

4. Subscribe to events using the SDK method captchaWidget.on().

   Invisible captcha

   Embedded captcha

   Popup window

   If the service considers the user suspicious, the invisible captcha will be automatically replaced with a visible one. In this case, VK Капча SDK will send the captcha: challenge visible event, and after the captcha is completed — the captcha: challenge hidden event.

   Example:

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

   If the captcha is embedded in the page, the user needs to complete it before the target action, so the target action button must be blocked until the captcha: success event is received.

   Example:

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

   Example:

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

5. Get the captcha widget launch link from the backend.

6. Mount the captcha on the page. Use the SDK method captchaWidget.render().

   Invisible captcha

   Embedded captcha

   Popup window

   Set the invisible parameter to true.

   Example:

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

   For the invisible captcha, VK Капча SDK will display an automatic data processing notification to the user.

   In the container parameter, specify the HTML element or CSS selector to embed the captcha widget into.

   Example:

    
   await captchaWidget.render({   link,   lang: 'ru',   container: '<ELEMENT_FOR_EMBEDDING_CAPTCHA>'});

   If the CSS selector does not find any elements, a popup window will be displayed instead of the embedded captcha. This is not considered an error.

   Do not specify the container and invisible parameters.

   Example:

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

   The captcha will be mounted on the page, but it will not be visible to the user until the target action is called.

7. Call the SDK method captchaWidget.execute() on the target action.

   The method will return a promise object with the captcha completion result: a successful captcha completion token if the user passed the captcha, or an error.

8. Process the captcha completion result:

   • If the promise object contains a successful captcha completion token, send it to the backend for validation.
   • Determine what will happen in the frontend if the promise object returns an error. Error codes are described in the article SDK reference for web applications.

9. (Optional) For a single-page application (SPA, Single Page Application), where screens change without reloading the page, use the SDK method captchaWidget.destroy() to remove the previous captcha from the page.

TypeScript code examples:

 
import { CaptchaPublicEvents, CaptchaWidget } from '@vkid/captcha';const captchaWidget = new CaptchaWidget();// Set up subscriptions before mounting to avoid losing early eventscaptchaWidget.on(CaptchaPublicEvents.SUCCESS, onSuccess);captchaWidget.on(CaptchaPublicEvents.CHALLENGE_VISIBLE, onChallengeVisible);captchaWidget.on(CaptchaPublicEvents.CHALLENGE_HIDDEN, onChallengeHidden);captchaWidget.on(CaptchaPublicEvents.TOKEN_EXPIRED, onTokenExpired);// Mounting the captcha on the pageconst { link } = await api.post('/api/captcha/session');await captchaWidget.render({   link,   lang: 'ru',   invisible: true,   notice: { position: 'bottom-left', draggable: true },});// Target actionasync 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();// Set up subscriptions before mounting to avoid losing early eventscaptchaWidget.on(CaptchaPublicEvents.SUCCESS, () => setCanSubmit(true));captchaWidget.on(CaptchaPublicEvents.TOKEN_EXPIRED, onTokenExpired);// Mounting — once per page loadconst { link } = await api.post('/api/captcha/session');await captchaWidget.render({   link,   lang: 'ru',   container: '<ELEMENT_FOR_EMBEDDING_CAPTCHA>'});// Target actionasync 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();// Set up subscriptions before mounting to avoid losing early eventscaptchaWidget.on(CaptchaPublicEvents.SUCCESS, onSuccess);captchaWidget.on(CaptchaPublicEvents.TOKEN_EXPIRED, onTokenExpired);// Mounting — once per page loadconst { link } = await api.post('/api/captcha/session');await captchaWidget.render({   link,   lang: 'ru'});// Target actionasync function onSubmit({ login, password }: Credentials) {   const captchaToken = await captchaWidget.execute();   await api.post('/api/login', { login, password, captchaToken });}