11/25/2024 10:18:49

登录模块

一、概述

MSDK 登录功能为游戏提供便捷的登录功能：玩家可以使用 QQ、微信、Facebook、GameCenter、Google、游客账号等登录您的游戏。

[info] 注意：
更新到 MSDK5.20 及之后版本的业务需联系 QQ 游戏中心，取消业务在 QQ 游戏中心启动时 scheme 携带的 accesstoken、paytoken 字段，否则会造成游戏内登录态失效。平台取消配置后，旧版本也会失去快速登录能力，详情可咨询平台侧。

支持的渠道有：

1. WeChat
2. QQ
3. Guest
4. Facebook
5. GameCenter
6. Google
7. Twitter
8. Garena
9. Line
10. Apple
11. HMS

二、接入向导

2.1 推荐登录流程

1. 初始化 SDK
2. 注册登录回调
3. 调用自动登录
4. 自动登录失败则选择登录指定渠道
5. 完整登录流程

2.2 注册回调

1）功能描述
接受 MSDK 登录模块的回调，游戏需要注册回调函数进行处理；强烈建议游戏在应用启动函数中进行注册。

2）接口声明

/// <summary>
/// 登出回调、应用唤醒回调、视频号授权回调
/// </summary>
public static event OnMSDKRetEventHandler<MSDKBaseRet> LoginBaseRetEvent;

/// <summary>
//// 登录回调，包括 login、bind、autologin、switchuser 等
/// </summary>
public static event OnMSDKRetEventHandler<MSDKLoginRet> LoginRetEvent;

class MSDKLoginObserver
{

public:
    // 登录回调，包括 login、bind、autologin、switchuser 等
    virtual void OnLoginRetNotify(const MSDKLoginRet &loginRet) {};

    // 登出回调、应用唤醒回调、视频号授权回调
    virtual void OnBaseRetNotify(const MSDKBaseRet &baseRet) {};
};

3）示例代码

MSDKLogin.LoginRetEvent += OnLoginRetEvent;
MSDKLogin.LoginBaseRetEvent += OnLoginBaseRetEvent;

private void OnLoginRetEvent(MSDKLoginRet loginRet)
{
	Debug.Log ("OnLoginRetNotify in Login");
	string methodTag = "";
	if (loginRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_LOGIN) {
		methodTag = "Login";
	} else if (loginRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_BIND) {
		methodTag = "Bind";
	} else if (loginRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_AUTOLOGIN) {
		methodTag = "AutoLogin";
	} else if (loginRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_QUERYUSERINFO) {
		methodTag = "QueryUserInfo";
	}
    // GetLoginRet 为同步接口，不需要在回调中处理
//      else if (loginRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_GETLOGINRESULT) {
	//	methodTag = "GetLoginResult";
	//}
    else if (loginRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_LOGINWITHCONFIRMCODE) {
		methodTag = "LoginWithConfirmCode";
	}
	SampleInstance.showRetDialog(methodTag, loginRet);
}			

private void OnLoginBaseRetEvent(MSDKBaseRet baseRet)
{
	Debug.Log ("OnBaseRetNotify in Login");

	if (baseRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_WAKEUP) {
		handleDiifAccount(baseRet);
	}
	else if (baseRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_LOGOUT) {
		string methodTag = "Logout";
	    SampleInstance.showRetDialog(methodTag, baseRet);
	}
}

