Outline

MSDK login function is the fastest way for players to login the game: players can use QQ account, WeChat account and guest account to login your game; the function can be used for iOS, Android mobile phones and tablet devices.

You can refer to the figure below to put the login button on the game’s login page. Upon requirements of Appstore, the guest login button should be placed at the first position.

MSDK login can create the following experience:

1) Quickly create a game login account： MSDK login allows users to quickly and easily create a game login account within the game, without setting a password (which may be forgotten later). This simple and convenient experience can produce a higher user conversion rate.

2 Personalized game operation： After logging in MSDK, you can be authorized to get the player's avatar and basic information to facilitate the operation of the game. This can produce a higher user retention rate.

3) Social function： After logging in MSDK, the player can share messages among friends, establish the game guild group, etc., to promote the sharing of the in-game experience.

Function 1 QQ login

You can call MSDK interface to launch mobile QQ client to guide the player to grant authorization to the game. The general login workflow is as follows.

1) On the game's login page, click "Play with QQ friends"

2) On mobile QQ's login page, complete authorization

In which every area is described as follows:

Function 1.1:"Authorize login" button. With a Click on the button, you can complete login authorization for the game.
Function 1.2: In the list of permissions authorized to the game by the users, especially note if it contains the following item: "Access your QQ friends’ information in the app". If no, the error code "100030" will appear when you try to access the user's relation chain. It is necessary to confirm that WGPlatform::GetInstance()->WGSetPermission(eOPEN_ALL) is called before the QQ login; <br>Function 1.3: "Return" button. After the user clicks the button, the login will be cancelled, and the game receives login callback and flag iseFlag_QQ_UserCancel`.
Function 1.4: "Switch account" button. When the user clicks the button, the user can switch mobile QQ account in mobile QQ and use the switched account to authorize the game.

3) Login succeeds. Return the page to select a zone server for the game or directly play the game

Function 1.5: The game's own "Enter the game" button，which has nothing to do with MSDK functions.
Function 1.6: The game's "Switch account" button. Call MSDK's logout interface, and then return to the game's login page.

Function 2 WeChat login

You can call MSDK interface to launch WeChat client to guide the player to grant authorization to the game. The general login workflow is as follows.

1) On the game's login page, click "Play with WeChat friends"

2) On WeChat login page, complete authorization

Function 2.1: "Authorize login" button. With a Click on the button, you can complete login authorization for the game.
Function 2.2: The list of the user's permissions to authorize the game, where the "Find friends who use the app with you together" items means that the user's relation chain can be gotten. This permission requires premium games to submit application to the collaboration & planning group to open it in the PR2 stage. For details, please consult with the game's person in contact with Tencent.
Function 2.3: "Cancel" button.After the user clicks the button, the login will be cancelled, and the game receives a login callback and flag is eFlag_WX_UserCancel。
Function 2.4: "Retry" button. The user clicks the button and can retry to authorize login in WeChat App.

Function 3: Guest login

Because Apple requires that the user can have a complete experience of the gaming workflow without providing any account password, MSDK provides the guest login to facilitate players’ quick access to your game to meet this requirement. At present, the guest login is only limited to iOS terminal. In addition, since the guest mode is only limited to the local experience, and the guest data will change when devices are switched. Games can remind users kindly by referring to the following way:

Access Guide

1 Preconditions

1) You have registered games on Tencent open platform and passed the audit, or your staff in contact with Tencent have helped you register games through internal channels.

2) You have completed initialization according to the initialization module's description initialization。

3) Make sure that your game login permission has been opened. After the completion of the game registration, the permission has been opened by default. If you call the login interface, it returns "-303, no permission". At this time, please contact MSDK joint debugging support staff.

2 Refer to demos

For mobile QQ login examples, please refer to the login section of MSDKDemo/LoginViewController.mm.

For WeChat login examples, please refer to the login section of MSDKDemo/LoginViewController.mm .

3 Call this module's other interfaces

After completing Step1-Step2, you have access to this module and can directly call other interfaces of the module without any additional configuration. Every part of the module is described below.

1)Authorized login: Launch mobile QQ/WeChat client or web page(mobile QQ has yet to be installed) for authorization.

2)Guest login: Authorize under the guest mode.

3)Account inconsistency handling: mobile QQ/WeChat platform is required to be able to handle account inconsistency scenes where the platform and the game are logged in by the same user with different accounts.

4)Get token: Call this interface at the place where the game requires a token (such as payment) to get the current user's token information.

5)Logout: When the user needs to log off or switch account, he or she can call this interface to clear the user's login token information.

Universal Link

