# 获取QQ用户信息（选接）

# 接口说明

用于获取QQ用户的个人信息，如昵称、头像等。

注意事项

一般通过此服务获取QQ用户的昵称、头像，用来作为玩家在游戏内的昵称、头像，如果无此需求，此服务可不对接！

# 首次获取

个人信息是用户的敏感数据，首次获取用户信息需要用户同意授权，具体方法为，使用 sdkInstance.createUserInfoButton(options) (opens new window) 创建一个引导用户点击的按钮，并在点击并同意授权后获取；授权相关说明可以参考QQ官方文档的授权 (opens new window)章节。

// 创建QQ用户信息获取按钮
const userInfoButton = sdkInstance.createUserInfoButton({
  type: "text",
  text: "获取用户信息",
  style: {
    top: 376,
    left: 40,
    width: 100,
    height: 32,
    backgroundColor: "#07c160",
    borderWidth: 0,
    borderColor: "#07c160",
    borderRadius: 0,
    color: "#ffffff",
    fontSize: 12,
    textAlign: "center",
    lineHeight: 32
  }
});

// 先判断 userInfoButton 是否存在再使用
// 因为当用户客户端基础库版本过低时，调用 sdkInstance.createUserInfoButton 接口将返回 undefined
if (userInfoButton) {
  userInfoButton.onTap(function(response) {
    // 事件响应状态码为0时，表示获取成功
    if (response.code == 0) {
      const userInfo = response.data.userInfo;

      console.log(userInfo.nickName); // QQ昵称
      console.log(userInfo.avatarUrl); // QQ头像
    }
    // 事件响应状态码为cancel时，表示用户拒绝授权
    else if (response.code == "cancel") {

    }
    // 其他非0状态码，表示获取失败
    else {
      sdkInstance.modal.message(response.message);
    }
  });
}

最低基础库版本要求

当用户客户端基础库版本过低时，调用 sdkInstance.createUserInfoButton(options) 接口将弹出升级提示，并返回 undefined，需要游戏客户端对返回值做兼容处理！

# 参数说明

参数说明如下表所示：

选项	类型	必填	默认值	说明
type	string	是	text	按钮类型 `text` - 文本按钮，允许自定义文本及背景色 `image` - 图片按钮，仅允许设置背景贴图，背景贴图会直接拉伸至按钮的宽高
text	string	否	--	文本按钮的文本，仅当 `type` 为 `text` 时有效
image	string	否	--	图片按钮的背景图片，仅当 `type` 为 `image` 时有效
style	object	是	--	按钮样式
style.top	number	是	0	按钮左上角纵坐标
style.left	number	是	0	按钮左上角横坐标
style.width	number	是	100	按钮宽度
style.height	number	是	32	按钮高度
style.borderWidth	number	否	0	按钮边框宽度
style.borderRadius	number	否	0	按钮边框圆角
style.borderColor	string	否	#07c160	按钮边框颜色，格式为 `6` 位 `16` 进制数
style.backgroundColor	string	否	#07c160	按钮背景颜色，格式为 `6` 位 `16` 进制数
style.color	string	否	#ffffff	按钮文本颜色，格式为 `6` 位 `16` 进制数
style.fontSize	number	否	12	按钮文本字号
style.textAlign	string	否	center	按钮文本水平居中方式 `left` - 居左 `center` - 居中 `right` - 居右
style.lineHeight	number	否	32	按钮文本行高
withCredentials	boolean	否	false	获取个人信息时是否携带登录态信息。当 `withCredentials` 为 `true` 时，要求此前有调用过 `qq.login` 且登录态尚未过期，此时返回的数据会包含 `encryptedData`、`iv` 等敏感信息；当 `withCredentials` 为 `false` 时，不要求有登录态，返回的数据不包含 `encryptedData`、`iv` 等敏感信息
lang	string	否	zh_CN	描述用户信息的语言 `en` - 英文 `zh_CN` - 简体中文 `zh_TW` - 繁体中文

# 返回值说明

调用 sdkInstance.createUserInfoButton(options) 接口，将返回一个用于获取QQ用户信息的按钮实例。具体实例方法如下表所示：

方法	类型	说明
show	function	用于显示QQ用户信息获取按钮
hide	function	用于隐藏QQ用户信息获取按钮
destroy	function	用于销毁QQ用户信息获取按钮
onTap	function	用于绑定QQ用户信息获取按钮的点击事件回调函数
offTap	function	用于注销QQ用户信息获取按钮的点击事件回调函数

# 特别说明

