05/15/2024 15:19:45

The Login Module's Description

I. Overview

MSDK login function provides a convenient login function for your game: players can use QQ, WeChat, Facebook, GameCenter, Google, guest account, etc. to login your game.

[info] Warning:
Any game which has been updated to MSDK5.20 and later versions needs to contact QQ Game Center to cancel accesstoken and paytoken fields carried by scheme when the game is initiated in QQ Game Center, otherwise the in-game login status will be invalid. After the platform removes configuration, the old version will also lose the quick login capability. For details, please consult the platform.

The supported channels include:

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

II. Access Guide

Recommended login process

1. Initialize SDK
2. Register login callback
3. Call automatic login
4. If automatic login fails, select to login the specified channel
5. Complete login process

2.1 Register Callback

1) Function Description

Receive MSDK login module's callback; the game needs to register a callback function for processing; it is strongly recommended that the game register it in the app's start function.

2) Interface Declaration

/// <summary>
/// Log out callback; the app wakes up callback 
/// </summary>
public static event OnMSDKRetEventHandler<MSDKBaseRet> LoginBaseRetEvent; 

/// <summary>
//// login callback, including login, binding, autologin, switchuser, etc.
/// </summary>
public static event OnMSDKRetEventHandler<MSDKLoginRet> LoginRetEvent;

class MSDKLoginObserver
{

public:
    // Login callback, including login, bind, autologin, switchuser, etc.
    virtual void OnLoginRetNotify (const MSDKLoginRet &loginRet) {}; 

    // Logout callback; application wakeup callback
    virtual void OnBaseRetNotify(const MSDKBaseRet &baseRet) {};
};

3) Demo code

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

private void OnLoginRetEvent (MSDKLoginRet loginRet) 
{
    Debug.Log ("OnLoginRetNotify in Ligin"); 
    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_SWITCHUSER) {
        methodTag = "SwitchUser";
    } else if (loginRet.MethodNameId == (int) MSDKMethodNameID.MSDK_LOGIN_QUERYUSERINFO) {
        methodTag = "QueryUserInfo";
    } 
    // GetLoginRet is a synchronous interface and does not need to be processed in callback
//      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"); 

    string methodTag = "";
    if (baseRet.MethodNameId == (int) MSDKMethodNameID.MSDK_LOGIN_WAKEUP) {
        handleDiifAccount(baseRet);
    }

    if (baseRet.MethodNameId == (int) MSDKMethodNameID.MSDK_LOGIN_LOGOUT) {
        methodTag = "Logout";
    } else if (baseRet.MethodNameId == (int) MSDKMethodNameID.MSDK_LOGIN_WAKEUP) {
        methodTag = "Wakeup";
    }

    SampleInstance.showRetDialog(methodTag, baseRet);
}

//Need to remove the listener when destroying it
private void OnDestroy()
{
    MSDKLogin.LoginRetEvent -= OnLoginRetEvent; 
    MSDKLogin.LoginBaseRetEvent -= OnLoginBaseRetEvent; 
}

MSDKLogin::SetLoginObserver(new MSDKDemoBaseLoginObserver());