Universal Link is a mechanism introduced by Apple from iOS 9 to open up the jump between Web and App. When you open a link associated with an app in Safari or WebView, it will automatically jump to the app without losing parameters and content. For a detailed description of the use, related configuration and platform side (QQ, WeChat) support of Universal Link, please refer to Navigation-->Initialization-->Left Directory: iOS-->Universal Link.

Detect Universal Link

Summary description

MSDK 3.3.15 version has started to add a detection interface after access to Universal Link. The interface can be used to detect whether Universal Link is accessed correctly. Currently, it only supports WeChat platform, and can only be called in MSDK's test environment. Please do not call it in the release environment

The test result can be viewed through the OnCheckULNotify callback.

1) Demo code

//Set callback
MyObserver* ob = MyObserver::GetInstance();
WGPlatform::GetInstance()->WGSetObserver(ob);
//View WeChat UL
WGPlatform::GetInstance()->WGCheckWXUniversalLink();
// Callback example
void MyObserver::onCheckULNotify(CheckULRet& checkUlRet)
{
    if (checkUlRet.success)
    {
    //Tested successfully
    }
}

2) CheckULRet data structure introduction

//CheckULRet data structure introduction

typedef struct sCheckULRet
{
int step; // Test steps
    bool success; // Whether the test is successful
    std:: string errorInfo; // Error information
    std:: string suggestion; // Suggested solutions for developers
    sCheckULRet() {}
} CheckULRet;

// Among them, 'step' is divided into 7 steps, and the corresponding enumeration type is as follows:

typedef enum _eULCheckStep {
    eULCheckStepParams, // Parameter check
    eULCheckStepSystemVersion, // Current system version check
    eULCheckStepWechatVersion, // WeChat client version check
    eULCheckStepSDKInnerOperation, // WeChat SDK internal operation check
    eULCheckStepLaunchWechat, // Check if App can launch WeChat
    eULCheckStepBackToCurrentApp,// Check if WeChat can return the current App
    eULCheckStepFinal, // Final check
} eULCheckStep;

// These 7 steps will be called back in sequence. When eULCheckStepFinal is called back, this means that the test is passed and Universal Link is successfully connected. If 'success' of any step's callback is false, the process is terminated and there will be no subsequent callbacks. You can check the cause of the current step error according to 'errorInfo' and fix the problem according to the suggestion.

Sign in With Apple

msdk 3.3.12 version starts to support Sign in With Apple .

Configuration instructions

1 Apple Developer Potral configuration

Before implementing the "Sign in With Apple" function, you need to do the following work at Apple Developer Portal:

• Obtain the Team ID;
• Create 'client_id' used to identify the source of the request when sending a request to Apple;   - For iOS apps, 'client_id' is also App ID (Bundle ID)
• Create a description file
• Create 'key' used to calculate 'client_secret' and the corresponding 'Key ID';

1.1 Get Team ID

• Log in Apple Developer Portal, click Account;
• Click on 'Membership' in the left sidebar to see 'Team ID';

1.2 Create App ID

• Log in Apple Developer Portal, click Account;
• Click Certificates, IDs & Profiles on the left sidebar;

• Click Identifiers in the left sidebar, and then click the blue plus sign;

• The first step is to select App IDs and click Continue;

• Enter Description and Bundle ID, and check Sign in With Apple under Capabilities;

• Click 'Continue', and then click 'Register';

For the existing App ID, just find the App ID that wants to add "Sign in With Apple" and then check "Sign in With Apple" under "Capabilities".

1.3 Create a description file

• Log in Apple Developer Portal, click Account;
• Click Certificates, IDs & Profiles on the left sidebar;

• Click Profiles on the left sidebar, and then click the blue plus sign;

• Select the certificate type, click Continue

• Select the App ID registered in the previous step, and click Continue

• Select the signing certificate and click Continue

• Select the device, and then click 'Continue'

• Click 'Continue' to name the description file

• click 'Download' to download the description file

• Install the downloaded description file into the development or packaging environment

For the existing description file, you only need to add "Sign in With Apple" to "Capabilities" of App ID and then re-edit, save and download it

1.4 Create 'Key' and obtain 'Key ID'

• Log in Apple Developer Portal, click Account;
• Click Keys on the left sidebar, and then click the blue plus sign;

• Enter the Key Name and check Sign in With Apple ;

• Click Configure next to Sign in With Apple , select the App ID configured with the Sign in With Apple function as the Primary App ID, and click Save;

• Click 'Continue', and then click 'Register';
• Download the Key file (download only once, make sure not to lose it) and get the Key ID

Configure the contents of the App ID, Team ID, Key ID and Key files obtained in the above process into Feiying system when the game accesses Sign in With Apple . The configuration path is: Game Management -> My Game -> SDK Parameters -> Search: Edit iOS Information -> MSDKV3 Apple Channel Configuration (joint debugging environment/release environment ).

