Contact UsTry it for free
© 2025 Direct Cursus Technology L.L.C.

Yandex SmartCaptcha widget installation methods

Written by
Updated at December 2, 2025

There are two methods to connect a SmartCaptcha widget:

  • Automatic
  • Advanced

Depending on the connection method, different widget parameter transmission methods are used.

Automatic connection method

In the automatic method, a JS script that loads the widget on the user page is added to the page by a link:

<script src="https://smartcaptcha.cloud.yandex.ru/captcha.js" defer></script>

After uploading, the JS script searches for all containers suitable for loading a widget into them, and renders widgets in them.

You can load a widget using the div elements of the smart-captcha class:

<div class="smart-captcha"></div>

Parameters for rendering the widget are set via container data attributes.

Example of a container with parameters for rendering a widget:

<div
  class="smart-captcha"
  data-sitekey="<client_part_key>"
  data-hl="<language>"
></div>

Where:

Data attribute Value Default value
data-sitekey string None
data-hl 'ru' | 'en' | 'be' | 'kk' | 'tt' | 'uk' | 'uz' | 'tr' window.navigator.language
data-callback string None
Example of embedding the widget
<html>
  <head>
    <meta charset="UTF-8">
    <title>Authentication form</title>
    <script>
      function callback(token) {
        console.log(callback);
      }
    </script>
    <script src="https://smartcaptcha.cloud.yandex.ru/captcha.js" async defer></script>
  </head>

  <body>
    <p>Enter your username and password:</p>
    <form id="auth_form" action="" method="POST">
      <input id="csrf_token" name="csrf_token" type="hidden" />
      <label for="username">Name</label>
      <input id="username" type="text" name="user" />
      <label for="userpass">Password</label>
      <input id="userpass" type="password" name="password" />
      <div
        id="captcha-container"
        class="smart-captcha"
        data-sitekey="<client_part_key>"
        data-hl="en"
        data-callback="callback"
      ></div>
      <input type="submit" value="Submit" />
    </form>
  </body>
</html>

Advanced connection method

In the advanced method, a JS script that loads the widget on the user page is added to the page by a link:

<script src="https://smartcaptcha.cloud.yandex.ru/captcha.js?render=onload&onload=onloadFunction"></script>

In onload, you provide the function containing the widget rendering parameters. In our example, it is onloadFunction.

After the JS script is loaded, you gain access to the window.smartCaptcha object with methods for the widget.

Sample onloadFunction code
<div id="<container_ID>"></div>

<script>
  function onloadFunction() {
    if (window.smartCaptcha) {
      const container = document.getElementById('<container_ID>');

      const widgetId = window.smartCaptcha.render(container, {
        sitekey: '<client_part_key>',
        hl: '<language>',
      });
    }
  }
</script>

window.smartCaptcha methods

render method

The render method is used to render the widget.

(
  container: HTMLElement | string,
  params: {
      sitekey: string;
      callback?: (token: string) => void;
      hl?: 'ru' | 'en' | 'be' | 'kk' | 'tt' | 'uk' | 'uz' | 'tr';
      test?: boolean;
      webview?: boolean;
      invisible?: boolean;
      shieldPosition?: `top-left` | `center-left` | `bottom-left` | `top-right` | `center-right` | `bottom-right`;
      hideShield?: boolean;
  }
) => WidgetId;

Where:

  • container: Container for the widget. You can transmit a DOM element or ID of the container.
  • params: Object with parameters for the CAPTCHA:
    • sitekey: Client-side key.
    • callback: Handler function.
    • hl: Widget language.
    • test: Running CAPTCHA in test mode. The user will always get a challenge. Use this property for debugging and testing only.
    • webview: Launching CAPTCHA in WebView. You can use it to make user response validation more precise when adding CAPTCHA to mobile apps via WebView.
    • invisible: Invisible CAPTCHA.
    • shieldPosition: Position of the data processing notice box.
    • hideShield: Hide the data processing notice box.

Warning

You must notify users that their data is processed by SmartCaptcha. If you hide the notice shield, find another way to tell users that SmartCaptcha processes their data.