class  MSDKDemoBaseLoginObserver: public GCloud:: MSDK:: MSDKLoginObserver {
    // Login callback, including login, bind, autologin, switchuser, etc.
public:
    virtual void OnLoginRetNotify (const GCloud:: MSDK:: MSDKLoginRet &loginRet) {
        String ret = MSDKUtils::FormatJson(MSDKJsonManager::ToJson(loginRet));
        UMSDKDemoBase::showNormalAlert(ret);
    };
    // Logout callback; application wakeup callback
    virtual void OnBaseRetNotify (const GCloud:: MSDK:: MSDKBaseRet &baseRet) {
        String ret = MSDKUtils::FormatJson(MSDKJsonManager::ToJson(baseRet));
        if (baseRet.methodNameID == kMethodNameWakeUp) {
            // account inconsistency handling
            switch (baseRet.retCode) {
                case MSDKError::SUCCESS:
                    ret.append ("Use the original token to login; the game doesn't need to handle it"); 
                    break;
                case MSDKError::LOGIN_ACCOUNT_REFRESH:
                    ret.append ("New and old openid are the same; refrsh  login token; the game doesn't need to handle it"); 
                    break;
                case MSDKError::LOGIN_URL_USER_LOGIN:
                    ret.append ("There is no opened in the local; launch has token; use the new token to login; the game does not need to process this"); 
                    break;
                case MSDKError::LOGIN_NEED_SELECT_ACCOUNT:
                    ret.append ("Choose whether to switch the user"); 
                    break;
                case MSDKError::LOGIN_NEED_LOGIN:
                    ret.append ("Token is invalid; enter the login page"); 
                    break;
                default:
                    break;
            }
            return;
        }
        if (baseRet.retCode == MSDKError::NEED_REALNAME) {
            //The real name system does not need to be processed
            return;
        }
        UMSDKDemoBase::showNormalAlert(ret);
    };
};

4) Data structure

Details about MSDKLoginRet

It inherits MSDKBaseRet and contains basic information

2.2 Automatic Login

1) Function Description

Automatic login: MSDK can automatically get the local login state and go to the MSDK server to check whether the login state is valid. If there is not login state cache in the local or the login state returned by the server is invalid, the callback returns a login failure result.

info If you need to check if the local login status is expiry, you can obtain the login status through the GetLoginRet interface and check the tokenExpire field by yourself.

2) Interface Declaration

MSDKLogin.AutoLogin ();

MSDKLogin:: AutoLogin ();

2.3 Login

1) Function Description

Login the specified channel, get the third-party platform's login state and go to MSDK server to authenticate it; return MSDK's unified account.
Currently, only WeChat and QQ channels support QR code login. For details, please see WeChat Channel's Login Function and QQ Channel's Login Function.

2) Interface Declaration

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

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

3) Parameter Description

4) Demo code

MSDKLogin.Login ("WeChat");

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

2.4 Logout

1) Function Description

logout this channel

2) Interface Declaration

public static void Logout ()

static void MSDKLogin:: Logout ()

3) Demo code

MSDKLogin.Logout ();

MSDKLogin:: Logout ();

2.5 Binding (overseas supported only)

1) Function Description

The essence of binding is that multiple third-party accounts share an MSDK openid. The general usage scenario is that visitors log in the game through "Guest" channel, and then bind Facebook or Google account.

2) Interface Declaration

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

static void MSDKLogin:: Bind (const String &channel, const String &permissions)

3) Parameter Description

4) Demo code

MSDKLogin.Bind ("WeChat");

MSDKLogin:: Bind ("WeChat");

2.6 Get Login State

1) Function Description

In the game, get the game's login state information

info The expiration check of the login status has been removed from this interface. If you need to check if the login status is expiry, it is recommended to check it through the login callback or the TokenExpire value returned by this interface (TokenExpire identifies the expiration timestamp of the token's validity period).

2) Interface Declaration

public static MSDKLoginRet GetLoginRet ()

static bool GetLoginRet (MSDKLoginRet &loginRet)

3) Demo code

MSDKLoginRet ret = MSDKLogin.GetLoginRet ();

MSDKLoginRet ret; 
MSDKLogin:: GetLoginRet (ret);

2.7 Query Personal Account Information

1) Function Description

In the game, Get the user's current login channel's account information, including third-party account information

2) Interface Declaration

public static void QueryUserInfo ()

static void QueryUserInfo ();

3) Demo code

MSDKLogin.QueryUserInfo ();

MSDKLogin:: QueryUserInfo ();

2.8 Switch Game Account

1) Function Description

In the case of account inconsistency, choose whether to switch another account for login. In the case of account inconsistency: for example, when you login the game with a QQ account, press the Home button to return to the desktop and then start the game from WeChat Game Center. In this case, there will be a need to switch to WeChat account. This phenomenon is called account inconsistency. Generally, account inconsistency occurs with the domestic version.

2) Interface Declaration

