用户模块

本页介绍如何通过 Playol SDK 接入用户系统、获取平台注入的用户信息、监听变更事件，并合理处理玩家身份与数据绑定关系。

Playol SDK 内置完善的用户模块，无需开发者构建注册/登录系统，即可获取平台身份、头像昵称、用户类型，并与游戏存档、道具、排行榜等信息绑定。

---

📌 一、用户信息结构

Playol SDK 初始化后，用户信息会自动注入并挂载至 window.playolSDK.user.userInfo，其结构如下：

字段名	类型	说明
userId	string	用户唯一 ID（平台生成，全局唯一）
userName	string	用户昵称（可能为空，建议兜底）
avatar	string	用户头像 URL，可用于展示
sex	number	性别标识：0 = 男，1 = 女，2 = 未知
userType	number	用户类型：0 = 游客用户，1 = 正式注册用户

示例：

{
  "userId": "231175897226391552",
  "userName": "QEkuj",
  "sex": 0,
  "avatar": "https://static.playol.com/upload/userAvatarCover/avatar_1.png",
  "userType": 1
}

⚠️ 注意：字段可能存在为空或默认值的情况，请在 UI 展示时做好容错处理。

---

📥 二、获取用户信息

作为游戏运行环境中的注入模块，Playol SDK 提供两种方式供游戏开发者访问当前玩家数据：

✅ 方式一：读取缓存变量

const userInfo = window.playolSDK.user.userInfo
console.log(userInfo)

• SDK 加载完成后会自动填充该变量；
• 变量会在平台用户变更时自动更新。

✅ 方式二：异步拉取最新数据

// Promise 写法
window.playolSDK.user.getUserInfo().then(userInfo => {
  console.log(userInfo)
})

// async/await 写法
const userInfo = await window.playolSDK.user.getUserInfo()
console.log(userInfo)

• 此方法从平台实时拉取最新用户数据；
• 拉取后会自动更新 user.userInfo 变量。

---

📡 三、监听用户信息变化

当用户切换账号、退出登录、身份变更等事件发生时，SDK 会自动触发已注册的监听函数：

const handleUserChange = (userInfo) => {
  console.log("用户信息发生变更:", userInfo)
}

// 添加监听
window.playolSDK.user.onChange(handleUserChange)

// 取消监听
window.playolSDK.user.removeChange(handleUserChange)

✅ 建议在游戏加载完成后添加监听；若游戏包含多场景或“重进房间”等逻辑，应在合适时机调用 removeChange() 主动移除监听，以避免内存泄漏或状态错乱。

---

🧾 四、用户类型说明

userType 值	含义	可进行的操作
0	游客用户	可试玩，但不支持支付或资产同步
1	正式用户	支持支付、广告、数据同步、排行等所有功能

⚠️ 游客用户可通过平台引导注册为正式账号，SDK 将在未来版本开放升级逻辑。

---

🛠️ 五、推荐实践场景

使用场景	推荐操作
游戏首次启动	使用 getUserInfo() 拉取并缓存用户身份
UI 展示用户昵称、头像	使用 user.userInfo.userName / avatar 字段
数据/道具与用户绑定	使用 userId 作为玩家主键
多端同步、分端识别	userId 在平台全局唯一，跨端一致
多开/iframe 场景下监听身份变化	使用 onChange()
判断当前是否为游客	user.userInfo.userType === 0

---

📦 六、常见问题解答

Q: userInfo 为空或 undefined 怎么办？

A: 确保 SDK 已加载完成并执行 initSDKParam()，再访问用户信息。建议使用 getUserInfo() 异步方式确保拿到值。

Q: 游客用户能用广告/支付吗？

A: 不建议。平台会限制部分功能，开发者应引导注册为正式账号后使用完整能力。

Q: 用户是否可以切换账号？

A: 平台支持账号切换，SDK 会自动触发用户更新监听函数，无需开发者干预。

---

🔗 相关文档推荐

👉 快速开始 | 支付模块 | 数据模块 | 邀请模块