// 处理异账号的逻辑
private void handleDiifAccount (MSDKBaseRet baseRet)
{
    string methodTag = "异账号";
    switch (baseRet.RetCode) {
    case MSDKError.SUCCESS: { // 本地原有票据有效，使用原有票据登录
            SampleInstance.showRetDialog (methodTag, "使用原有票据登录，游戏无需处理");
            break;
        }
    case MSDKError.LOGIN_ACCOUNT_REFRESH: { // 新旧 openid 相同，票据不同。刷新登录票据
            SampleInstance.showRetDialog (methodTag, "新旧 openid 相同，票据不同。刷新登录票据，游戏无需处理");
            break;
        }
    case MSDKError.LOGIN_URL_USER_LOGIN: {// 本地无openid，拉起有票据，使用新票据登录
            SampleInstance.showRetDialog (methodTag, "本地无openid，拉起有票据，使用新票据登录，将自动触发切换游戏账号逻辑（SwitchUser），游戏需监控登录的回调结果");
            break;
        }
    case MSDKError.LOGIN_NEED_SELECT_ACCOUNT: {
            SampleInstance.ShowSwithUserDialog ();
            break;
        }
    case MSDKError.LOGIN_NEED_LOGIN: {
            SampleInstance.showRetDialog (methodTag, "票据均无效，进入登录页面");
        }
        break;
    default:
        break;
    }
}

//销毁的时候需要移除监听
private void OnDestroy()
{
	MSDKLogin.LoginRetEvent -= OnLoginRetEvent;
	MSDKLogin.LoginBaseRetEvent -= OnLoginBaseRetEvent;
}

MSDKLogin::SetLoginObserver(new MSDKDemoBaseLoginObserver());

class  MSDKDemoBaseLoginObserver: public GCloud::MSDK::MSDKLoginObserver {
    // 登录回调，包括 login、bind、autologin、switchuser 等
public:
    virtual void OnLoginRetNotify(const GCloud::MSDK::MSDKLoginRet &loginRet) {、
        UMSDKDemoBase::showNormalAlert(loginRet);
    };
    // 登出回调、应用唤醒回调
    virtual void OnBaseRetNotify(const GCloud::MSDK::MSDKBaseRet &baseRet) {
        if (baseRet.methodNameID == kMethodNameWakeUp) {
            //异账号处理
            switch (baseRet.retCode) {
                case MSDKError::SUCCESS:
                	baseRet.append("使用原有票据登录，游戏无需处理");
                    break;
                case MSDKError::LOGIN_ACCOUNT_REFRESH:
                	baseRet.append("新旧 openid 相同，刷新登录票据，游戏无需处理");
                    break;
                case MSDKError::LOGIN_URL_USER_LOGIN:
                	baseRet.append("本地无openid，拉起有票据，使用新票据登录，将自动触发切换游戏账号逻辑（SwitchUser），游戏需监控登录的回调结果");
                    break;
                case MSDKError::LOGIN_NEED_SELECT_ACCOUNT:
                	baseRet.append("选择是否切换用户");
                    break;
                case MSDKError::LOGIN_NEED_LOGIN:
                	baseRet.append("票据均无效，进入登录页面");
                    break;
                default:
                    break;
            }
            return;
        }
        if (baseRet.retCode == MSDKError::NEED_REALNAME) {
            //实名制不需要处理
            return;
        }
        UMSDKDemoBase::showNormalAlert(ret);
    };
};

4）数据结构

MSDKLoginRet 详解
继承自 MSDKBaseRet，包含基础的信息

2.3 自动登录

1）功能描述
自动登录，MSDK 将自动获取本地登录态，并到 MSDK 服务器校验登录态是否有效，若本地无登录态缓存或者服务器返回登录态失效则回调自动登录失败的结果。

2）接口声明

public static void AutoLogin();

public static void AutoLogin();

3）示例代码

MSDKLogin.AutoLogin();

MSDKLogin::AutoLogin();

2.4 登录

1）功能描述
登录指定渠道，获取第三方平台登录态并到 MSDK 服务器鉴权，返回 MSDK 统一账号。
目前只有微信、QQ渠道支持二维码登录，详情见微信渠道的登录功能、QQ渠道的登录功能。

2）接口声明

public static void Login(string channel, string permissions = "", string subChannel = "", string extraJson = "")

public static void Login(const String &channel, const String &permissions, const String &subChannel, const String &extraJson)

