Как начать работать с Yandex SmartCaptcha

Статья создана

Обновлена 11 марта 2025 г.

Перед началом работы
Создайте капчу
Получите ключи капчи
Добавьте виджет на страницу
Проверьте ответ пользователя
Что дальше

Чтобы начать работу с сервисом:

Перед началом работы

Перейдите в консоль управления. Войдите в Yandex Cloud или зарегистрируйтесь, если вы еще не зарегистрированы.
На странице Yandex Cloud Billing убедитесь, что у вас подключен платежный аккаунт, и он находится в статусе ACTIVE или TRIAL_ACTIVE. Если платежного аккаунта нет, создайте его.

Чтобы сделать вашу защиту более эффективной, мы используем информацию об HTTP-запросах для развития моделей машинного обучения (ML). Вы можете отключить использование этой информации в консоли управления при создании капчи или позднее в ее настройках.

Консоль управления

В консоли управления выберите каталог.
Выберите сервис Yandex SmartCaptcha.
Нажмите кнопку Создать капчу.
Введите имя капчи. Требования к имени:
- длина — от 2 до 63 символов;
- может содержать строчные буквы латинского алфавита, цифры и дефисы;
- первый символ — буква, последний — не дефис.
(Опционально) Отключите проверку имени домена.
Укажите список сайтов, на которых будет размещаться капча.
Внешний вид оставьте стандартным.
Настройте капчу по умолчанию:
1. Выберите тип основного задания, которое предлагается решить пользователю.
2. Выберите тип дополнительного задания, которое предлагается решить пользователю.
3. Выберите сложность Средняя.
Вы можете добавить варианты заданий и настроить правила для входящего трафика, чтобы показывать разную капчу разным пользователям. В этом примере будет добавлена только одна капча по умолчанию для всех пользователей.
(Опционально) Включите или отключите использование информации об HTTP-запросах для улучшения моделей машинного обучения в разделе Обучение ML-моделей.
Нажмите кнопку Создать.

Получите ключи капчи

Консоль управления

В консоли управления выберите каталог.
Выберите сервис Yandex SmartCaptcha.
Нажмите на имя капчи или создайте новую капчу.
На вкладке Обзор скопируйте значения полей Ключ клиента и Ключ сервера.

screen04

С помощью ключа клиента вы можете добавить виджет SmartCaptcha на свою страницу. Ключ сервера потребуется для проверки ответа пользователя.

Добавьте виджет автоматическим методом:

Подключите JS-скрипт к странице пользователя. Для этого разместите в любом месте страницы (например, внутри тега <head>) код:
```
<script src="https://smartcaptcha.yandexcloud.net/captcha.js" defer></script>
```
Скрипт captcha.js автоматически найдет все div с классом smart-captcha и установит в них виджет.
Добавьте на страницу пустой контейнер (элемент div), чтобы скрипт captcha.js загрузил в него виджет:
```
<div
    id="captcha-container"
    class="smart-captcha"
    data-sitekey="<ключ_клиента>"
></div>
```
Примечание
При загрузке виджет меняет высоту контейнера, в котором он находится, на 100px. Это может привести к нежелательному «скачку» верстки на странице из-за изменения высоты. Чтобы избавиться от этого «скачка», вы можете задать до загрузки виджета высоту контейнера 100px.
```
<div ... style="height: 100px"></div>
```

На странице отобразится кнопка Я не робот. Сервис проверит запрос пользователя, когда он нажмет кнопку. Если запрос покажется подозрительным, сервис предложит пользователю решить задание.

Проверьте ответ пользователя

После проверки пользователю выдается уникальный токен. Токен загружается в элемент <input type="hidden" name="smart-token" value="<токен>" внутри контейнера с виджетом. Например, так:

<div id="captcha-container" class="smart-captcha" ...>
    <input type="hidden" name="smart-token" value="<токен>">
    ...
</div>

Для проверки токена нужно отправить POST-запрос на адрес https://smartcaptcha.yandexcloud.net/validate, передав параметры в формате x-www-form-urlencoded:

secret=<ключ_сервера>&token=<токен>&ip=<IP-адрес_пользователя>

Где:

secret — ключ сервера;
token — одноразовый токен, полученный после прохождения проверки;
ip — IP-адрес пользователя, с которого пришел запрос на проверку токена. Этот параметр не обязателен, однако мы просим передавать IP-адрес пользователя при запросах. Это помогает улучшить качество работы SmartCaptcha.

