常驻浮球与游戏账号中心

H5 SDK v0.6.0 提供 mountGameOverlay()，在真实游戏里挂载浮球和完整的平台中心首页。首页展示当前账号、可用权益及功能入口，再进入账号安全、订单、消息、客服等二级页面。它与登录卡片 mountAuth() 是两个生命周期：登录卡片属于登录路由，浮球属于常驻游戏壳。

v0.5.0 已有远程登录卡片，但没有游戏内浮球挂载接口。只升级服务器或只调用 mountAuth() 都不会让游戏中出现浮球；首次需升级 v0.6.0 并在游戏壳增加下面的挂载。

一次接入，按游戏状态显示

import type {SessionResponse} from '@starlight/sdk';
import {sdk} from './sdk';

// 在常驻游戏壳初始化一次，container 省略时为 document.body。
const overlay = sdk.mountGameOverlay(document.body, {
  visible: false,
  uiMode: 'remote',
  onUiStatus: ({state, version}) => {
    // 可显示连接状态或记录脱敏诊断信息，不能据此判断玩家已登录。
    showGameUiStatus(state, version);
  },
  onSwitchAccount: async () => {
    // SDK 已先退出平台账号并尝试远端撤销。
    try { await closeGameBusinessSession(); }
    finally {
      clearGameIdentityAndRoleCache();
      goToLoginRoute();
    }
  },
});

// 供登录成功与刷新恢复共用，必须先完成游戏自己的会话恢复。
async function enterWithPlatformSession(session: SessionResponse) {
  overlay.setVisible(false);
  await restoreGameBusinessSession(session);
  await enterServerAndRoleFlow();
  overlay.setVisible(true);
}

export async function bootGame() {
  const restored = await sdk.restoreSession();
  if (restored) await enterWithPlatformSession(restored);
  else goToLoginRoute();
}

// 登录路由 mountAuth 的 onAuthenticated 调用 enterWithPlatformSession。
// 网络恢复失败应显示错误和重试，不能只凭本地缓存显示浮球。

上面的 restoreGameBusinessSession、角色流程和路由函数由游戏提供；SDK 不会自动恢复你的游戏业务会话或存档。visible:false 是默认值。即使设为 true，没有有效平台会话时浮球仍隐藏；宿主应再以“游戏业务登录完成”为显示条件。

常驻位置与销毁

游戏常驻壳
  ├─ 一个 SDK 实例
  ├─ 一个 mountGameOverlay 句柄
  └─ 游戏路由
       ├─ 登录页：mountAuth → 离开时销毁登录卡片
       ├─ 选服/角色：由宿主决定浮球显示时机
       └─ 游戏场景：浮球和账号中心继续存在

不要把 overlay 写在登录页面组件里，否则登录完成后页面卸载会同时移除浮球。也不要在每次切换场景时反复挂载一份浮球。

中心采用相对浏览器视口固定定位的独立面板，不占用或嵌套原游戏登录卡片的排版。桌面左侧面板宽 430px，移动端宽 390px，实际最大宽度为 calc(100vw - 24px)；面板打开时浮球隐藏，关闭后恢复。挂载到 document.body 可避免游戏局部布局、裁剪和缩放干扰。

整个游戏壳卸载、嵌入游戏实例关闭或切换到不同 App ID 时调用：

overlay.setVisible(false);
overlay.destroy();

destroy() 取消远程加载、移除 UI、订阅和计时器。迟到请求不能再次挂载。它不等于退出账号或永久注销；需要退出时执行 sdk.logout()，永久注销仍走独立的身份核验和资料处理流程。

参数与返回值