3）参数说明

4）示例代码

MSDKLogin.Login(MSDKChannel.WeChat);

std:string permissionList = "snsapi_userinfo,snsapi_friend,snsapi_message";
MSDKLogin::Login("WeChat", permissionList);

2.5 退出登录

1）功能描述
退出登录渠道

2）接口声明

public static void Logout(string channel = "", string subChannel = "", bool channelOnly = false)

public static void Logout(const String &channel = "", const String &subChannel = "", const bool channelOnly = false)

3）示例代码

MSDKLogin.Logout();

MSDKLogin::Logout();

2.6 获取登录态

1）功能描述
在游戏中，获取游戏的登录态信息

[warning] 此接口中已移除对登录态过期的校验。

2）接口声明

public static MSDKLoginRet GetLoginRet()

public static bool GetLoginRet(MSDKLoginRet &loginRet)

3）示例代码

MSDKLoginRet ret = MSDKLogin.GetLoginRet();

MSDKLoginRet ret;
MSDKLogin::GetLoginRet(ret);

2.7 视频号授权

1）功能描述
MSDK 封装视频号授权接口，通过调用 ChannelPermissionAuth 接口，当前微信要求传入 snsapi_channels_livestream，在 MSDK 的回调中获取 tdiAuthBuffer，用于后续的直播登录。 该功能不限制登录渠道及登录态，即可以跨平台调用该接口。

2）接口声明

public static void ChannelPermissionAuth(string channel, string permissions = "", string subChannel = "", string extraJson = "")

public static void  ChannelPermissionAuth(const String &channel, const String &permissions = "", const String &subChannel = "", const String &extraJson = "")

3）参数说明

4）示例代码

在视频号授权回调 OnBaseRetNotify（C++）或 OnLoginBaseRetEvent（C#）接口中，通过判断 methodId 为 137（MSDK_CHANNEL_PERMISSION_AUTH）的授权返回作为直播授权的标记，具体使用可参照注册回调部分。 调用示例：

MSDKLogin.ChannelPermissionAuth(MSDKChannel.WeChat, "snsapi_channels_livestream");

MSDKLogin::ChannelPermissionAuth("WeChat", "snsapi_channels_livestream");

5）注意事项

• 视频号授权当前仅支持微信视频号
• 权限列表目前请填 snsapi_channels_livestream，这同时也是底层区分正常登录与权限申请的标记，后续微信要求的 permissions 可能会变动
• 视频号授权回调中 tdiAuthBuffer 存在于 extraJson 字段中，以 Base64 的格式返回，通过 Json 解析获取，请使用标准的 Base64 解码后使用
• 暂未支持超时回调逻辑
• MSDK 仅做 tdiAuthBuffer 内容的返回，具体使用方法联系 MSDK助手 对接

2.8 切换游戏账号

1）功能描述
在出现异账号的情况，选择是否切换另一个账号登录。 异账号的情况：比如游戏用 QQ 登录，按 Home 键返回桌面后，又从微信游戏中心启动游戏，就会出现是否需要切换到微信账号的情况，称为异账号。 一般国内会出现异账号的情况。

2）接口声明

public static bool SwitchUser(bool useLaunchUser)

public static bool SwitchUser(bool useLaunchUser);

3）参数说明

[info] 注意
1.如果玩家选择切换账号，请将 useLaunchUser 置为 true。切换账号的结果将从游戏监控的登录回调处返回。
2.如果玩家选择不切换账号，请将 useLaunchUser 置为 false。MSDK 将自动触发自动登录逻辑，但不会回调给游戏

4）示例代码

MSDKLogin.SwitchUser(true);

MSDKLogin::SwitchUser(true);

2.9 绑定（仅支持海外）

1）功能描述
绑定的本质是指多个第三方账号共用一个 MSDK openid。一般使用场景为：游客登陆游戏，之后绑定 Facebook 或者 Google 账号。

2）接口声明