2 iOS project configuration

Apple supports Apple ID login since XCode 11. When the running iOS system version is iOS 13 and above, the function works normally; otherwise, the login will return an error code "8002 eFlag_Apple_NotSupport"

2.1 Add Capability in Xcode

2.2 Xcode BuildPhases configuration

Add 'AuthenticationServices.framework' in Xcode BuildPhases, and set 'Status' to 'optional' at the same time. Xcode 11 compilation does not need to set to 'optional' but just takes the default value.

UI requirements for "Sign in With Apple "

[human-interface-guidelines] is the UI style required by Apple, with clear UI requirements. What developers need to pay attention to is:

Requirements on the appearance and color of the button

The login button has three appearances: white, bordered white and black. It is required to choose a button appearance that fits the background

White button

Used for a dark or colorful background

Bordered white button

Used for a white or light white background that cannot provide sufficient contrast

Black button

Used a white or light background which provides sufficient contrast

Requirements on the button's location

• Use the "Sign in With Apple " button which has the same size as other login buttons
• Avoid any button which can be seen only when scrolling
• By default, the "Sign in With Apple" button has rounded corners
• In addition, the button cannot have any ratio loss when it is stretched or compressed
• The button needs to be above all other login modes

Other concerns

Apple provides two types of documentation, "Sign in With Apple " and "Continue With Apple", for the login button (Objective-c and Swift native UI components). The game developer can choose the documentation that matches its login experience. The language of the documentation will be localized with the smartphone system's language.

Instructions about the openID of "Sign in With Apple"

All apps under the same developer account have the same userID returned under the same iCloud account. MSDK backend transmit this userID as openID.

Description of changes in userID of iCloud account when signing in Apple

Authorized login

Summary

Launch mobile QQ/WeChat client or web page(mobile QQ has yet to be installed) for authorization. After the user authorizes, the game will be notified through OnLoginNotify callback to get LoginRetlogin information.

Registration callback

1)Function description

To receive MSDK's login callback, you need to set the callback Observer. It is suggested to set it at Two entries for starting the game. The login result will be notified to you through the callback function OnLoginNotify.

2)Interface declaration

void WGSetObserver(WGPlatformObserver* pObserver);

3)Parameter description

4)Return value

None

5)Demo code

//Set callback
MyObserver* ob = MyObserver::GetInstance();
WGPlatform::GetInstance()->WGSetObserver(ob);

//Callback example
void MyObserver::OnLoginNotify(LoginRet& loginRet)
{
    if(loginRet.flag == eFlag_Succ)
    {
        //login succeeds
        //Game TODO: Enter the game
    }
    else if (loginRet.flag == eFlag_NeedRealNameAuth)
    {
        //It is needed to carry out real-name authentication. The business itself can set real-name authentication workflow. Configure MSDK_REAL_NAME_AUTH_SWITCH in info.plist; default: 0
        //0, the business does not need to perform any operation and just stays in the login page. MSDK automatically pops up real-name registration page to guide the user to register. After the registration is completed, the user will be guided to login again.
        //1, the business does not need to perform any operation and just stays in the login page. MSDK automatically pops up real-name registration page to guide the user to register. The business needs to monitor the login callback again. After the real-name registration succeeds, MSDK will automatically call the local token login interface for automatic login
    }
    else
    {
        //Login failed
        //Game TODO: Remind the player of relevant information according to flag
    }
}

6)Special description

V3.3.21 Version starts adding WeChat authorization scope field transmission capability in the authorized login callback, as follows:

In the authorized login callback OnLoginNotify, add WeChat authorization scope field transmission capability. The business side can determine whether the user has an authorized relationship permission based on this field; the scope field is in the extra_json of LoginRet, as shown as follows:

    The scope style of the relationship permission authorized by the user:
    loginRet.extra_json = "{\"scope\":\"snsapi_userinfo,snsapi_friend,snsapi_message\"}";

    The scope style of the relationship permission unauthorized by the user:
    loginRet.extra_json = "{\"scope\":\"snsapi_userinfo,snsapi_message\"}";

Warning:

1.The authorized login scope transmission is limited to WeChat platform, and QQ platform does not support it.

2.When the unauthorized login is made, the personal information and the friend relationship are in the authorization page by default. If a separate authorization page is required for the friend relationship:

• The WeChat platform needs to apply to the WeChat (Enterprise WeChat wxgame) platform to open it.
• The QQ platform currently no longer supports this feature's configuration. Please pay attention to subsequent platform version updates.

7)Name interpretation

ePlatform definition description

LoginRet definition description

