Yandex SmartCaptcha — интеграция и управление
Yandex SmartCaptcha — сервис Yandex Cloud для защиты сайтов и приложений от ботов. Принцип работы: виджет на странице проверяет пользователя и выдаёт одноразовый токен (живёт 5 минут) → фронтенд передаёт токен на ваш бэкенд → бэкенд обязан проверить токен POST-запросом на /validate и принять решение по полю status.
Начни с docs/overview.md — как работает сервис и как выбрать способ интеграции.
Ключевые факты
| Что | Значение |
|---|---|
| Скрипт виджета | <script src="https://smartcaptcha.yandexcloud.net/captcha.js" defer></script> |
| Проверка токена | POST https://smartcaptcha.yandexcloud.net/validate (x-www-form-urlencoded: secret, token, ip) → {"status": "ok"|"failed", "message": "...", "host": "..."} |
| Токен | Одноразовый, срок жизни 5 минут; лежит в <input type="hidden" name="smart-token"> |
| При сбое сервиса | HTTP != 200 → fail-open: пропустить пользователя, залогировать |
| Ключи | Ключ клиента (ysc1_…, публичный, для виджета) и ключ сервера (ysc2_…, секрет, только на бэкенде, env SMARTCAPTCHA_SERVER_KEY) |
| React | Пакет @yandex/smart-captcha (официальный) |
| Vue 3 | Официального пакета нет — composable на расширенном методе, см. docs/vue.md |
| Управление | REST https://smartcaptcha.api.cloud.yandex.net/smartcaptcha/v1/captchas, CLI yc smartcaptcha captcha, Terraform yandex_smartcaptcha_captcha |
Выбор сценария
| Задача | Пошаговый план | Ключевые знания |
|---|---|---|
| Создать/настроить капчу в Yandex Cloud | workflows/setup-captcha.md | docs/captcha-management.md, docs/captcha-settings.md, docs/keys.md |
| Капча на обычном сайте (HTML + бэкенд) | workflows/integrate-website.md | docs/widget-auto.md, docs/server-validation.md |
| Капча в React / SPA | workflows/integrate-react.md | docs/react.md |
| Капча во Vue 3 / Nuxt | workflows/integrate-react.md (шаги те же, код — Vue) | docs/vue.md |
| Капча в мобильном приложении | workflows/integrate-mobile.md | docs/mobile-webview.md + файл платформы |
| Капча без кнопки «Я не робот» | workflows/integrate-website.md | docs/invisible-captcha.md |
| Капча не работает / пропускает ботов | — | docs/troubleshooting.md |
| Оценить стоимость и лимиты | — | docs/pricing-limits.md |
Карта знаний — docs/
Прочитай соответствующий файл до написания кода: имена параметров, поля ответов и шаги бери из него, а не по памяти.
Основы:
- docs/overview.md — принцип работы, жизненный цикл токена, таблица выбора метода интеграции.
- docs/keys.md — ключ клиента и ключ сервера: получение (консоль/CLI/API), безопасность, действия при компрометации.
Виджет на сайте:
- docs/widget-auto.md — автоматический метод:
div.smart-captcha, data-атрибуты, скрытое полеsmart-token. - docs/widget-advanced.md — расширенный метод:
?render=onload,window.smartCaptcha.render(), callback, несколько виджетов, отправка токена fetch'ем, отложенная загрузка. - docs/invisible-captcha.md — невидимая капча:
invisible: true+execute(), уведомление об обработке данных (shieldPosition/hideShield).
Серверная проверка:
- docs/server-validation.md — проверка токена на
/validate: параметры, разбор ответов, «решение только поstatus», одноразовость, fail-open, таймауты, IP за прокси.
Фреймворки и платформы:
- docs/react.md —
@yandex/smart-captcha: компонентыSmartCaptchaиInvisibleSmartCaptcha, props, события, сброс черезkey. - docs/vue.md — Vue 3 / Nuxt: composable на расширенном методе (официального пакета нет), жизненный цикл в SPA, невидимая капча как Promise, обзор community-пакетов.
- docs/mobile-webview.md — общий подход для мобильных: страница в WebView, мост в нативный код, готовая страница
smartcaptcha.yandexcloud.net, параметрwebview. - docs/mobile-android.md — Android: Kotlin,
@JavascriptInterface, обычная и невидимая капча. - docs/mobile-ios.md — iOS: WKWebView,
WKScriptMessageHandler, приём токена в Swift. - docs/mobile-flutter.md — Flutter:
webview_flutter, каналjsBridge.
Управление и настройка:
- docs/captcha-management.md — создание/обновление/удаление капчи: консоль, CLI, Terraform, REST API; роли IAM
smart-captcha.*; метрики Monitoring; аудитные логи Audit Trails; миграция условий наhost_matcher. - docs/captcha-settings.md — задания (чекбокс/слайдер; текст/силуэты/калейдоскоп), сложность, варианты заданий и правила показа по условиям трафика, метаданные (
metadata), валидация домена.
Эксплуатация:
- docs/troubleshooting.md — «симптом → причины → решение»: виджет не отображается,
Invalid or expired Token, ограниченный режим, доступность, как тестировать капчу при разработке. - docs/pricing-limits.md — тарификация (платны только
status=ok, 10 000/мес бесплатно), квоты, публичные IP сервиса.
Справочники — references/
Точные таблицы для сверки имён и значений:
- references/widget-params.md — все параметры
render()и data-атрибуты (включаяtest,webview,invisible,hideShield,metadata). - references/js-api.md — методы
window.smartCaptchaс сигнатурами и все событияsubscribeс полезной нагрузкой. - references/validate-api.md —
/validate: параметры запроса, все варианты ответов с примерами JSON, свойства токена. - references/management-api.md — REST endpoint'ы, gRPC-сервисы, команды CLI, поля Terraform-ресурса, ключи
style_json, IAM-токен, пример curl. - references/source-map.md — какой файл скилла на какой странице официальной документации основан; как обновлять знания.
Шаблоны — templates/ и утилита scripts/
Готовый код: копируй и адаптируй, а не пиши с нуля.
| Файл | Что это |
|---|---|
| templates/widget-auto.html | Страница с формой и автоматическим виджетом |
| templates/widget-advanced.html | Расширенный метод: отложенная загрузка, render, отправка токена fetch'ем |
| templates/invisible.html | Невидимая капча: execute() на submit, события token-expired/network-error |
| templates/webview-page.html | Страница для мобильного WebView (мосты Android NativeClient и iOS messageHandlers) |
| templates/validate.py | Проверка токена: Python (requests) |
| templates/validate.js | Проверка токена: Node.js 18+ (fetch, ESM) |
| templates/validate.php | Проверка токена: PHP (cURL) |
| templates/SmartCaptchaField.tsx | React-компонент обычной капчи (токен и сброс через ref) |
| templates/InvisibleCaptchaForm.tsx | React-форма с невидимой капчей (проверка по submit) |
| templates/useSmartCaptcha.ts | Vue 3 composable: синглтон-загрузка скрипта, lifecycle, невидимая капча как Promise |
| templates/smartcaptcha.d.ts | TypeScript-типы window.smartCaptcha (для Vue/vanilla TS проектов) |
| templates/validate-amphp.php | Проверка токена в event loop: PHP + AMPHP v3 (amphp/http-client) |
| templates/mock-validate.php | Локальный мок /validate для юнит/смоук-тестов (php -S), все канонические сценарии |
| scripts/check_token.py | CLI-смоук-тест: python check_token.py --secret <ключ> --token <токен>; только stdlib |
Примеры — examples/
Запускаемые фуллстек-примеры «форма + серверная проверка» (examples/README.md):
- examples/express-fullstack/ — Node.js 18+ / Express: server.js, public/index.html, package.json.
- examples/flask-fullstack/ — Python / Flask: app.py, templates/index.html, requirements.txt.
Правила работы
- Токен всегда проверяется на бэкенде. Виджет без серверной проверки
/validateне защищает ничего. Решение — только по полюstatus;message— лишь для логов. - Ключ сервера — секрет. Только переменные окружения (
SMARTCAPTCHA_SERVER_KEY) или секретница; не во фронтенд, не в репозиторий. См. docs/keys.md. - Fail-open при сбоях сервиса (HTTP != 200, таймаут ~1 с): пропусти пользователя и залогируй — иначе сбой капчи положит ваши формы.
- Уведомление об обработке данных обязательно. Скрывая блок Shield (
hideShield), обязан показать уведомление другим способом. - Не выдумывай параметры. Точные имена и значения — в references/; если чего-то нет в справочниках, сверься с официальной документацией по карте references/source-map.md.
- Тестирование: задание принудительно —
test: true(только не в проде); поведение «как незнакомый пользователь» — инкогнито/VPN; ручная проверка токена — scripts/check_token.py. Подробнее — docs/troubleshooting.md. - Выдавай запускаемое решение целиком. Кроме основного кода приложи манифесты зависимостей (
package.json,requirements.txt,composer.json), пример переменных окружения (.env.example) и написанные в ходе работы тесты/проверочные скрипты — они часть решения, а не черновик. Ориентир комплектности — examples/. - Читай по маршруту, а не всё подряд. Начни с таблицы «Выбор сценария», открой workflow и только те docs/references, на которые он ссылается: это экономит контекст и время.
Тест-кейсы скилла
evals/evals.json — 7 сценариев для проверки скилла (Express, React invisible, Flask, Terraform, Android, диагностика домена, тарификация).