阅读主题
登录与授权排查
先区分失败发生在开发者登录、玩家登录、游戏服务器交换还是游戏自己的会话建立阶段。记录 HTTP 状态和错误 code，不要复制密码、验证码、令牌或服务端密钥。
常见错误
| 现象或错误 | 检查与处理 |
|---|---|
APP_UNAVAILABLE | 在控制台检查应用和开发者状态。待审、停用或扩端后的复审期间不开放登录与兑换 |
APP_NOT_FOUND | 核对实际客户端 App ID，不能把逻辑游戏 ID 直接当作 App ID |
INVALID_GAME_KEY | 由游戏服务器检查对应应用密钥，尤其是最近轮换后是否仍使用旧配置 |
INVALID_AUTH_CODE | 检查 code 是否过期、已兑换、App ID/verifier 不匹配；重新开始一次完整登录 |
INVALID_CREDENTIALS | 确认账号类型和密码。玩家、开发者和运营账号分别登录各自入口 |
INVALID_SMS_CODE | 确认号码、验证码挑战、有效期与用途；登录验证码不能用于重置密码 |
SESSION_EXPIRED | 会话过期或已撤销，清理旧身份后重新登录 |
RATE_LIMITED | 停止自动重试，等待限流窗口恢复；不要无限循环请求验证码或密码登录 |
SESSION_CHANGED | 新登录、退出或切号使旧请求失效；忽略旧结果，不恢复旧账号 |
授权交换失败
正确流程是客户端取得 { appId, code, codeVerifier }，交给自己的游戏服务器，再由服务器携带 X-API-Key 兑换。
- 确认应用已批准、App ID 对应正确客户端。
- 确认游戏服务器请求的是
/api/server/auth/exchange，而不是演示快捷入口。 - 确认 SDK 返回的原始 verifier 和 code 没被截断、替换或从另一登录事务拼接。
- 授权码只有 60 秒且仅能成功兑换一次。重复点击不能反复兑换同一 code。
- 若服务器已经兑换但响应丢失，按游戏后端设计查询/恢复该业务结果，或重新发起完整登录，不伪造成功。
新应用不能调用 /api/demo/game/session。把密钥塞进客户端来绕过这一步会破坏信任边界。
H5 页面问题
无界面 SDK 的登录接口不会自行生成完整登录框。宿主应渲染表单并订阅 SDK 事件。使用 HTTPS 或 localhost 安全上下文，并检查浏览器是否具备 Web Crypto、Fetch、structuredClone。
跨域失败时核对实际浏览器 Origin 与平台允许的来源；localhost、127.0.0.1 和不同端口属于不同 Origin。不要通过关闭来源校验解决问题。
刷新不保持登录时，确认已显式传入 sessionStorage 适配器并调用 restoreSession()。默认内存会话刷新即失去；缓存只作为候选，网络错误不等于已登录。清理候选前先区分服务端撤销和临时网络故障。
Android 回调问题
使用 completeGameLogin(authorization, response) 并传回该次登录的原始 Authorization。单参数旧入口无法绑定取消状态，不应用来完成新接入。关闭登录或 Activity 销毁后的旧网络结果应被忽略。
首次集成采用每 Activity 创建 SDK、销毁时 destroy() 并清空引用的策略。detachActivity() 不会替换构造时的 Listener，不能据此把保留旧 Activity 的 SDK 放进全局单例。
iOS 候选恢复或退出异常
前台 login() 未完成时，restoreSession() 返回 nil，不会从 Keychain 抢先恢复旧身份。保持登录进度并处理当前登录任务结果，不把这次 nil 当作一次新的退出。403 ACCOUNT_RESTRICTED / APP_UNAVAILABLE 会终止候选恢复或对应业务会话，应先确认账号限制、应用审核状态。
Keychain 删除失败会报告 STORAGE_ERROR；当前实例清空内存并阻止恢复，但新实例仍可能读到设备残留记录。退出同时断网时还需确认服务端撤销，不应直接新建 SDK 忽略错误。详见iOS 会话与生命周期。
跨端角色不一致
确认 H5、Android、iOS App ID 属于同一逻辑游戏，且使用同一玩家账号。平台 gameUserId 一致后，存档差异仍需检查游戏自己的区服、角色与存档映射。