Recommended login process

Call login

1)Function description

You can call the WGLogininterface to specify the platform to launch authorized login or automatic login. The call result will be notified by the callback function OnLoginNotifyto you. The function declaration and the demo code are as follows:

2)Interface declaration

void WGLogin(ePlatform platform = ePlatform_None);

3)Parameter description

4)Return value

None, login information will be returned to the game through OnLoginNotify callback

5)Demo code

//QQ login; it is needed to set QQ-related permissions before the QQ login
WGPlatform::GetInstance()->WGSetPermission(eOPEN_ALL);
WGPlatform::GetInstance()->WGLogin(ePlatform_QQ);
//WeChat login
WGPlatform::GetInstance()->WGLogin(ePlatform_Weixin);
//Guest login(only for iOS)
WGPlatform::GetInstance()->WGLogin(ePlatform_Guest);

6)Special description

• The respective bugs of WeChat and mobile QQ can lead to the game's failure in receiving the login callback in different scenes. After the game calls WGLogin, you should make a timeout judgment when returning to the game. If the delay exceeds 15s, it will be deemed as login timeout. Here, scenes in which the callback fails to be received include but are not limited to:
  1) In systems above iOS9, click the "Return xx game" button (built-in button in the system) at the top left corner of the authorization page, there will be no login callback

• MSDK version 3.3.22 starts to support WeChat video number authorization, call the WGLogin interface, pass in ePlatform.ePlatform_WeixinVideoLive, and obtain tdiAuthBuffer in the callback of MSDK for subsequent live login.

Precautions for authorization of video number:

• Video account live broadcast authorization currently only supports WeChat channel
• In the login callback, tdiAuthBuffer exists in the _extra_json field and is returned in Base64 format. It can be obtained through Json parsing. Please use standard Base64 decoding before use
• MSDK only returns the content of tdiAuthBuffer. For specific usage methods, contact MSDK Assistant for docking

7)Term interpretation

None

Call login(used by 3.0.8 and higher versions)

1)Function description

Have the function of preventing repeated clicks and preventing overtime. You can call WGLogin interface to launch authorized login or automatic login for the specified platform. If the interface is called successfully, eFlag_Succ will be returned. eFlag_Logining is returned when you are logging in. The login result will be informed to you via the callback function. The function's declaration and the demo code for calling it are as follows:

2)Interface declaration

eFlag WGLoginOpt(ePlatform platform = ePlatform_None, int overtime = DEFAUTL_LOGIN_OVERTIME);

3)Parameter description

4)Return value

Return eFlag_Succ if successfully, and return eFlag_Logining if being logged in. The login information is returned to the game via WGPlatformObserver's callback

5)Demo code

//QQ login; it is needed to set QQ-related permissions before the QQ login
WGPlatform::GetInstance()->WGSetPermission(eOPEN_ALL);
WGPlatform::GetInstance()->WGLoginOpt(ePlatform_QQ,20);
//WeChat login
WGPlatform::GetInstance()->WGLoginOpt(ePlatform_Weixin,20);
//Guest login(only for iOS)
WGPlatform::GetInstance()->WGLoginOpt(ePlatform_Guest,20);

6)Special description

MSDK adds the login timeout callback

7)Term interpretation

None

guest login

Summary

Because Apple requires that the user can have a complete experience of the gaming workflow without providing any account password, MSDK provides the guest mode to facilitate players’ quick access to your game to meet this requirement. At present, the guest mode is only limited to iOS terminal. The login process and the way of getting tokens in the guest mode are the same as those in mobile QQ and WeChat. About them, please refer to Authorized login and Get tokens. In the guest mode, aside from login and getting tokens, attention shall be given to matters below:

1 Guest mode payment Guest mode payment is the same as mobile QQ and WeChat payment: Midas registration payment (supplementary delivery) interface shall be first called, and then the payment interface shall be called. At the time of payment, pay attention to guest mode's session_id and session_type values, which are:

//At the time of payment, guest mode session_id and session_type are fixed as：
sessionId = "hy_gameid";
sessionType = "st_dummy";

2 Interfaces which the guest mode does not support The guest mode does not support some interfaces, such as relation chain, LBS and notice. If the game calls these interfaces in the guest mode, the return value's corresponding Ret flag is eFlag_InvalidOnGuest. Please pay attention to this flag.

3 Guest resetting After GameServer clears relevant data, the guest resetting interface can be called to clear the guest account data left by MSDK at the terminal. In the next login, the guest mode will generate a new guest account.

4 Alerts for players Since the guest mode does no need any account password, the guest mode account and game data are only used in the current machine. The following scenes will lead to the loss of guest data:

