验证用户的响应

本页介绍了如何从应用的后端验证用户对 reCAPTCHA 质询的响应。

对于 Web 用户，您可以通过以下三种方式之一获取用户的响应令牌：

  • g-recaptcha-response POST 参数（当用户在您的网站上提交表单时）
  • 用户完成 reCAPTCHA 验证后的 grecaptcha.getResponse(opt_widget_id)
  • 作为回调函数的字符串参数（如果在 g-recaptcha 标记属性中或在 grecaptcha.render 方法中的回调参数中指定了 data-callback）

对于 Android 库用户，您可以调用 SafetyNetApi.RecaptchaTokenResult.getTokenResult() 方法在状态返回成功时获取响应令牌。

令牌限制

每个 reCAPTCHA 用户响应令牌的有效期为两分钟，只能验证一次， 从而防止重放攻击如果您需要新令牌，可以重新运行 reCAPTCHA 验证。

获得响应令牌后，您需要在两分钟内通过 reCAPTCHA 使用 以下 API 来确保令牌有效。

API 请求

URL：https://www.google.com/recaptcha/api/siteverify

方法：POST

POST 参数 说明
secret 必需。您的网站与 reCAPTCHA 之间的共享密钥。
response 必需。您网站上的 reCAPTCHA 客户端集成提供的用户响应令牌。
remoteip 可选。用户的 IP 地址。

API 响应

响应是一个 JSON 对象：

{
  "success": true|false,
  "challenge_ts": timestamp,  // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
  "hostname": string,         // the hostname of the site where the reCAPTCHA was solved
  "error-codes": [...]        // optional
}

对于 reCAPTCHA Android：

{
  "success": true|false,
  "challenge_ts": timestamp,  // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
  "apk_package_name": string, // the package name of the app where the reCAPTCHA was solved
  "error-codes": [...]        // optional
}

错误代码参考

错误代码 说明
missing-input-secret 缺少 Secret 参数。
invalid-input-secret Secret 参数无效或格式错误。
missing-input-response 缺少响应参数。
invalid-input-response 响应参数无效或格式错误。
bad-request 请求无效或格式错误。
timeout-or-duplicate 响应不再有效：过旧或以前使用过。