public static bool SwitchUser (bool useLaunchUser)

static bool SwitchUser (bool useLaunchUser);

3) Parameter Description

info

1. If the player chooses to switch accounts, please set useLaunchUser to true. The result of switching accounts will be returned from the login callback of the game monitor
   
2. If the player chooses not to switch accounts, please set useLaunchUser to false. MSDK will automatically trigger the automatic login logic, but will not call it back to the game
   

4) Demo code

MSDKLogin.SwitchUser (true);

MSDKLogin:: SwitchUser (true);

2.9 Login With the Confirmation Code

1) Function Description

When login or binding fails, try to login again with the confirmation code to prevent the user from launching the authorization login UI again. The confirmation code is returned by the backend.

2) Interface Declaration

public static void LoginWithConfirmCode (string confirmcode)

static void LoginWithConfirmCode (const String &confirmCode);

3) Parameter Description

4) Demo code

MSDKLogin.LoginWithConfirmCode (confirmcode);

MSDKLogin:: LoginWithConfirmCode (confirmcode);

2.10 Guest resetting function

1) Functional description

Reset the guest. When MSDK is logged in again with the guest channel, a new guest will be generated.

2) Interface declaration

public static void ResetGuest()

static void ResetGuest()

3) Demo code

MSDKLogin.ResetGuest();

MSDKLogin::ResetGuest();

III. Simulated login in the Editor environment

During its development phase, your game needs to log into the Editor environment for joint debugging. MSDK currently provides a simulated login scheme for games to conduct joint debugging in the Editor environment.

Please refer to 5. FAQs -> Login -> Simulated Login in the Editor Environment

IV. Description of the guest mode and the binding function

4.1 Function description **

The guest mode refers to a login mode in which the user logs in a game with the identity of a guest each time (for example, directly enter a game without a login button) and performs social relation binding in the game to achieve the account association to retrieve the account.

Description of game scenarios using the guest mode:

1. Generally, the game has no channel login button, and a player can directly enter the game with the guest identity
2. In the game's novice tutorial and game's setting UI, there is the function of binding social relations accounts. The bound accounts are used to pull the user's friends and retrieve accounts.
3. Account retrieval is triggered via binding. When the bound account has any progress in retrieval, an error and a confirmation code will be returned. The account can be retrieved via the confirmation code login interface.

! [Guest binding process] (Images / login_guest_mode_bind.png)

4.2 Login

Log in the game with the guest channel every time

4.3 Bind an account

Bind an account through the binding interface. The bound account can be used to get the user relationship and retrieve accounts.

[info] During the test process, if you need to unbind your account for testing, please contact MSDK Assistant via your corporate WeChat

4.4 Restore an account

1. Triggered by a binding failure. When there is account progress on the bound channel, the tripartite error code is: 1403
2. Log in the game with the confirmation code login interface by judging the error code

4.5 Reset the progress

Since the user logs in the game through the guest mode each time, if the user wants to restart the process, the user can delete the current guest through the guest resetting interface (only delete the guest account, which can be retrieved through the bound design account)

Note: If the guest is not bound to any account, resetting the progress will cause the guest account to be lost

V. Real name authentication

According to the relevant requirements of national laws and regulations, online game users need to make real-name registration with a valid ID before being able to log into any game. In order to reduce the burden of game developers, we have encapsulated the real-name authentication operation into the game's login process. When the system returns a prompt requiring he real-name authentication after login, the WebView component will be launched automatically to open the real-name authentication page. After the player has completed real-name authentication, he or she can log in to the game. This way, the real-name authentication process requires no additional development of game developers.

[info] Note:

1. Real-name authentication requires access to the WebView component
   
2. The real-name authentication page is displayed in full screen. If the player clicks the "Return to Login" button, the login status returned to the game is that the login is unsuccessful.
   
3. Real-name authentication is a relevant service provided by Tencent Center Console
   
4. Only China-made games have the real-name authentication process. Foreign games do not have.
   

![Real name authentication page] (Images/login_real_name_auth.png)

VI. Check Universal Link access function

Version description