1) After iPhone upgrades or downgrades its system, it is reactivated and is set as a new iPhone.

2) Restore and erase iPhone data

3) Delete and reinstall games

So the user will be kindly reminded at the time of guest mode login. For specific reminders, refer to

Guest login process

In Guest mode, login is divided into two sequences: registration and login. However, the difference between the two scenes is shielded by MSDK, and game developers don't need to care about the difference between the two. Here is only a program description:

Comparison of account mode and Guest mode in terms of workflow

Registration callback

Refer to Authorized login Registration callback

Call login interface

Refer to Authorized loginCall the login interface

Call the guest ID refreshing interface

1)Function description

Refresh ID in the guest mode.

2)Interface declaration

void WGResetGuestID();

3)Parameter description

None

4)Return value

None

5)Demo code

WGPlatform::GetInstance()->WGResetGuestID();

6)Special description

In the release environment version, do not call the guest resetting interface, so as to avoid user data loss.

7)Term interpretation

None

Scan-code login

1)Function description

Launch the login QR code display interface. The player can scan QR code through another mobile phone which has logged on the WeChat/QQ corresponding social account. After authorization according to prompts, the game can get the login token information. This mode is generally used for TV or tablet environment, or mobile phones not installed with the platform client.

Remarks: 3.3.16 version starts to support the QR code scanning-based login for QQ.

2)Interface declaration

void WGQrCodeLogin(ePlatform platform);

3)Parameter description

4)Return value

None, login information will be returned to the game through WGPlatformObserver callback

5)Demo code

WGPlatform::GetInstance()->WGQrCodeLogin((ePlatform)Platform);

6)Special description

For the scan-code login permission: non-premium games apply for it from WeChat via the game mail, and premium games can get it through the collaboration & planning group.

The drawn QR code image is valid for 5 minutes, and expired scan-code can't login successfully.

7)Name interpretation

None

WeChat video channel authorization (cross-platform)

1)Function description

MSDK encapsulates the video channel authorization interface. After invoking the WGChannelPermissionAuth interface, the current WeChat passes `snsapi_channels_livestream` to it and obtains `tdiAuthBuffer` in MSDK callback for subsequent livestreaming login. 3.3.26 Version starts adding this interface

2)Demo code

Please use the WGChannelPermissionAuth interface and set the parameters to `ePlatform.ePlatform_WeixinVideoLive` and `snsapi_channels_livestream`. The callback is received in the ChannelPermissionAuthEvent interface authorized by the video channel. Invocation example:

// ePlatform_WeixinVideoLive refers to WeChat Video Channel
// snsapi_channels_livestream is also a special mark permission

WGPlatform.Instance.WGChannelPermissionAuth(ePlatform.ePlatform_WeixinVideoLive, "snsapi_channels_livestream");

Callback example:

MsdkEvent.Instance.ChannelPermissionAuthEvent += (LoginRet ret) =>
{
    Debug.Log(ret.ToString());
    message = ret.ToString();
    switch (ret.flag)
    {
        case eFlag.eFlag_Succ:
            // Video channel authorization succeeds
            Debug.Log("Video channel authorization succeeds!");
            break;
        case eFlag.eFlag_WX_UserCancel:
            Debug.Log("Video channel authorization - Cancelled by the user!");
            break;
        case eFlag.eFlag_WX_UserDeny:
            Debug.Log("Video channel authorization - Rejected by the user!");
            break;
        default:
            // Video channel authorization fails
            Debug.Log("Video channel authorization fails!");
            break;
    }
};

Return result:

{
	"_flag": 0,
	"_desc": "",
	"_platform": 8,
	"_open_id": "",
	"_user_id": "",
	"_pf": "",
	"_pf_key": "",
	"_token": [],
	"_prajna_ext": "",
	"_extra_json": "{\"tdiAuthBase64\":\"Cp4BMV9CZ0FBYTRpb3RxYVA3aUgwQ1AzejkzRlZWY0Y4OG55NmZPZlZtaXh3ZUZNVHMwYVdJK0FF\\nVFpQR1c1SnpKbDdySWpnSnV6MEJRL2EyUXlQQlJWMG0xejNlTzRTR25ZN1VvSmt4N01idmxyemVp\\nOGNRU21lSnkxZGt6M0JubTFsNkgxZGJIMWVYRWNMMDdJa3dlYzJQMVZCUmhnPT0SF2lsaW5rYXBw\\nXzA2MDAwMDNiNzhjMTc2\\n\"}"
}

3)Warning

