Как начать работать с Yandex SmartCaptcha
Yandex SmartCaptcha — сервис защиты от ботов и автоматизированных атак.
Чтобы добавить капчу на свою HTML-страницу:
- Создайте капчу в Yandex Cloud.
- Скопируйте ключи на странице с информацией о капче.
- Добавьте код виджета капчи в свою HTML-страницу.
- Проверьте ответ пользователя с помощью отправки POST-запроса.
Если не получается настроить SmartCaptcha:
- Для Бизнес и Премиум тарифов поддержки — обратитесь в поддержку
. - В других случаях обратитесь к аккаунт-менеджеру для связи со специалистами сервиса.
Перед началом работы
- Перейдите в консоль управления
. Войдите в Yandex Cloud или зарегистрируйтесь, если вы еще не зарегистрированы. - На странице Yandex Cloud Billing
убедитесь, что у вас подключен платежный аккаунт, и он находится в статусеACTIVEилиTRIAL_ACTIVE. Если платежного аккаунта нет, создайте его.
Создайте капчу
Примечание
Чтобы сделать вашу защиту более эффективной, мы используем информацию об HTTP-запросах для развития моделей машинного обучения (ML). Вы можете отключить использование этой информации в консоли управления
-
В консоли управления
выберите каталог. -
Перейдите в сервис Yandex SmartCaptcha.
-
Нажмите кнопку Создать капчу.
-
Введите имя капчи, например
sm-captcha. -
Укажите список сайтов, на которых будет размещаться капча. Например,
my-shop.com. -
Внешний вид оставьте без изменений.
-
Выберите параметры капчи по умолчанию (или оставьте текущие):
- Основное задание — будет показано пользователю первым.
- Дополнительное задание — будет показано, если результат выполнения основного задания кажется сервису подозрительным или если выбран максимальный уровень сложности.
- Выберите сложность —
Средняя.
Можно добавить варианты заданий и настроить правила для входящего трафика, чтобы показывать разную капчу разным пользователям. В этом примере будет добавлена только одна капча по умолчанию для всех пользователей.

-
Нажмите кнопку Создать.
Получите ключи капчи
После создания капчи выберите ее в списке и скопируйте два ключа:
- Ключ клиента — для добавления виджета SmartCaptcha на ваш сайт или страницу.
- Ключ сервера — для проверки ответа пользователя.
Сохраните их в безопасном месте.

Добавьте виджет на страницу
Добавьте виджет автоматическим методом:
-
Подключите JS-скрипт к вашей HTML-странице. Для этого разместите в любом месте страницы (например, внутри тега
<head>) код:<script src="https://smartcaptcha.cloud.yandex.ru/captcha.js" defer></script>Скрипт
captcha.jsавтоматически найдет всеdivс классомsmart-captchaи установит в них виджет. -
Добавьте на страницу пустой контейнер (элемент
div) для виджета капчи:<div id="captcha-container" class="smart-captcha" data-sitekey="<ключ_клиента>" ></div>Где
<ключ_клиента>— ключ, скопированный после создания капчи.Примечание
При загрузке виджет меняет высоту контейнера, в котором он находится, на
100px. Это может привести к нежелательному «скачку» верстки на странице из-за изменения высоты. Чтобы избавиться от этого «скачка», вы можете задать до загрузки виджета высоту контейнера100px.<div ... style="height: 100px"></div>
На странице появится кнопка Я не робот. Когда пользователь нажмет кнопку, сервис проверит его запрос.
Если запрос покажется подозрительным, сервис предложит пользователю пройти задание капчи.
Проверьте ответ пользователя
После проверки капчи пользователю выдается уникальный токен. Токен добавляется в HTML-страницу, в контейнер с виджетом капчи как элемент <input>:
<div id="captcha-container" class="smart-captcha" ...>
<input type="hidden" name="smart-token" value="<токен>">
...
</div>
Для проверки токена отправьте POST-запрос на адрес https://smartcaptcha.cloud.yandex.ru/validate, передав параметры в формате x-www-form-urlencoded:
secret=<ключ_сервера>&token=<токен>&ip=<IP-адрес_пользователя>
Где:
secret— ключ сервера;token— одноразовый токен, полученный после прохождения проверки;ip— IP-адрес пользователя, с которого пришел запрос на проверку токена. Этот параметр не обязателен, однако мы просим передавать IP-адрес пользователя при запросах. Это помогает улучшить качество работы SmartCaptcha.
Пример функции проверки токена:
curl -X POST https://smartcaptcha.cloud.yandex.ru/validate \
-d "secret=<ключ_сервера>" \
-d "token=<токен_из_формы>" \
-d "ip=<IP_пользователя>"
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.cloud.yandex.ru',
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);
});
// Записываем POST-данные в тело запроса
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.cloud.yandex.ru/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.cloud.yandex.ru/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")
В ответ сервис отправит JSON-объект с полями:
status— результат проверки:okилиfailed. Если проверка успешна, в JSON-объект добавляется полеhost— сайт, на котором была пройдена проверка.message— сообщение о проверке, например,Token invalid or expired.
Примеры ответов см. в разделе Валидация пользователя.
Частые вопросы
Как проверить работу капчи?
Откройте страницу с капчей в режиме инкогнито или используйте VPN — это повысит вероятность появления задания.
Как настроить внешний вид капчи?
См. раздел Расширенные настройки виджета.
Что делать, если капча не отображается?
Проверьте, что домен добавлен в список разрешенных сайтов в настройках капчи.