---
name: ineed-login
description: 接入游客进入、按需登录、账号资料显示、登录返回和切换账号后的数据隔离。
---
# 登录与账号

默认允许游客体验免费内容，需要支付、账号云档或提交正式成绩时再登录；若作品已要求入口登录，保留已有策略。不能用登录成功代替购买成功。

## 需要确认

从工程找到账户按钮与免费入口。只确认尚未知的：是否允许游客、哪些动作需要账号、取消登录后怎么返回、游客存档是否提供显式导入选择。填写菜单路径和实际按钮名称，给平台[配置交接单](../../platform-handoff/SKILL.md)。

## 接入流程

1. initialize 成功后 request("account.get")。value=null 表示游客；对象使用 id 作为身份标识，nickname/avatarUrl 作显示，不以昵称作为存档主键。
2. 玩家按登录按钮时 await INeed.login()；插件 0.1.1 也可用 ensure_logged_in()：已有账号直接返回，无账号才登录。
3. 成功后重读 account.get，再取该账号商品、库存、权益、榜单资料和存档。只显示成功响应中的资料，不能预先显示“已登录”。
4. buy/consume/buy_and_consume 简写会确保登录；取消或失败直接返回错误，不继续商业动作。平台商店可先 ensure_logged_in 再 open_store。
5. 绑定 account.changed，先提高游戏自己的身份版本号、清空旧账号显示和未完成 UI，再重新读新身份数据。已发送的服务端交易可能已提交，错误不代表自动回滚。

## 同步什么、不同步什么

account.get 返回账号快照，可包含 id、nickname、avatarUrl、username、balanceCoins 等；昵称/头像为空时显示占位。账号快照随登录、商业响应及平台会话更新变化。同账号跨设备改名或余额变化不保证即时推送，account.changed 表示身份改变，不是所有资料更新通知。

不在存档里保存密码、token 或余额作为权限。不需要自己调用登录 HTTP 接口，也不把平台凭据传进 GDScript。[接口手册](../../../guides/integration/api.md)列出实际方法和字段。

## 手机、微信和 QQ

登录应由明确按钮触发。平台可能打开窗口，也可能当前页跳转并返回；两者都要验收。跳转前保存选择、关卡和待继续动作，不保存“已付费”布尔值。返回重新初始化、识别账号、加载该账号数据；未确认交易结果时不自动重买。弹窗被拦截或取消时保持免费玩法和已做选择，给出可重试登录入口。

## 验收与交付

游客 → 登录成功、取消、超时；登录前后按钮状态；A 切 B 时旧账号成绩/存档/购买结果不能落到 B；刷新能恢复正确身份；手机真实登录返回。记录环境、账号标识和时间，截图隐藏敏感信息。关联[异常与恢复](../../../guides/integration/recovery.md)、[界面建议](../../../guides/integration/ui.md)。