public static void Bind(string channel, string permissions = "", string subChannel = "", string extraJson = "")

public static void Bind(const String &channel, const String &permissions = "", const String &subChannel = "", const String &extraJson = "")

3）参数说明

4）示例代码

MSDKLogin.Bind("WeChat");

MSDKLogin::Bind("WeChat");

2.10 使用确认码登录

1）功能描述
当登录或者绑定失败后，通过确认码再次尝试登录，避免让用户再次拉起授权登录界面。 确认码是后台返回的。

2）接口声明

public static void LoginWithConfirmCode (int actionType = 0, string confirmcode = "",string extraJson = "")

public static void LoginWithConfirmCode(const int actionType = 0, const String &confirmCode = "", const String &extraJson = "");

3）参数说明

4）示例代码

MSDKLogin.LoginWithConfirmCode(0, confirmcode);

MSDKLogin::LoginWithConfirmCode(0, confirmcode);

2.11 重置游客功能

1）功能描述
将游客重置，再次使用游客渠道登录时，将生成新的游客。

2）接口声明

public static void ResetGuest()

static void ResetGuest()

3）示例代码

MSDKLogin.ResetGuest();

MSDKLogin::ResetGuest();

三、Editor环境下模拟登录

业务在开发阶段，需要在 Editor 环境上登录，进行联调。MSDK 目前提供模拟登录方案，以供业务在 Editor 环境联调。

请参考Editor环境下模拟登录

四、游客模式和绑定功能说明

4.1 功能描述

游客模式是指：每次用户登录均使用游客身份进行登录（如：无登录按钮直接进入游戏），在游戏内进行社交关系绑定达到账号关联以找回账号的一种登录方式。

游戏使用场景说明：

1. 一般没有渠道登录按钮，直接使用游客进入游戏
2. 在游戏新手教程、游戏设置界面中，有绑定社交关系账号功能，绑定账号用于拉取用户好友、找回账号

3. 找回账号通过绑定触发，当被绑定账号存在进度时会返回错误及确认码，可通过确认码登录接口实现账号恢复

   

4.2 登录

每次均使用游客渠道进行登录

4.3 绑定账号

通过绑定接口进行账号绑定。绑定账号可用于获取用户关系链及找回账号。

[info] 测试过程中，如需要解绑账号便于测试，请在企业微信联系 MSDK助手

4.4 恢复账号

1. 通过绑定失败触发。当被绑定渠道存在账号进度时，三方错误码为：1403
2. 通过判断错误码，使用确认码登录接口进行登录

4.5 重置进度

由于每次通过游客登录，用户如果想新启进度时，可以通过重置游客接口，删除当前游客（仅删除游客，可通过绑定的设计账号找回）

注意：如果游客没有绑定账号，重置进度将导致游客账号丢失

五、实名认证

根据国家法律法规的相关要求，网络游戏用户需要使用有效身份证件进行实名注册才可登录游戏。为了减轻游戏开发的负担，我们在游戏登录的过程中，封装了实名认证的操作。当登录后返回需要实名认证时，会自动拉起 WebView 组件，打开实名认证的网页。当玩家完成实名认证后，就可以登录游戏。实名认证过程，游戏无需额外的开发。

[info] 注意：
1、实名认证需要接入 WebView 组件
2、实名认证的网页是全屏展示，若玩家点击返回登录，则返回给游戏的登录态是登录不成功。
3、实名认证是由中控提供的相关服务
4、只有国内游戏才有实名认证过程，国外游戏没有

六、检测 Universal Link 接入功能

版本说明

V 5.11 及以后版本

1）功能描述

增加了自检函数 ，帮助开发者排查SDK接入过程中遇到的问题，目前只支持微信渠道, 测试环境测试使用，正式环境不可以使用此功能

2) 接口代码

channel 填写 “WeChat“ ,其他字段为预留字段填空的字符串即可

