# 登录 [概述](#Outline) [接入向导](#Preconditions) [授权登录](#Login) [扫码登录](#ScanCodeLogin) [异帐号处理](#DiffLogin) [获取票据](#GetLoginRecord) [实名制](#realName) [退出登录](#Logout) [常见问题](#Problem) ## 概述 MSDK登录功能是游戏玩家登录游戏的最快捷方便的方式：玩家可以使用QQ帐号，微信帐号，游客帐号登录您的游戏，可用于Android的手机，平板设备。 您可以参照下图在游戏登录页面放置登录按钮。 ### 功能1 QQ登录 您可以调用MSDK接口拉起手Q客户端引导玩家给游戏进行授权。一般登录流程如下。 1) 在游戏登录页点击“与QQ好友玩” 2) 在手Q登录页完成授权 其中各区域说明如下： 功能1.1: 授权登录按钮，点击可完成对游戏的登录授权。 功能1.2: 用户给游戏授权的权限列表，特殊注意是否有"访问应用里你的QQ好友信息"项，如果没有则会在获取用户关系链时报错"100030"。需要确认在java代码中初始MSDK后调用`WGPlatform.WGSetPermission(WGQZonePermissions.eOPEN_ALL);`。 功能1.3: "返回"按钮，用户点击后会取消登录，游戏有收到登录回调且flag为`eFlag_QQ_UserCancel`。 功能1.4: "切换账号"按钮，用户点击此按钮可在手Q内切换手Q账号，并用切换后的账号对游戏授权。 3) 登录成功，回到游戏进行选择区服或直接开始游戏 功能1.5: 游戏本身的"进入游戏按钮，与MSDK功能无关。 功能1.6: 游戏"切换账号"按钮，调用MSDK的登出接口，然后返回游戏登录页。 ### 功能2 微信登录 您可以调用MSDK接口拉起微信客户端引导玩家给游戏进行授权。登录流程如下。 1) 在游戏登录页点击“与微信好友玩” 2) 在微信登录页完成授权 功能2.1: 授权登录按钮，点击可完成对游戏的登录授权。 功能2.2: 用户给游戏授权的权限列表，其中"寻找与你共同使用该应用的好友"项表示可获取用户关系链。此项权限需要精品类游戏在PR2阶段由协同规划组申请开通，具体可咨询游戏的腾讯接口人。 功能2.3: "取消"按钮，用户点击后会取消登录，游戏有收到登录回调且flag为`eFlag_WX_UserCancel`。 功能2.4: "重试"按钮，用户点击此按钮在微信App上重试授权登录。 ### 微信扫码登录 在未安装微信手机或者在pad类，电视类产品上，您还可以调用扫码登录接口达到更好的用户体验。 MSDK登录可以打造出如下体验： 1)**快速创建游戏登录账户** MSDK登录让用户能够快速轻松地在游戏内创建游戏登录账户，无需设置密码（可能在之后忘记）。这一简单方便的体验可以产生更高的转化量。 2)**个性化游戏运营** MSDK登录后您可以授权获得玩家的头像，基本资料信息，方便游戏运营，能够产生更高的留存率。 3)**社交功能** MSDK登录后游戏玩家可以进行好友间分享，建立游戏工会群等，以促进游戏内体验的分享。 ## 接入向导 ### 1 前置条件 1) 您已经在腾讯开放平台上注册游戏并通过审核，或您的腾讯接口人已经通过内部渠道帮您注册游戏。 2) 您已经按接入配置模块说明完成 [接入配置](config.md)。 3) 确认您的游戏登录权限已开通。完成游戏注册后此权限已经默认开通，如果您调用登录接口返回"-303, no permission"，请联系MSDK联调支持的同学。 ### 2 参考Demo示例 手Q登录示例参考 MSDKDemo/src/com/example/wegame/MainActivity.java 的登录部分。 微信登录示例参考 MSDKDemo/src/com/example/wegame/MainActivity.java 的登录部分。 ### 3 调用此模块其他接口 完成前面Step1-Step2步骤后，即已完全接入此模块，可直接调用此模块的其他接口不需要额外的配置。此模块各部分说明如下。 1)**授权登录：**拉起手Q/微信客户端或web页面(手Q未安装)授权(web版手Q需要根据游戏类型不同开通相应权限)。 2)**扫码登录：**在用户设备未安装微信的情况下游戏可通过扫码登录让用户其他设置的微信进行授权。 3)**异帐号处理：**手Q/微信平台要求处理不同账号登录的异账号场景。 4)**获取票据：**在游戏需要票据（如支付）的地方调用此接口可获取当前用户的票据信息。 5)**退出登录：**用户需要注销或切换账号时可调用此接口清除登录用户的票据信息。 ## 授权登录 ### 1 概要说明 拉起手Q/微信客户端或web页面(手Q未安装)授权，在用户授权以后通过 WGPlatformObserver通知游戏获取到[LoginRet](const.md#LoginRet)登录信息。 ### 2 注册回调 ##### 1)功能描述 为接收MSDK的登录回调，您需要注册回调函数进行处理。登录结果会通过回调函数通知给您。 ##### 2)接口声明 ```java public static void WGSetObserver(WGPlatformObserver observer); ``` ##### 3)参数说明 |参数名称|类型|说明| |:----|:----|:----| |observer|WGPlatformObserver 类|MSDK回调类，参考示例代码| ##### 4)返回值 无 ##### 5)示例代码 ```java public class MsdkCallback implements WGPlatformObserver { public void OnLoginNotify(LoginRet ret) { Logger.d("called"); Logger.d("ret.flag" + ret.flag); switch (ret.flag) { case CallbackFlag.eFlag_Succ: mainActivity.stopWaiting(); // 登陆成功, 读取各种票据 String openId = ret.open_id; String pf = ret.pf; String pfKey = ret.pf_key; MainActivity.platform = ret.platform; String wxAccessToken = ""; long wxAccessTokenExpire = 0; String wxRefreshToken = ""; long wxRefreshTokenExpire = 0; for (TokenRet tr : ret.token) { switch (tr.type) { case TokenType.eToken_WX_Access: wxAccessToken = tr.value; wxAccessTokenExpire = tr.expiration; break; case TokenType.eToken_WX_Refresh: wxRefreshToken = tr.value; wxRefreshTokenExpire = tr.expiration; break; default: break; } } mainActivity.letUserLogin(); break; // 游戏逻辑，对登陆失败情况分别进行处理 case CallbackFlag.eFlag_NotInWhiteList: mainActivity.stopWaiting(); mainActivity.letUserLogout(); System.out.println("不在白名单内"); break; case CallbackFlag.eFlag_Need_Realname_Auth: System.out.println("需要实名认证"); // TODO 游戏如果配置MSDK_REAL_NAME_AUTH_SWITCH=0或者1在这里取消对msdk的超时处理 // TODO 游戏如果配置MSDK_REAL_NAME_AUTH_SWITCH=2在这里调用自定义的实名认证界面 // 这里模拟用户在游戏自定义界面填好信息准备提交注册 if(mainActivity.isCustomUI()){ RealNameAuthInfo info = new RealNameAuthInfo(); info.name = "张霞"; info.identityType = eIDType.IDCards; info.identityNum = "430455198411262142"; info.provinceID = 11; WGPlatform.WGRealNameAuth(info); }; break; case CallbackFlag.eFlag_Login_NetworkErr: case CallbackFlag.eFlag_WX_UserCancel: case CallbackFlag.eFlag_WX_NotInstall: case CallbackFlag.eFlag_WX_NotSupportApi: case CallbackFlag.eFlag_WX_LoginFail: case CallbackFlag.eFlag_QQ_LoginFail: case CallbackFlag.eFlag_Local_Invalid: Logger.d(ret.desc); default: // 显示登陆界面 mainActivity.stopWaiting(); mainActivity.letUserLogout(); break; } } } ``` ##### 6)特殊说明 无 ##### 7)名称解释 |名称|描述|支持平台|调用接口| |----|----|----|----| |授权登录|游戏通过拉起平台的授权界面，引导用户授权游戏获得登录所需票据|手Q/微信|WGLogin| |快速登录|玩家的操作使平台拉起游戏时会透传登录相关的票据信息从而登录进入游戏。|手Q|无| |自动登录|登录时不指定平台参数，不会拉起手Q或者微信，只使用本地有效票据进行授权。|手Q/微信|WGLogin(EPlatform.ePlatform_None)| |自动刷新|MSDK提供自动刷新微信票据接口|MSDK 提供功能|无| |异帐号|当前游戏内登录的帐号和平台登录的帐号不一致|MSDK 提供功能|WGSwitchUser| [ePlatform定义说明](const.md#ePlatform) [LoginRet定义说明](const.md#LoginRet) QQ大厅登录 : QQ大厅登录是早期棋牌类游戏通过QQ游戏大厅拉起传递票据进行登录的方式，不接入QQ游戏大厅的游戏可以不关注 ### 3 调用登录 ##### 1)功能描述 您可以通过调用WGLogin 接口进行指定平台拉起授权登录 或者 进行自动登录，调用结果会通过回调函数通知给您，函数声明及调用示例代码如下： ##### 2)接口声明 ```java public static void WGLogin(EPlatform platform); ``` ##### 3)参数说明 |参数名称|类型|说明| |:----|:----|:----| |platform|[EPlatform 枚举](const.md#ePlatform)|游戏需要授权登录的平台类型| ##### 4)返回值 无，登录信息通过 WGPlatformObserver 回调返回给游戏 ##### 5)示例代码 ```java WGPlatform.WGLogin (EPlatform.ePlatform_QQ); //QQ登录 WGPlatform.WGLogin (EPlatform.ePlatform_Weixin); //微信登录 ``` ##### 6)特殊说明 无 ##### 7)名称解释 无 ### 微信扫码登录 ##### 1)功能描述 拉起登录二维码显示界面，玩家可以通过另外一个已经登录对应社交帐号的手机扫描二维码，根据提示授权后，游戏即可获得登录票据信息，一般用于电视或平板环境，或者手机未安装平台客户端的情况，（目前仅支持微信）。 ##### 2)接口声明 ```java public static void WGQrCodeLogin(EPlatform platform); ``` ##### 3)参数说明 |参数名称|类型|说明| |:----|:----|:----| |platform|[EPlatform 枚举](const.md#ePlatform)|游戏需要授权登录的平台类型| ##### 4)返回值 无，登录信息通过 WGPlatformObserver 回调返回给游戏 ##### 5)示例代码 ```java WGPlatform.WGQrCodeLogin (EPlatform.ePlatform_Weixin); ``` ##### 6)特殊说明 关于扫码登录权限：非精品的游戏统一由游戏邮件向微信申请，精品的游戏由协同统一接入处理。 拉取到的二维码图片有效期5分钟，过期扫码无法登录成功。 ##### 7)名称解释 无 ## 异帐号处理 ### 1 概括说明 用户从平台拉起进入游戏，因为账号不一致（平台不一致或者平台一致但帐号不一致），需要游戏弹框提示异账号。异账号场景详细描述参考[异账号说明文档](diff_account.md) ### 2 注册回调 为接收MSDK提供的游戏被拉起的回调，您需要注册 WGPlatformObserver 回调。 ##### 1)功能描述 平台拉起进入游戏携带的信息，会通过 WGPlatformObserver 传递给游戏。 ##### 2)接口声明 ```java public static void WGSetObserver(WGPlatformObserver observer); ``` ##### 3)参数说明 |参数名称|类型|说明| |:----|:----|:----| |observer|WGPlatformObserver 类|MSDK回调类，参考示例代码| ##### 4)返回值 无 ##### 5)示例代码 ```java public class MsdkCallback implements WGPlatformObserver { public void OnWakeupNotify(WakeupRet ret) { Logger.d("called"); Logger.d(ret.toString() + ":flag:" + ret.flag); Logger.d(ret.toString() + "desc:" + ret.desc); Logger.d(ret.toString() + "platform:" + ret.platform); MainActivity.platform = ret.platform; // TODO GAME 游戏需要在这里增加处理异账号的逻辑 if (CallbackFlag.eFlag_Succ == ret.flag || CallbackFlag.eFlag_AccountRefresh == ret.flag) { //eFlag_AccountRefresh代表 刷新微信票据成功 Logger.d("login success flag:" + ret.flag); mainActivity.letUserLogin(); } else if (CallbackFlag.eFlag_UrlLogin == ret.flag) { // 用拉起的账号登录，登录结果在OnLoginNotify()中回调 } else if (ret.flag == CallbackFlag.eFlag_NeedSelectAccount) { // 异账号时，游戏需要弹出提示框让用户选择需要登陆的账号 Logger.d("diff account"); mainActivity.showDiffLogin(); } else if (ret.flag == CallbackFlag.eFlag_NeedLogin) { // 没有有效的票据，登出游戏让用户重新登录 Logger.d("need login"); mainActivity.letUserLogout(); } else { Logger.d("logout"); mainActivity.letUserLogout(); } } } ``` ##### 6)特殊说明 收到 eFlag.eFlag_NeedSelectAccount 时即为触发异账号场景，此时游戏需要弹出提示框让用户选择需要登录的账号，并根据用户的选择调用WGSwitchUser接口，然后等待 WGPlatformObserver 回调获取切换账号的结果。 ##### 7)名称解释 [EPlatform定义说明](const.md#ePlatform) [WakeupRet定义说明](const.md#WakeupRet) ### 3 切换账号 ##### 1)功能描述 当异账号判断的wakeupRet.flag为eFlag_NeedSelectAccount时，游戏需要弹框提示用户，选择本地账号或者拉起账号登陆游戏，游戏需要根据用户选择的结果调用接口WGSwitchUser完成用户登陆。 ##### 2)接口声明 ```java public static boolean WGSwitchUser(boolean switchToLaunchUser); ``` ##### 3)参数说明 | 参数名称 | 类型 | 说明 | | :---- | :---- | :---- | | switchToLaunchUser | bool | true : 切换到外部帐号; false : 继续使用原帐号| ##### 4)返回值 true : 表明此账号有票据。MSDK会去验证此票据的有效性，并在 WGPlatformObserver 中返回验证结果。 false : 表明此账号无票据或票据不合法。可直接登录，让用户重新授权登录。 ##### 5)示例代码 ```java if(!WGPlatform.WGSwitchUser(true)){ letUserLogout(); } ``` ##### 6)特殊说明 无 ##### 7)名称解释 无 ## 获取票据 ### 1 概括说明 您在登录回调中通过解析[LoginRet](const.md#LoginRet)中的 [TokenRet](const.md#TokenRet)可以获得登录的回调票据，除此之外，您还可以调用如下接口来获取当前的登录票据。LoginRet票据信息中包含玩家的openid,pf,pfkey,LoginRet中的TokenRet包含pay_token(QQ登录时特有),access_token(微信登录时特有)等信息。您在进行[支付](midas.md)时将会用到这些信息。 ### 2 注册回调 无 ### 3 调用接口 ##### 1)功能描述 获得登录的回调票据 ##### 2)接口声明 ```java public static int WGGetLoginRecord(LoginRet ret); ``` ##### 3)参数说明 | 参数名称 | 类型 | 说明 | | :---- | :---- | :---- | | ret | LoginRet | 票据信息 [LoginRet](const.md#LoginRet)| ##### 4)返回值 当前登录票据的平台id ##### 5)示例代码 ```java LoginRet lr = new LoginRet(); WGPlatform.WGGetLoginRecord(lr); ``` ##### 6)特殊说明 您通过此接口获取到的票据以后必须传到游戏Server,通过游戏Server调用MSDK后端验证票据接口验证票据有效以后才能让用户进入游戏。 ##### 7)名称解释 [LoginRet](const.md#LoginRet)定义说明 ## 实名制 按照文化部《网络游戏管理暂行办法》的相关要求，网络游戏用户需要使用有效身份证件进行实名注册才可登录游戏，为了减轻游戏开发的负担我们为游戏定制了实名认证的界面以及整套接口，通过该模块您可以花费几分钟的时间来完成实名认证的功能。 实名制详细描述参考[实名制说明文档](realname.md) ## 退出登录 ### 1 概括说明 您可以调用WGLogout接口来退出登录，清除本地票据 ### 2 注册回调 无 ### 3 调用接口 ##### 1)功能描述 获得登录的回调票据 ##### 2)接口声明 ```java public static boolean WGLogout(); ``` ##### 3)参数说明 无 ##### 4)返回值 返回true,您无需处理返回值 ##### 5)示例代码 ```java WGPlatform.WGLogout(); ``` ##### 6)特殊说明 无 ##### 7)名称解释 无 ## 常见问题 |常见问题|登录|Android|