原生 SDK 登录界面、交互体验与多语言规范（设计约定）
状态：2026-10-26 需求已确认、源码与完整测试仍待实施。本页约束 Android / iOS ROSDK 中所有可能出现 UI 或面向用户提示的模块。它不代表 Firebase Auth 或登录 UI 已经构建、发布或在真机通过。
目标及边界
Firebase 提供通用 Firebase User/UID/ID Token、会话与凭证认证；为保证体验，ROSDK 另外提供按需选装的原生登录选择界面和交互协调层。它不访问游戏服务端、不实现 auth.Auth、不兑换游戏 account/token、不处理角色或游戏数据合并、不依赖 Egret/SDKManager/SDKDelegate。
模块候选：Android auth-firebase + 可选 auth-firebase-ui；iOS ROAuthFirebase + 可选 ROAuthFirebaseUI。是否采用这些最终制品名以实现时的模块规范为准。认证 Core 不引入 UI、Google、Apple 的强制依赖；UI 模块不依赖 Egret，不绑定所有 Provider。 每个游戏仅组合实际需要的模块及授权处理器；宿主负责向游戏既有协议映射结果。现有 Google / Apple 登录模块继续独立可用。
登录方式配置
与 roweb-sdk 的 FirebaseLoginMethods 位值保持语义一致，以便阅读配置，但 Web Provider 已列出不表示原生已接入。
| 位值 | 登录方式 | Android / iOS 当前状态 |
|---|---|---|
| 1 | 待在 Firebase Core + 对应授权处理器中实现并验收 | |
| 2 | 待实现，不显示空按钮 | |
| 4 | GitHub | 待实现，不显示空按钮 |
| 8 | Twitter/X | 待实现，不显示空按钮 |
| 16 | Microsoft | 待实现，不显示空按钮 |
| 32 | Yahoo | 待实现，不显示空按钮 |
| 64 | Apple | 待按平台身份流程实现并验收 |
| 128 / 256 | Email / Phone | Web 预留位；原生需专用输入 UI，不视为完成 |
| 512 | Anonymous（游客） | 待基于 signInAnonymously 实现并验收 |
| 1024 及以上 | Play Games、Game Center、OIDC、SAML 等 | Web 预留位；按能力单独提 Issue、实现、测试 |
可见方法 = 宿主配置允许 ∩ 当前 OS / 宿主条件允许 ∩ 有已注册且可工作的授权处理器。如果没有可用方式，显示可本地化的“当前没有可用登录方式”并向调用方返回明确错误，不展示无法点击的假入口。支持自定义展示顺序、名称和品牌合规布局；游戏不必安装全量 Provider。
建议配置模型（示意，不是已有源码）：
FirebaseLoginUIOptions
loginMethods: 位掩码
preferredOrder: 登录方式数组（未设置则默认顺序）
showCachedAccount: true
autoContinueSeconds: 0（默认关闭；游戏可设置如 3）
allowSwitchAccount: true
showAnonymousWarning: true
providerHandlers: 每个方法对应独立授权能力回调
language: SYSTEM（当前固定策略；不接收 Egret 游戏语言）Core 提供 signInWithCredential、linkWithCredential、reauthenticate、signInAnonymously、getIdToken(forceRefresh)、状态监听、退出及明确错误结果；可选 UI 只协调授权按钮与 Core API。Google / Apple 原生 SDK 返回的 Google/Apple 身份凭证 不是 Firebase ID Token。iOS Google Firebase 凭证需使用 ID Token + Access Token，不可把 serverAuthCode 当 Access Token；Apple 必须保存 raw nonce，向 Apple 请求提交 SHA256(raw nonce)，向 Firebase 构建凭证使用 raw nonce，首次授权姓名在可用时传递。Android Apple 网页一次性游戏后端 code 不可直接冒充 Firebase 身份凭证，需使用 Firebase 官方支持的 Apple OAuth 授权路径并正确恢复 pending result。
原生登录界面与流程状态
- 初始：Firebase 初始化并监听认证状态；无缓存账号展示可用 Provider；已有 Firebase User 展示非敏感账号摘要、“继续”、“切换账号”。缓存令牌应通过
getIdToken重新确认，不凭 UID 就向游戏报告成功。倒计时自动继续仅当宿主显式启用，且可被用户取消。 - 授权：用户明确点击 Provider 按钮 → 进入
AUTHORIZING→ 阻止重复提交 → 显示带取消语义的 Loading → 唤起授权界面 → 获得 provider 原始凭证 →FIREBASE_AUTHENTICATING→ 获取 Firebase User + ID Token →SUCCEEDED。绑定/重认证使用独立模式，绝不误调用新登录造成匿名 UID 被替换。 - 失败：明确区分用户取消、无网络、超时、提供方不可用、Firebase 配置错误、凭证冲突、匿名账号链接冲突、需要最近重新登录和未知错误。展示面向用户的本地化提示、允许重试/切换方式；原始异常码作为开发诊断交给回调，不直接显示给普通用户。
- Loading/遮罩：只阻拦 SDK 自己当前 UI 的重复触摸，不锁死操作系统/游戏主线程；在失败、取消、成功、窗口销毁和生命周期中断时释放。超时表示 UI 不再等待，不等于第三方请求已取消；迟到回调必须去重且不能多次完成；Firebase 状态如已变化应正确通知监听者。授权系统 UI 不被 SDK 遮罩盖住。
- 安全：不记录 ID Token、授权码、完整邮箱和用户机密；可记录脱敏错误码、阶段与耗时。切换账号须有清晰提示，不能默默抹掉正在使用的匿名身份或未保存游戏进度。账号合并仅由游戏后端决定。
建议状态：IDLE → CHOOSING / CACHED_ACCOUNT → AUTHORIZING → FIREBASE_AUTHENTICATING → REFRESHING_TOKEN → SUCCEEDED，并对 CANCELLED、FAILED、TIMED_OUT 提供恢复路径。登录、链接、重新认证模式应分别测试。
SDK UI 多语言规则
当前只看操作系统语言，不跟随 Egret 游戏内部语言设置。游戏即使切换至另一种语言，SDK 自己的提示、Loading、按钮仍按系统语言；两套语言可以不一致，暂不实现游戏侧统一切换。首批 en、zh、th、id，不支持的语言回退 en；扩展语言时先补齐同模块全套字符串及无障碍说明。
- Android：优先模块私有
res/values/strings.xml（英文）、values-zh、values-th、values-in或经工具链验证的印尼语资源目录，全部字符串统一rosdk_<module>_前缀。若宿主通过自定义 Locale 改写 App/进程语言，而要求严格使用系统语言，不能仅依赖 Activity 的getString；需基于真实系统语言取得模块字符串并实际测试 API 23+。不能修改固定 Egret 的资源或全局 Locale。 - iOS：每个 Pod 以
Resources/*.lproj、Localizable.strings和s.resource_bundles分发，以模块 Bundle 读取文案，不假设[NSBundle mainBundle]包含 SDK 自有语言资源；尊重系统语言列表、合理回退。iOS 的每 App 语言设置也可能影响 OS/第三方授权界面的语言。 - 所有 ROSDK 模块：支付处理中、恢复交易、账号取消、网络错误、成就提示等，只要是 SDK 主动生成的 UI/提示，就使用所在模块的本地化资源和可诊断的错误码；纯无界面模块无需引入本地化依赖或新的统一 Core。官方 Google/Apple、商店、权限系统窗口由 OS/供应商选择语言，ROSDK 无法保证逐字相同。
模块级验收及发行门槛
- 只有 Firebase Core 安装时，原有五模块与 Firebase 不互相污染依赖；不安装 UI 时不携带 UI 资源或额外 Google/Apple 依赖；UI 单独选装后至少能以匿名方式完成纯 SDK 验证。
- 按配置只显示注册完成的按钮、按钮可点击且能走到实际授权处理器；关闭模块后对应方式消失；系统不支持时明确反馈。
- Android Maven Local → 传递依赖 → 独立 D8/APK → 与已有五模块联合 APK；旧 Egret AGP 兼容性留到正式项目验收。iOS 独立 Pod lint/XCTest、联合 Simulator Release、CocoaPods 同 URL split Tag 混装与最低 iOS 验证。
- en/zh/th/id 文案覆盖及系统语言切换、未知语言回退、无障碍字体/RTL 回退、前后台切换、销毁恢复、多次点击、超时和迟到回调、授权取消/失败/重试。
- 真实 Google/Apple/Firebase Console、设备与签名、跨 Web/Android/iOS UID、游戏服务器
auth.Auth和账号映射，只在真实游戏项目完成联调。仓库 SmokeApp 通过不等于正式游戏验收。
参考：