由于QQ的策略限制，首次获取用户信息必须使用上述API创建指定按钮，并在点击并同意授权后获取。但往往游戏拥有自己的视觉设计体系，而该API创建的按钮并不符合美术需求，遇到这种情况可通过以下两种方式解决：

设置 type 为 text 时，将按钮文本、边框颜色及背景颜色均置空，以便创建一个视觉透明的按钮，并利用宽高及横纵坐标将其覆盖在游戏原生按钮上；
设置 type 为 image 时，将游戏的按钮图片素材作为背景图片。

# 已授权的情况下获取

如果用户之前已经授权过个人信息给游戏，开发者可以把用户的个人信息记录在业务后台；但用户有可能修改昵称头像，为了保证个人信息不出现过期失效的情况，需要再次获取用户信息，此时不需要再使用上述 sdkInstance.createUserInfoButton(options) (opens new window) 的方式来获取用户信息，可以调用 sdkInstance.getUserInfo(options) (opens new window) 直接获取。

sdkInstance.getUserInfo({
  success: function(response) {
    console.log(response.code); // 接口响应状态码，此处为0，表示获取成功
    console.log(response.data); // QQ用户信息
    console.log(response.data.userInfo.nickName); // QQ昵称
    console.log(response.data.userInfo.avatarUrl); // QQ头像
  },
  fail: function(error) {
    console.log(error); // 获取失败的错误信息，error.code为非0状态码，error.message为错误消息
  },
  complete: function(result) {
    // do something here...
  }
});

# 参数说明

参数说明如下表所示：

选项	类型	必填	默认值	说明
withCredentials	boolean	否	false	获取个人信息时是否携带登录态信息。当 `withCredentials` 为 `true` 时，要求此前有调用过 `qq.login` 且登录态尚未过期，此时返回的数据会包含 `encryptedData`、`iv` 等敏感信息；当 `withCredentials` 为 `false` 时，不要求有登录态，返回的数据不包含 `encryptedData`、`iv` 等敏感信息
lang	string	否	zh_CN	描述用户信息的语言 `en` - 英文 `zh_CN` - 简体中文 `zh_TW` - 繁体中文
success	function	否	--	获取成功的回调函数，返回QQ用户信息
fail	function	否	--	获取失败的回调函数，返回错误信息
complete	function	否	--	获取完成的回调函数，成功或失败均会调用

# 返回值说明

WARNING

返回值格式：JSON 格式。

选项	类型	说明
code	number	响应状态码，为 `0` 时表示获取成功，其他非 `0` 状态码均表示获取失败
data	object / null	获取成功时返回QQ用户信息，详情请参考 qq.getUserInfo() 接口说明，失败时返回 `null`
message	string	获取成功或失败时的相应描述信息

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

// 首先通过 sdkInstance.getSetting 接口查询用户是否已授权获取昵称头像
sdkInstance.getSetting({
  success: function(setting) {
    // 判断用户之前是否已同意授权获取其个人信息
    // 若已授权，可以直接调用 sdkInstance.getUserInfo 接口获取昵称头像
    if (setting.authSetting["scope.userInfo"]) {
      sdkInstance.getUserInfo({
        success: function(response) {
          const userInfo = response.data.userInfo;

          console.log(userInfo.nickName); // QQ昵称
          console.log(userInfo.avatarUrl); // QQ头像
        },
        fail: function(error) {
          sdkInstance.modal.message(error.message);
        }
      });
    }
    // 反之，先通过 sdkInstance.createUserInfoButton 接口创建授权按钮并引导用户点击
    else {
      const userInfoButton = sdkInstance.createUserInfoButton({
        type: "text",
        text: "获取用户信息",
        style: {
          top: 376,
          left: 40,
          width: 100,
          height: 32,
          backgroundColor: "#07c160",
          borderWidth: 0,
          borderColor: "#07c160",
          borderRadius: 0,
          color: "#ffffff",
          fontSize: 12,
          textAlign: "center",
          lineHeight: 32
        }
      });

      // 先判断 userInfoButton 是否存在再使用
      // 因为当用户客户端基础库版本过低时，调用 sdkInstance.createUserInfoButton 接口将返回 undefined
      if (userInfoButton) {
        userInfoButton.onTap(function(response) {
          // 事件响应状态码为0时，表示获取成功
          if (response.code == 0) {
            const userInfo = response.data.userInfo;

            console.log(userInfo.nickName); // QQ昵称
            console.log(userInfo.avatarUrl); // QQ头像
          }
          // 事件响应状态码为cancel时，表示用户拒绝授权
          else if (response.code == "cancel") {

          }
          // 其他非0状态码，表示获取失败
          else {
            sdkInstance.modal.message(response.message);
          }
        });
      }
    }
  }
});

← 登录支付 →