GPG登录报Out of box error需经UIflow重认证问题排查

问题表现 #

在自研Android游戏内登录Google Play Games时触发报错：
Out of box error detected; the user must reauthenticate through the UIflow.
该应用此前可正常对接Google Play服务，问题在最新构建版本首次出现，项目集成的是C++版本gpg-cpp-sdk_3.1 SDK。
登录流程中可看到系统弹出显示「Hey there, gamertag」「Level 16」的欢迎通知，说明账号曾短暂登录成功，但随即被强制登出，对应运行日志如下：

V  Play Games callback indicates connection.
I  Successfully connected to Google Play.
V  WelcomeBack Notification UI should be displayed by GMSCore.
V  ApplicationMetadataCache is not being seeded; this is normal on non-iOS platforms.
I  Sign in finished with a result VALID
I  OnAuthActionFinished
I  You are logged in!
V  PlayerLevelCache is not being seeded; this is normal on Android.
V  Automatically seeded event cache.
E  Out of box error detected; the user must reauthenticate through the UIflow.

已知前置条件 #

• 当前测试使用debug构建包，已确认GPG（Google Play Games）同时支持debug、release构建，两类签名密钥均已上传至Google Play Console
• 本次构建仅升级Android Studio版本后重新编译项目，未对业务源码做重大修改
• 复现规律：问题仅在小米Mi A3真机上出现，模拟器环境无法复现

排查解决步骤 #

1. 清理GMS相关应用本地缓存
   该报错本质是GMSCore返回的开箱校验失败，通常由本地残留的无效授权态触发。小米系统对GMS应用的后台数据管控策略更严格，极易出现授权缓存错乱问题。
   操作路径：进入设备应用管理，分别找到「Google Play服务」「Google Play游戏」两个应用，清除二者的全部缓存与本地存储数据，重启设备后重新尝试登录。
2. 校验当前构建包的实际签名
   升级Android Studio后，debug构建的默认签名配置可能被重置为IDE自带的默认debug密钥，而非之前上传到Play Console的自定义debug密钥，不要信任IDE的签名配置预览，直接对最终产出的apk做签名校验：
   执行命令：keytool -printcert -jarfile <你的debug安装包文件路径>.apk
   对比输出的SHA1指纹与Play Console中登记的debug签名指纹，确保二者完全一致。
3. 显式调用带UI交互的授权流程
   暂时关闭静默自动登录逻辑，首次触发登录时强制调用带前台UI的登录接口，让用户手动走完账号选择、授权确认的完整流程。小米系统的权限管控会拦截后台静默发起的授权请求，只有前台可见的完整UI授权流才能通过OOB校验，完成一次有效授权后，后续自动登录即可恢复正常。
4. 校验设备端GMSCore版本
   确认小米Mi A3上安装的Google Play服务为官方最新正式版，部分老旧定制版GMSCore与3.1版本gpg-cpp-sdk存在OOB校验逻辑兼容问题，升级GMSCore到最新版后即可修复。

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