• Video channel authorization currently only supports WeChat video channel
• Currently pass in snsapi_channels_livestream; WeChat may change this in the future
• In the login callback, `tdiAuthBuffer` exists in the `_extra_json` field and is returned in the format of Base64. It is obtained through Json parsing. Please use the standard Base64 to decode it before using it
• This function does not limit the login channel and the login status, that is, the interface can be invoked across platforms
• MSDK only returns the content of `tdiAuthBuffer`. As for its usage method, please contact MSDK Assistant for specific usage methods

Third-party platform launches login

MSDK 3.3.21 and above versions need to pay attention to this

In order to resist the Zuhao platform, MSDK 3.3.21 starts to block the quick login capability of the QQ Game Center during the startup of a game. The user will not be able to enter the game successfully from the QQ Game Center without logging into the game at first. Guidelines on the handling of account inconsistency scenes arising from the startup of games in the QQ Game Center (game evaluation processing):：

1) The game is not logged in: stay on the login page or call QQ login to initiate QQ authorization
2) The game is logged in:
    2.1) There is no account inconsistency: wait for the MSDK login callback; the user can enter the game if the user logs into it successfully
    2.2) There is account inconsistency:
        2.2.1) The user selects a local account: wait for the MSDK login callback; the user can enter the game if the user logs into it successfully
        2.2.2) The user chooses to initiate an account: return to the login page or call the QQ login to initiate the QQ authorization page

Warning:

The game which is updated to version 3.3.21 need to contact the QQ Game Center to cancel the accesstoken and paytoken fields carried in scheme when the game is started in the QQ Game Center to avoid affecting the login state of the logged-in user in the game.

1)Function description

In the mobile QQ game list or share links, a player can directly pass the mobile QQ login account information to the game to login to the game without re-authorization of the game.

• Environmental dependence:

  1. MSDK 1.8.0i and above;
  2. Mobile QQ 4.6.2 and above;
  3. The game must be configured with scheme:

  - Success means to launch the game and to carry openId, accessToken, payToken, pf and pfKey.

2)Interface declaration

To receive the game launch callback from MSDK, you need to handle OnWakeupNotify callback.

• The results of a third-party platform launch login and account inconsistency are returned in wakeupRet's flag. The relevant flag is described as follows:

eFlag_Succ: 
There is no account inconsistency, and the game is successfully aroused. In this case, the launched App's URL does not carry any token. This is consistent with the launch in previous versions.
eFlag_AccountRefresh: 
There is no account inconsistency. MSDK has updated the local account token with the token information carried in the launched App's URL.
eFlag_UrlLogin：
There is no account inconsistency, and the game is logged in successfully through the third-party platform information. After receiving the flag, the game directly reads the token from LoginRet struct for the game's authorization process.
eFlag_NeedLogin：
Users can't login the game with either the game's local account or the launched account. After the game receives this flag, it needs to pop up the login page to allow users to login it.
eFlag_NeedSelectAccount：
There is account inconsistency between the game's local account and the launched account. After receiving this flag, the game needs to pop up a dialog box to allow the user to select a login account.
When flag is eFlag_NeedSelectAccount, the game needs to pop up a dialog box for the user to choose to use the original account or the account carried by the third-party platform. This is the logic that mobile QQ platform is required to achieve. Otherwise, the platform will be rejected to be online by the auditor.

Prompt example (the UI is achieved by game developers separately)  After the user selects an account, it is needed to call WGSwitchUser interface to handle the account inconsistency in the follow-up logic. (Both options need to call the following interface. For details, please see the demo code)

bool WGSwitchUser(bool flag);

Description: login the game through the external launched URL. This interface is called when account inconsistency occurs and the user chooses to use an external launched account. Parameter: - flag - When it is YES, this means that the user needs to switch to the external account. At this time, the interface will use the login data saved last time in case of account inconsistency for the user to login the game. After the user logs in the game successfully, the result will be called back via onLoginNotify. If there is no token or the token is invalid, the function will return NO and onLoginNotify callback will not happen. - NO represents that the user continues to use the original account. At this time, the saved account inconsistency data will be deleted to avoid confusion. Return NO If there is no token or the token is invalid; otherwise, return YES.

3)Parameter description

4)Return value

None

5)Demo code

• Add the code to set the callback while launching App

-(BOOL)application:(UIApplication*)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
{
    NSLog(@"url == %@",url);
    WGPlatform* plat = WGPlatform::GetInstance();
    WGPlatformObserver *ob = plat->GetObserver();
    if (!ob) {
        MyObserver* ob = new MyObserver();
        ob->setViewcontroller(self.viewController);
        plat->WGSetObserver(ob);
    }
    return [WGInterface HandleOpenURL:url];
}

• The launched callback code examples are as follows:

void MyObserver::OnWakeupNotify (WakeupRet& wakeupRet)
{
    switch (wakeupRet.flag) 
    {
        case eFlag_Succ:[viewController setLogInfo:@"Wake up successfully"];
        break;
        case eFlag_NeedLogin:[viewController setLogInfo:@"Account inconsistency occurs. It is needed to enter the login page"];
        break;
        case eFlag_UrlLogin:[viewController setLogInfo:@"Account inconsistency occurs. Successfully login the game via external launch"];
        break;
        case eFlag_NeedSelectAccount:
        {
            [viewController setLogInfo:@"Account inconsistency occurs. It is needed to prompt the user to select an account"];
            UIAlertView *alert = [[[UIAlertView alloc]initWithTitle:@"account inconsistency" message:@"Account inconsistency is found. Please choose which account for logging in the game" delegate:viewController cancelButtonTitle:@"Do not switch. Use the original account" otherButtonTitles:@"Switch to the external account for login", nil] autorelease];
             [alert show];
        }
        break;
        case eFlag_AccountRefresh:[viewController setLogInfo:@"External account is the same as the login account. Update the local token with external token"];
        break;
        default:
        break;
    }
    if(eFlag_Succ == wakeupRet.flag ||
eFlag_NeedLogin == wakeupRet.flag ||
eFlag_UrlLogin == wakeupRet.flag ||
eFlag_NeedSelectAccount == wakeupRet.flag ||
eFlag_AccountRefresh == wakeupRet.flag)
    {
        [viewController setLogInfo:@"Wake up successfully"];
    }
    else
    {
        [viewController setLogInfo:@"Wake up fails"];
    }
} 
- (void)alertView:(UIAlertView *)alertView clickedButtonAtIndex:(NSInteger)buttonIndex 
{
    BOOL switchFlag = NO;
    switch (buttonIndex) 
    {
        case 0:
        NSLog(@"The user chooses not to switch account");
        break;
        case 1:
        {
            NSLog(@"The user chooses to switch account");
            switchFlag = YES;
        }
         break;
        default:
         break;    
    }
    WGPlatform* plat = WGPlatform::GetInstance();
    plat->WGSwitchUser(switchFlag);

6)Special description

• Only mobile QQ 4.6 and higher versions support quick login.
• Scheme in URL Types needs to be configured with tencentlaunch + AppID, so that it can carry login information when launched.

Account inconsistency handling

General description

The user launches the game from the platform and enters it. Because the account is inconsistent (the platform is inconsistent or the platform is consistent but the account is inconsistent), it needs the game to pop up a box to prompt account inconsistency.As for the detailed description of account inconsistency, please refer toAccount inconsistency specification documentation

Handle callback

To receive the game launch callback from MSDK, you need to handle OnWakeupNotify callback.

1)Function description

The information generated when the platform launches the game will be passed to the game via OnWakeupNotify.

2)Interface declaration

virtual void OnWakeupNotify(WakeupRet& wakeupRet) = 0;

3)Parameter description

4)Return value

None

5)Demo code

void MyObserver::OnWakeupNotify(WakeupRet& wakeupRet)
{
    switch (wakeupRet.flag)
    {
        case eFlag_Succ:
            //After local account login succeeds, the player can directly enter the game; the platform call also the automatic login interface WGLogin() but need to wait for login callback
            break;
        case eFlag_NeedLogin:
            //In case of no valid token, logout of the game to let the user re-login
            break;
        case eFlag_UrlLogin:
            //There is no account information in the local. In this case, the platform can automatically login the game with the launched account but need to wait for login callback
            break;
        case eFlag_NeedSelectAccount:
            //Pop up a prompt box to let the user to select a login account, and call WGSwitchUser interface according to the user's choice 
            break;
        case eFlag_AccountRefresh:
            //the external account is the same as the login account; use the external token to update the local token, and need to wait for login callback
            break;
        default:
            break;
    }
}

6)Special description

When eFlag_NeedSelectAccount is received, this means that account inconsistency has been triggered. At this time, the game needs to pop up a prompt box to facilitate the user to select an account which the user needs to login, and calls WGSwitchUser: interface according to the user's choice. If WGSwitchUser: returns "true", wait for OnLoginNotify callback to get the account switch result. If WGSwitchUser: returns "false", return to the login page to let the player reauthorize login.

7)Term interpretation

ePlatform definition description

WakeupRet definition description

Switch account

1)Function description

When wakeupRet.flag, a flag used to judge if there is account inconsistency, is eFlag_NeedSelectAccount, the game needs to pop up a box to prompt the user to select the local account or the launched account to log in the game, and the game needs to call the interface WGSwitchUser: to complete the user's login according to the user's choice.

2)Interface declaration

bool WGSwitchUser(bool flag);

3)Parameter description