В ответ сервис отправит JSON-объект с полями status и message. Когда поле status принимает значение ok, в JSON-объект добавляется поле host. Оно показывает, на каком сайте была пройдена проверка. Примеры ответов см. в разделе Валидация пользователя.

Пример функции проверки токена:

Node.js

PHP

Python

const https = require('https'),
    querystring = require('querystring');

const SMARTCAPTCHA_SERVER_KEY = "<ключ_сервера>";


function check_captcha(token, callback) {
    const postData = querystring.stringify({
        secret: SMARTCAPTCHA_SERVER_KEY,
        token: token,
        ip: '<IP-адрес_пользователя>', // Способ получения IP-адреса пользователя зависит от вашего фреймворка и прокси.
    });

    const options = {
        hostname: 'smartcaptcha.yandexcloud.net',
        port: 443,
        path: '/validate',
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Content-Length': Buffer.byteLength(postData),
        },
    };

    const req = https.request(options, (res) => {
        let content = '';

        res.on('data', (chunk) => {
            content += chunk;
        });

        res.on('end', () => {
            if (res.statusCode !== 200) {
                console.error(`Allow access due to an error: code=${res.statusCode}; message=${content}`);
                callback(true);
                return;
            }

            try {
                const parsedContent = JSON.parse(content);
                callback(parsedContent.status === 'ok');
            } catch (err) {
                console.error('Error parsing response: ', err);
                callback(true);
            }
        });
    });

    req.on('error', (error) => {
        console.error(error);
        callback(true);
    });

    // Write the POST data to the request body
    req.write(postData);
    req.end();
}


let token = "<токен>";
check_captcha(token, (passed) => {
    if (passed) {
        console.log("Passed");
    } else {
        console.log("Robot");
    }
});

define('SMARTCAPTCHA_SERVER_KEY', '<ключ_сервера>');

function check_captcha($token) {
    $ch = curl_init("https://smartcaptcha.yandexcloud.net/validate");
    $args = [
        "secret" => SMARTCAPTCHA_SERVER_KEY,
        "token" => $token,
        "ip" => "<IP-адрес_пользователя>", // Нужно передать IP-адрес пользователя.
                    // Способ получения IP-адреса пользователя зависит от вашего прокси.
    ];
    curl_setopt($ch, CURLOPT_TIMEOUT, 1);
    curl_setopt($ch, CURLOPT_POST, true);    
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($args));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $server_output = curl_exec($ch); 
    $httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpcode !== 200) {
        echo "Allow access due to an error: code=$httpcode; message=$server_output\n";
        return true;
    }
 
    $resp = json_decode($server_output);
    return $resp->status === "ok";
}

$token = "<токен>"; //Например, $_POST['smart-token'];
if (check_captcha($token)) {
    echo "Passed\n";
} else {
    echo "Robot\n";
}

import requests
import sys
import json

SMARTCAPTCHA_SERVER_KEY = "<ключ_сервера>"

def check_captcha(token):
    resp = requests.post(
       "https://smartcaptcha.yandexcloud.net/validate",
       data={
          "secret": SMARTCAPTCHA_SERVER_KEY,
          "token": token,
          "ip": "<IP-адрес_пользователя>"   # Способ получения IP-адреса зависит от вашего фреймворка и прокси.
                                            # Например, во Flask это может быть request.remote_addr
       },
       timeout=1
    )
    server_output = resp.content.decode()
    if resp.status_code != 200:
       print(f"Allow access due to an error: code={resp.status_code}; message={server_output}", file=sys.stderr)
       return True
    return json.loads(server_output)["status"] == "ok"

token = "<токен>"  # Например, request.form["smart-token"]
if check_captcha(token):
    print("Passed")
else:
    print("Robot")

Что дальше

Узнайте больше о методах подключения виджета SmartCaptcha.

Как начать работать с Yandex SmartCaptcha

Перед началом работыПеред началом работы

Создайте капчуСоздайте капчу

Получите ключи капчиПолучите ключи капчи

Добавьте виджет на страницуДобавьте виджет на страницу

Проверьте ответ пользователяПроверьте ответ пользователя

Что дальшеЧто дальше

Была ли статья полезна?

Перед началом работы

Создайте капчу

Получите ключи капчи

Добавьте виджет на страницу

Проверьте ответ пользователя

Что дальше