The method returns widgetId, the unique widget ID.

GetResponse method

The getResponse method returns the current value of the user token.

(widgetId: WidgetId | undefined) => string;

The widgetId argument is the unique widget ID. If no argument is provided, the result of the first rendered widget is returned.

Execute method

The execute method starts user validation. It is used to initiate the invisible CAPTCHA test at a certain event, e.g., when the user clicks the Submit button of an authentication form.

(widgetId: WidgetId | undefined) => void;

The widgetId argument is the unique widget ID. If the argument is not provided, the test will be run on the first rendered widget.

reset method

The reset method resets the widget to the initial state.

(widgetId: WidgetId | undefined) => void;

The widgetId argument is the unique widget ID. If no argument has been passed, the first rendered widget is reset.

destroy method

The destroy method deletes widgets and any listeners they created.

(widgetId: WidgetId | undefined) => void;

The widgetId argument is the unique widget ID. If the argument is not passed, the first rendered widget will be deleted.

subscribe method

The subscribe method enables you to subscribe listeners to specific widget events.
For instance, you can listen for the opening and closing of a challenge pop-up window. This may be useful for displaying the keyboard on mobile devices.

(widgetId: widgetId, event: SubscribeEvent, callback: Function) =>
  UnsubscribeFunction;

Where:

  • widgetId: Unique widget ID.

  • event: Event:

    type SubscribeEvent =
| 'challenge-visible'
| 'challenge-hidden'
| 'network-error'
| 'javascript-error'
| 'success'
| 'token-expired';

    Event descriptions:

    Event When it occurs Handler signature
    challenge-visible Opening the challenge pop-up window () => void
    challenge-hidden Closing the challenge pop-up window () => void
    network-error A network error occurred () => void
    javascript-error A critical JS error occurred (error: { filename: string, message: string,
    col: number, line: number }) => void
    success Successful user validation (token: string) => void
    token-expired Invalidated verification token () => void

  • callback: Handler function:

    UnsubscribeFunction = () => void;

Warning

javascript-error indicates a critical failure in the JavaScript operation. Notify the user about this issue through the application interface. When such an error occurs, you cannot consider the job successfully completed, as it could potentially create a vulnerability in your application.

Here is a possible use case:

<div id="container"></div>

<script
  src="https://smartcaptcha.cloud.yandex.ru/captcha.js?render=onload&onload=onloadFunction"
  async
  defer
></script>

<script>
  function onloadFunction() {
    if (window.smartCaptcha) {
      const container = document.getElementById('container');
      const widgetId = window.smartCaptcha.render(container, {
        /* params */
      });

      const unsubscribe = window.smartCaptcha.subscribe(
        widgetId,
        'challenge-visible',
        () => console.log('challenge is visible')
      );
    }
  }
</script>
Example of embedding the widget
<form>
  <div id="captcha-container"></div>
  <button id="smartcaptcha-demo-submit" disabled="1">Submit</button>
</form>

<script
  src="https://smartcaptcha.cloud.yandex.ru/captcha.js?render=onload&onload=smartCaptchaInit"
  defer
></script>

<script>
  function callback(token) {
    console.log(token);
    if (token) {
      document
        .getElementById('smartcaptcha-demo-submit')
        .removeAttribute('disabled');
    } else {
      document
        .getElementById('smartcaptcha-demo-submit')
        .setAttribute('disabled', '1');
    }
  }

  function smartCaptchaInit() {
    if (!window.smartCaptcha) {
      return;
    }

    window.smartCaptcha.render('captcha-container', {
      sitekey: '<client_part_key>',
      callback: callback,
    });
  }

  function smartCaptchaReset() {
    if (!window.smartCaptcha) {
      return;
    }

    window.smartCaptcha.reset();
  }

  function smartCaptchaGetResponse() {
    if (!window.smartCaptcha) {
      return;
    }

    var resp = window.smartCaptcha.getResponse();
    console.log(resp);
    alert(resp);
  }
</script>
Previous
Challenge options
Next
CAPTCHA keys