Безопасный scope: Это руководство применимо только к собственным или явно авторизованным QA-, staging- и production-средам. Описаны сценарии диагностики, тестирования и наблюдаемости вашей собственной CAPTCHA-интеграции — не для сторонних сайтов и не для несанкционированных workflow.
reCAPTCHA v3 возвращает score от 0.0 до 1.0 — оценку поведения пользователя в вашем собственном приложении. Это руководство описывает, как корректно интегрировать v3 в собственный backend, измерять распределение score и обеспечивать стабильный UX.
Корректные action
Каждое значимое действие должно иметь собственный action: login, signup, checkout, password_reset. Один общий action на всё приложение даёт смешанное распределение, по которому невозможно подобрать threshold.
Сбор распределения
from collections import defaultdict
scores = defaultdict(list)
def record(action: str, score: float) -> None:
scores[action].append(score)
def below(action: str, threshold: float) -> float:
values = scores.get(action, [])
if not values:
return 0.0
return sum(1 for v in values if v < threshold) / len(values)
Threshold по action
| Action | Безопасный threshold | Комментарий |
|---|---|---|
| login | 0.5 | устойчиво для известных пользователей |
| signup | 0.5–0.7 | сильнее зашумлено |
| checkout | 0.5–0.7 | важна стабильность UX |
| password_reset | 0.3–0.5 | щадящий threshold |
Fallback вместо жёсткого отказа
Если score ниже threshold — не отказывайте сразу. Включайте дополнительный шаг: reCAPTCHA v2, e-mail-подтверждение, 2FA. Это снижает риск потери легитимных пользователей.
Тестирование с CaptchaAI
Для воспроизводимых QA-сценариев в собственной staging-среде используйте CaptchaAI: получаете токен, верифицируете на собственном backend и записываете полученный score в журнал.
Логи и наблюдаемость
Структурированные логи помогают сравнивать поведение CAPTCHA между релизами и быстро находить регрессии в собственных формах:
import json, time, logging
log = logging.getLogger('captcha-qa')
def record(event: str, **fields) -> None:
payload = {'ts': time.time(), 'event': event, **fields}
log.info(json.dumps(payload, ensure_ascii=False))
Минимальный набор полей для каждой попытки: slug, captcha_type, task_id, wait_seconds, verify_status, env. Этого достаточно, чтобы построить дашборд медианы / P90 / P99 по типу CAPTCHA и по среде.
Troubleshooting
| Симптом | Что сделать |
|---|---|
| Стабильно низкий score | Проверьте action и сессию |
| Скачки распределения | Проверьте версии и инициализацию v3 |
| Много fallback-шагов | Снизьте threshold |
| Расхождение между регионами | Сегментируйте дашборд по локали |
QA-чек-лист
- Запрос отправляется только на собственные или авторизованные endpoints.
- Тестовые учётные записи, события и платежи помечены как фиктивные.
- CAPTCHA-токен проверяется на собственном backend, а не доверяется клиенту.
- Логи содержат
task_id, тип CAPTCHA, время ожидания и pass/fail. - Скрипт возвращает корректный exit code, чтобы CI мог принять решение.
FAQ
Можно ли использовать этот подход на сторонних сайтах?
Нет. Описанные сценарии применимы только к собственным или явно авторизованным средам. Для чужих ресурсов запрашивайте письменное разрешение владельца.
Что делать, если CaptchaAI вернул ошибку?
Логируйте task_id, тип CAPTCHA и текст ошибки, повторите запрос с экспоненциальной задержкой и фиксируйте долю ошибок в дашборде. Постоянный рост ошибок — повод проверить sitekey и страницу.
Как сравнивать результаты между релизами?
Сохраняйте логи в одном формате и стройте отчёт по медиане, P90 и P99 на одинаковом наборе сценариев. Сравнивайте только сопоставимые выборки в собственной среде.
Безопасные связанные руководства
- Быстрый старт CaptchaAI
- QA-тестирование CAPTCHA в авторизованных средах
- Тестирование CAPTCHA API на собственных формах
- Отладка: браузерный тест падает, API проходит
- reCAPTCHA v2 через API
- Cloudflare Turnstile через API
- GeeTest v3 через API
Стабильный UX и предсказуемый score в собственной app — начните с CaptchaAI.