V 5.11 and higher versions

1) Function description

These versions add the self-check function to help developers troubleshoot problems encountered during the SDK access process. Currently, the function only supports WeChat channel. In the test environment, the function is used for testing. In the formal environment, this function cannot be used.

2) Interface code

The ‘channel’ field is filled in "WeChat", and other fields are reserved fields and are filled in blank strings

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) Demo code:

Interface call

MSDKLogin.CheckUniversalLink(("WeChat");

MSDKLogin::CheckUniversalLink("WeChat");

callback function

// Logout callback, and app wakeup callback	
 public void OnLoginBaseRetEvent(MSDKBaseRet baseRet)	
{	
    Debug.Log("OnBaseRetNotify in Login");	
    if (baseRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_CHECK_UL)	
    {	
        //Handle the callback and check the result of Universal Link	
    }	
    mCurrentTestMgr.ShowLogInNewLine(methodTag + Tools.Instance.GetRetString(baseRet));	
}

// Logout callback, and app wakeup callback	
void OnBaseRetNotify(const MSDKBaseRet &baseRet) {	
    if (baseRet.methodNameID == kMethodNameCheckUniversalLink) {	
        //Handle the callback and check the result of Universal Link	
    }	
    handleCallback(baseRet, baseRet.methodNameID);	
};

4) Field description

The check result will be placed in baseRet.ExtraJson in the format of a JSON string

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

success marks the current step check result    
errorInfo is the prompt information    
suggestion is the operation information to prompt developers     
Description of the value of step:    
    step = WXULCheckStepParams: parameter check
    step = WXULCheckStepSystemVersion: current system version check
    step = WXULCheckStepWechatVersion: WeChat client version check
    step = WXULCheckStepSDKInnerOperation: WeChat SDK's internal operation check
    step = WXULCheckStepLaunchWechat: check the launch of WeChat by App
    step = WXULCheckStepBackToCurrentApp: check the current App returned by WeChat
    step = WXULCheckStepFinal: final check

These 7 steps will be called back in turn. When WXULCheckStepFinal is called back, this indicates that the check is passed and SDK is accessed successfully. If the success of any step's callback is false, the process will be terminated and the step will be no longer called back later. You can look for the cause of the current step error according to errorInfo, and fix the problem according to the suggestion.

VII. FAQ

1. To ensure security, MSDK login status is limited by the period of validity, which is generally 30 days. For considerations of the replaced device's login and security problems, the login status will also expire in advance.
   
2. Since MSDK 5.4.0000 (corresponding to GCloud 2.0.10), the anti-reentry restriction on login has removed, but the login timeout detection is still retained. In systems higher than iOS9, if you click "Return to xx game" in the upper left corner of the system or return directly to the game through the Home button, there will be no login callback. At this time, if you call the login interface again, you can restart the login process (the old version will return an InProgress error) and the last login process will be invalid.
   
3. How to judge a game launched through QQ/WeChat Game Center? In MSDK 5.2.000 and earlier versions, such a game is judged by the game_data field in the ExtraJson parameter in the wakeup callback. WeChat is: WX_GameCenter; QQ is: sq_gamecenter.
   MSDK5.3.000 and later versions make judgment through the 'param' field in the 'ExtraJson' parameter in 'wakeup' callback. This field can receive all the fields returned by the Game Center. QQ is: launchfrom:sq_gamecenter; WeChat Android is: _wxobject_message_ext:WX_GameCenter; WeChat iOS is: messageExt:WX_GameCenter.
   
4. How to get pay_token?
   pay_token of QQ channel can be obtained by parsing the pat_token field in the login callback 'channelInfo'; Other channels do not have pay_token. There is the 'token' field in the outermost layer of MSDK's login callback. China-made games do not need to do any processing on this token. Overseas games need to use Interface for getting third-party channel tokens to turn this token into the corresponding channel token.
   Note: The recommended payment authentication mode is to obtain the third-party openid and token and then go to the specified platform to make payment authentication as needed.
   
5. Error code
   Refer to Error Code Description.