4)Return value

true : indicate that this account has a token. MSDK will verify the validity of the token and return the verification result in OnLoginNotify.

false: indicate that the account has no token or the token is invalid. The user can login the game directly, so that the user can re-authorize login.

5)Demo code

WGPlatform* plat = WGPlatform::GetInstance();
BOOL success = plat->WGSwitchUser(switchFlag);
if (success)
{
    //Switch succeeds; wait for OnLoginNotify callback
}
else
{
    //Switch fails; call WGLogout interface to logout and return to the login page
    plat->WGLogout();
}

6)Special description

None

7)Term interpretation

None

Get token

1)Function description

You can get the login callback token by parsing TokenRet in LoginRet in the login callback. In addition, you can call WGGetLoginRecordinterface to get the current login token. LoginRet token information contains the player's openid, pf and pfkey. TokenRet in LoginRet contains pay_token (unique for QQ login), access_token (unique for WeChat login) and other information. You will use such information when you make payment.

2)Interface declaration

int WGGetLoginRecord(LoginRet& loginRet);

3)Parameter description

4)Return value

Return value is the corresponding login platform of token information

5)Demo code

LoginRet ret;
WGPlatform::GetInstance()->WGGetLoginRecord(ret);
if (ret.flag == eFlag_Succ)
{
    //Succeed in getting the token, and read the token information normally
}
else if (ret.flag == eFlag_Checking_Token)
{
    //MSDK is checking the token’s effectiveness, and get the token again after waiting for 3~5s 
}
else
{
    //There is no token locally or the token is invalid
}

6)Special description

1. You can get the token through this interface and then judge LoginRet.flag. If the value is 0 (eFlag_Succ), the token is normal and valid and can be directly used; if the value is 5001 (eFlag_Checking_Token), it indicates that MSDK is verifying the token. At this time, the token got is invalid. Try it again later.
2. The interface can involve querying the local database. Very frequently calling it can hurt the performance, so the interface is not suitable for high-frequency calls. For example, unity games shall not call it frequently in update function

7)Term interpretation

LoginRet definition description

Real name

In accordance with the relevant provisions of "Interim Measures for Management of Online Games" issued by the Chinese Ministry of Culture, online game users need to use a valid identity document to make real name registration before they can login any game. In order to reduce the burden of game developers, we have customized the real-name authentication UI and the entire interfaces for games. Through the module, you only need to spend a few minutes to complete the real-name authentication function.

As for the detailed description of the real-name system, please refer to Real name system specification documentation

Logout

1 General description

You can call WGLogout interface to logout and clear the local token

2 Registration callback

None

3 Call interfaces

1)Function description

Get the login's callback token

2)Interface declaration

bool WGLogout();

3)Parameter description

None

4)Return value

Return true. You do not need to process the return value

5)Demo code

WGPlatform::GetInstance()->WGLogout();

6)Special description

None

7)Name interpretation

None

MSDK token automatic refresh process

On the basis of supporting the previous versions' login process, MSDK2.6.0i and later versions optimize the new process. The business only needs to pay attention to the two interfaces, that is WGLogin andWGGetLoginRecord, to complete the login and token processing procedures.

• Call logic in case that the game uses automatic login:

  Start the game, directly call WGLogin() interface, and wait for OnLoginNotify() callback. The process is as follows：

• Call logic in case that the game needs the login token:

  Call WGGetLoginRecord() interface; when the return value is flag = 5001, this indicates that the validity of the token is being verified inside MSDK. A few seconds later, you may try again to obtain the token. The process is as follows：

• MSDK's internal token verification and refresh logic:

FAQ

Is it needed to check the token when the frontend and backend of the game switch？

The game does not need to check the validity of the token when switching between the frontend and the backed. If the backend in the game lasts too long and then switches to the frontend, MSDK will automatically verify the validity of the token.

About "Sign in With Apple"

1. Return -3003; check whether the contents of the App ID, Team ID, Key ID and Key files are correctly configured in Feiying system. Check path: Game management -> My Game -> SDK Parameters -> Search: Edit iOS Information -> MSDKV3 Apple Channel Configuration (joint debugging environment/ release environment ).
2. Return -3008; check whether the used BundleID matches that configured in the Feiying system.
3. Return -3011; check whether the environments of the MSDK client and server match each other. The MSDK environment needs to be consistent.
4. How to add the "Sign in With Apple" capability to Apple certificate? As for Apple certificate-related capabilities, please contact the certificate provider to add the corresponding capabilities and update the certificate. Generally, you should contact the KeyStore-helper certificate assistant or DevOps-helper. After packaging the certificate with the "Sign in With Apple" capability, do not perform the re-signing operation.