reCaptcha v3不可见模式下API调用次数及错误选择检测问询

一、三个场景的API调用次数统计 #

这里的API调用次数指与Google reCAPTCHA服务的交互次数：

• 场景1（直接判定为人类，无弹窗）：共2次。前端调用grecaptcha.execute()获取验证token（1次），后端将token发送到Google验证接口校验（1次）。
• 场景2（弹出验证谜题且用户通过）：共3次。前端初始调用触发风险检测（1次）；用户完成验证后，Google返回有效token（第2次）；后端校验该token（第3次）。
• 场景3（弹出验证谜题但用户选错）：共1次。仅前端初始调用触发验证弹窗的那次交互，用户验证失败后，Google不会返回有效token，后端无有效内容可提交校验，因此无后续调用。

二、追踪场景3（验证失败）的方法 #

1. 前端回调直接捕获 #

reCAPTCHA提供了错误回调机制，能直接监听验证失败事件（包括用户选错谜题、超时、操作异常等）。你可以在回调里埋点记录，或者上报到自己的统计系统：

<script src="https://www.google.com/recaptcha/api.js?render=你的站点密钥"></script>
<script>
// 方法1：通过execute的catch捕获错误
grecaptcha.ready(function() {
  grecaptcha.execute('你的站点密钥', {action: '表单提交'}).then(function(token) {
    // 拿到有效token，提交表单
    document.getElementById('your-form').submit();
  }).catch(function(error) {
    // 捕获验证失败
    console.log('验证挑战失败:', error);
    // 上报到后端统计接口
    fetch('/your-api/recaptcha-failure', {
      method: 'POST',
      headers: {'Content-Type': 'application/json'},
      body: JSON.stringify({action: '表单提交', reason: error})
    });
  });
});

// 方法2：初始化时指定error-callback
function recaptchaErrorCallback() {
  console.log('用户验证挑战未通过');
  // 这里做日志记录或统计上报
}
</script>
<!-- 配合不可见reCAPTCHA容器 -->
<div class="g-recaptcha" 
     data-sitekey="你的站点密钥" 
     data-size="invisible" 
     data-error-callback="recaptchaErrorCallback"></div>

2. 后端校验兜底判断 #

如果前端没捕获到失败，后端在处理表单时，若没有收到有效reCAPTCHA token，或者提交无效token到Google验证接口后收到success: false的响应，即可判定为验证失败（包含场景3的情况），此时可以记录该事件：

# 示例：Python后端校验逻辑
import requests

def check_recaptcha(token):
    verify_url = "https://www.google.com/recaptcha/api/siteverify"
    payload = {
        "secret": "你的密钥",
        "response": token
    }
    res = requests.post(verify_url, data=payload).json()
    if not res.get("success"):
        # 记录失败日志，可带上错误码进一步分析
        with open("recaptcha-logs.txt", "a") as f:
            f.write(f"验证失败，错误码：{res.get('error-codes')}\n")
        return False
    return True

3. 统计平台埋点（可选） #

如果用了Google Analytics或其他统计工具，可以在验证失败回调里发送自定义事件，方便后续分析失败趋势：

function recaptchaErrorCallback() {
  // 发送事件到Google Analytics
  gtag('event', 'recaptcha_failure', {
    'event_category': '表单提交',
    'event_label': '验证谜题错误'
  });
}

内容的提问来源于stack exchange，提问作者Kamal Surendra