参数	默认及行为
container	document.body；选用不会随普通游戏路由销毁的节点
visible	false，等平台与游戏登录都完成后开启
uiMode	remote；bundled 显式使用随包备用 UI
onUiStatus	`{state:'loading'
onSwitchAccount	SDK 尝试 logout 后在 finally 中调用，宿主必须清理游戏会话并返回登录
onSupport	可选；接管点击客服的动作。不传时调用 SDK openSupport()

调用同步返回：

方法	行为
setVisible(boolean)	调整可见许可；远程加载中也可调用，挂载后使用最新状态
openCenter(view?)	默认 home 平台中心；支持 account、orders、messages、support 等二级页面；需可见且有有效会话
destroy()	幂等销毁，不撤销账号或删除数据

也可继续使用 sdk.showFloating()、sdk.hideFloating()、sdk.openCenter(view)；前提是已挂载 overlay 接收相关事件。事件本身不会在尚未集成 overlay 的旧游戏里生成 DOM。

当前面板内容

面板	真实数据与操作
平台中心首页 home	当前账号摘要、真实权益数据、功能快捷入口，默认打开此页
账号安全	当前用户名、脱敏手机、修改密码、登录设备、退出其他指定设备
订单记录	当前账号在当前游戏的订单列表与状态；不是自动收款或商城
消息	游戏/账号消息与标记已读
客服	以当前游戏身份打开专属客服页面，或调用宿主 onSupport
礼包 / 优惠券 / 钱包 / 会员	分别由 giftsEnabled、couponsEnabled、walletEnabled、membershipEnabled 控制，读取当前账号真实数据
游戏商城	存在符合条件的 game_item 商品时才显示入口；并不因此接通真实支付供应商

页面通过实际 SDK 接口读取数据，显示加载、空数据、失败和刷新状态。首页延续演示中心的完整布局，但入口由实际配置与数据决定：auth.testing 测试身份隐藏礼包、优惠券、钱包、会员、商城等资产入口。浮球与面板不会因为演示有钱包或商品图就自动开放实际资产能力。真实短信、支付、游戏角色及测试账号限制仍由服务端执行。

切换账号必须清理两份会话

玩家点击切号后先看到确认，确认后 SDK 执行顺序为：

1. sdk.logout() 立即清除平台本地身份并尝试撤销服务端会话。
2. 无论远端撤销成功或失败，都在 finally 中调用 onSwitchAccount。
3. 游戏清理自己的登录状态、网络连接与角色缓存，再返回登录路由。

不要只在 SDK logout 请求成功时才清理游戏；网络失败时旧角色也不应继续冒充已登录身份。若外部代码主动调用 sdk.logout()，宿主同样必须处理游戏退出；不要假定 overlay 的切号回调会覆盖所有外部退出路径。

远程更新与回退

账号卡片和常驻 overlay 使用同平台的 /api/sdk/account-ui/manifest?appId=... 清单。清单含协议版本、UI 版本、摘要与不可变模块 URL；加载器验证 SHA-256 后加载 ESM。v0.6.0 UI 模块额外导出 createGameOverlay，不会把只有 createAuthView 的旧模块误当成完整中心。

远程失败、摘要不符、协议不兼容或没有 overlay 工厂时回退 bundled UI。CSP 若不允许必要模块加载，应调整宿主的精确策略或使用 bundled 模式；不要通过允许任意来源脚本解决问题。状态回调报告 fallback，不谎称已加载平台新版本。

平台发布兼容 UI 后，游戏下次挂载可加载新版本，不需为每次样式或交互更新换游戏包。加载器、SDK 核心能力、PKCE、游戏会话协议、原生桥接或设备权限变化仍可能需要游戏重新适配。H5 远程界面不表示 Android、iOS、Windows 编译代码可以全部远程更新。

必测场景

• 全新登录进入游戏后浮球显示，点开面板取到本人当前游戏数据。
• 刷新页面先验证平台会话和游戏业务会话，完成后恢复浮球。
• 登录页只有登录卡片，不叠加旧表单；登录页卸载不销毁常驻 overlay。
• 远程失败回退仍可操作，加载过程中退出不会迟到重挂。
• 账号过期/切号后旧面板隐藏，迟到数据不显示为新账号内容。
• 切号时模拟平台撤销网络失败，游戏仍完成自身退出。
• 手机拖动、靠边、点击、页面滚动、软键盘、关闭与焦点正常；不遮挡游戏关键按钮。

继续阅读远程账号加载器、注册与手机绑定和会话恢复。