Android端reCaptcha Enterprise生成Token超时问题求助

一、排查网络基础问题 #

• 确认用户网络环境：弱网、VPN/代理、地区网络限制都可能导致reCaptcha请求超时，需引导用户切换稳定网络测试
• 检查应用权限：确保AndroidManifest.xml中已添加<uses-permission android:name="android.permission.INTERNET" />，Android 10+需确认网络安全配置未限制google.com或recaptcha.net域名
• 验证域名连通性：测试应用能否访问recaptcha.net（reCaptcha备用域名，部分地区访问更稳定）

二、自定义SDK超时配置 #

18.0.1版本的reCaptcha支持通过RecaptchaClientOptions调整超时时间，默认5秒过短，可延长至8-12秒：

// 初始化时配置超时
RecaptchaClientOptions options = new RecaptchaClientOptions.Builder()
    .setTimeoutMillis(10000) // 设置10秒超时
    .build();
RecaptchaTasksClient recaptchaTasksClient = Recaptcha.getTasksClient(context, YOUR_SITE_KEY, options);

三、添加重试机制 #

针对超时异常增加有限重试，避免单次网络波动导致失败：

private int retryCount = 0;
private static final int MAX_RETRY_TIMES = 2;

private void runRecaptchaTask(CaptchaEvent event) {
    recaptchaTasksClient.executeTask(getCaptchaAction(event))
        .addOnSuccessListener(token -> {
            retryCount = 0; // 重置重试计数
            if (context != null) {
                ((RecaptchaTokenListener) context).onSuccess(event, token);
            }
        })
        .addOnFailureListener(e -> {
            // 判断是否为超时异常且未达最大重试次数
            if (e instanceof TimeoutCancellationException && retryCount < MAX_RETRY_TIMES) {
                retryCount++;
                runRecaptchaTask(event);
            } else {
                retryCount = 0;
                if (context != null) {
                    ((RecaptchaTokenListener) context).onFailure();
                }
            }
        });
}

四、检查配置与更新SDK #

• 验证Site Key配置：确保Google Cloud控制台中，reCaptcha Enterprise已绑定应用的包名和SHA-1指纹
• 更新SDK版本：18.0.1可能存在已知超时bug，替换为最新稳定版（例如com.google.android.recaptcha:recaptcha:18.3.0，以maven仓库最新版本为准）
• 检查云服务状态：在Google Cloud控制台确认reCaptcha Enterprise服务正常、配额充足

五、优化异常处理与日志 #

• 区分异常类型：在onFailure中判断异常，针对超时场景给用户提示“网络不稳定，请稍后重试”，而非统一失败提示
• 收集排查日志：记录异常信息、用户网络类型（Wi-Fi/移动数据）、运营商等，便于后续定位问题

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