public static void CheckUniversalLink(string channel, string subChannel = "", string extraJson = "");

MSDK_EXPORT_UE static void CheckUniversalLink(const String &channel, const String &subChannel = "", const String &extra = "");

3) 示例代码：

接口调用

MSDKLogin.CheckUniversalLink(("WeChat");

MSDKLogin::CheckUniversalLink("WeChat");

回调函数

// 登出回调、应用唤醒回调
 public void OnLoginBaseRetEvent(MSDKBaseRet baseRet)
{
    Debug.Log("OnBaseRetNotify in Login");
    if (baseRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_CHECK_UL)
    {
        // 处理回调检查 Universal Link 结果
    }
    mCurrentTestMgr.ShowLogInNewLine(methodTag + Tools.Instance.GetRetString(baseRet));
}

// 登出回调、应用唤醒回调
void OnBaseRetNotify(const MSDKBaseRet &baseRet) {
    if (baseRet.methodNameID == kMethodNameCheckUniversalLink) {
        // 处理回调检查 Universal Link 结果
    }
    handleCallback(baseRet, baseRet.methodNameID);
};

4) 字段说明

其中检测结果会放在 baseRet.ExtraJson 中，格式为一个 JSON 字符串

{
    "success":true,
    "errorInfo":"Universal Link check passed. The application is launched by WeChat via Universal Link",
    "step":"WXULCheckStepBackToCurrentApp",
    "suggestion":""
}

success 标识当前步骤检测结果
errorInfo 为提示信息
suggestion 为提示开发者的操作信息
step 的值说明:
    step = WXULCheckStepParams: 参数检查
    step = WXULCheckStepSystemVersion: 当前系统版本检查
    step = WXULCheckStepWechatVersion: 微信客户端版本检查
    step = WXULCheckStepSDKInnerOperation: 微信SDK内部操作检查
    step = WXULCheckStepLaunchWechat: App拉起微信检查
    step = WXULCheckStepBackToCurrentApp: 由微信返回当前App检查
    step = WXULCheckStepFinal: 最终检查

会依次回调这 7 个 step，当回调了WXULCheckStepFinal，说明检测通过，SDK 接入成功。 任一 step 回调的 success 为 false, 流程终止，后续不再回调，可以根据errorInfo的查看当前步骤错误的原因，根据 suggestion 修复问题.

七、常见问题

1. 为保障安全性，MSDK 登录态受有效期限制，一般情况下为 30 天 。由于更换设备登录、安全问题考量，登录态也会提前过期。
2. MSDK 5.4.0000 版本开始（对应 GCloud 2.0.10 版本），移除登录防重入限制，但仍然保留登录超时检测。在 iOS9 以上系统，点击系统左上角的“返回xx游戏”或者通过 home 键直接返回游戏，不会有登录回调，此时再调用登录接口，可以重新拉起登录流程（旧版本会返回 InProgress 错误），上次的登录流程作废。
3. 如何判断通过手Q/微信游戏中心拉起游戏？
   MSDK5.3.000 版本及之后的版本，通过 wakeup 回调里 ExtraJson 参数中的 param 字段判断，此字段会全量接收游戏中心返回的字段。手Q为：launchfrom:sq_gamecenter；微信Android为：_wxobject_message_ext:WX_GameCenter；微信iOS为：messageExt:WX_GameCenter。
   
4. 如何获取米大师支付场景 token？
   手Q渠道使用 pay_token，需要解析登录回调 channelInfo 中的 pay_token 字段获取；
   其他渠道没有 pay_token，使用 MSDK 登录回调最外层的 token 字段。其中，国内游戏对此 token 不需要做任何处理。海外游戏需要使用 获取第三方渠道 token 接口 将此 token 转成对应的渠道 token。
   注意：推荐的支付鉴权方式为，获取第三方 openid 和 token 后按需到指定平台进行支付鉴权。
   
5. 错误码
   见错误码说明。