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.

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: The list of the user's permissions to authorize the game. It is needed to especially note if there is the "Access your QQ friends's information in app" item in the list. If not, error code "100030" will emerge when you get the user relation chain. It is needed to confirm to call WGPlatform.WGSetPermission(WGQZonePermissions.eOPEN_ALL); in Java code after MSDK is initialized.
Function 1.3: "Return" button. After the user clicks the button, the login will be cancelled, and the game receives login callback and flag is eFlag_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.

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.

3 iOS 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.

4 WeChat scan-code login

On mobile phones not installed with WeChat or on pads and TV sets, you can also call the scan-code login interface to achieve better user experience.

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, refer to Assets\Example\MsdkDemo.cs script's ShowQQ() method's login part.

For WeChat login examples, refer to Assets\Example\MsdkDemo.cs script's ShowWX() method's login part.

For guest login examples, refer to Assets\Example\MsdkDemo.cs script's ShowNotice() method's login part.

3 Bind the interface with button

Here, we will take Unity native UGUI as an example to illustrate how to bind login interface with UGUI Button. For NGUI binding method, refer to this example

1) Bind the interface through the property panel

• Create Button

Select in succession Create -> UI -> Button on the Hierarchy panel

• Create C# script

In the Project panel, click the right button to pop up a menu. In the menu, select in succession Create -> C# Script, and rename C# script as ClickTest.cs(or other names can also be used).

• Compile script

Double-click the newly created C# script ClickTest.cs, and compile the script in the opened IDE.

using UnityEngine;
using System.Collections;
// Step1 Import MSDK libraries
using Msdk;

public class ClickTest : MonoBehaviour {

    void Start () {
        // Step2 Set whether or not to use the PC debugging pile environment
        WGPlatform.SetPCDebug(true);
        // Step3 Set the MSDK login callback
        MsdkEvent.Instance.LoginEvent += LoginCallback;
        // Step4 Initialize MSDK
        WGPlatform.Instance.Init();
    }

    // the method which Button needs to bind; its name is optional
    public void Clicked()
    {
        // Click the button and then call MSDK's login interface
        WGPlatform.Instance.WGLogin(ePlatform.ePlatform_QQ);
    }

    // MSDK Login Callback
    public void LoginCallback(LoginRet ret)
    {
        Debug.Log(ret.ToString());
    }
}

Of which, refer to MSDK initialization for the detailed descrption of MSDK initialization steps

• Set the script as Canvas component

On the Hierarchy panel, select Canvas, call Inspector panel, and drag ClickTest.cs script to the lowermost part of the Inspector panel, as shown in the figure below

• Bind the method with the button

On the Hierarchy panel, select Button and call Inspector panel, click the plus (+) at the lower part of the Inspector panel to add one click event

Click the circle near the newly added entry to select GameObject that is bound with click event. Here, we select Canvas bound with ClickTest.cs script

Click No Function entry, and select the click-triggered method Clicked()

2) Dynamically bind the interface through the code

• Create button

Like the "Bind the interface through the Property panel", create Button. Then, on the Button's Inspector panel, modify Button's name as LoginButton(the name is freely optional), so as to get this button in the code.

• Create and compile the script

Create ClickTest.cs script. The code is like:

using UnityEngine;
using System.Collections;
using UnityEngine.Events;
using UnityEngine.UI;
// Step1 Import MSDK libraries
using Msdk;

public class ClickTest : MonoBehaviour {

    void Start () {
        // Step2  Set whether or not to use the PC debugging pile environment
        WGPlatform.SetPCDebug(true);
        // Step3 Set the MSDK login callback
        MsdkEvent.Instance.LoginEvent += LoginCallback;
        // Step4 Initialize MSDK
        WGPlatform.Instance.Init();

        // Get GameObject through button name
        GameObject btnObj = GameObject.Find("LoginButton");
        // Get Button example
        Button loginBtn = btnObj.GetComponent<Button>();
        // set click event
        loginBtn.onClick.AddListener(delegate() {
            // Click the button and then call MSDK's login interface
            WGPlatform.Instance.WGLogin(ePlatform.ePlatform_QQ);
        });
    }

    // MSDK Login Callback
    public void LoginCallback(LoginRet ret)
    {
        Debug.Log(ret.ToString());
    }
}

Of which, refer to MSDK initialization for the detailed descrption of MSDK initialization steps

4 Run and view the result

Click the triangle icon above the middle part of Unity to run the program in the PC environment, and then click the Game panel's button

At this time, view Console and be able to see the following login interfaces be successfully called and see the callback log

Finally, export the installation package and install and run it in the mobile phone. After clicking the button, mobile QQ is launched and the login authorization is completed.

5 Call this module's other interfaces

After completing Step1-Step4, 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.

Authorized login: Launch mobile QQ/WeChat client or web page(mobile QQ has yet to be installed) for authorization.
Guest login: MSDK provides the guest mode, facilitating the user to have a complete experience of the game workflow without providing any account password.
Code scanning login : If WeChat has yet to be installed on the user's device, the game can take advantage of the code scan login to let the user authorize with WeChat on other devices.
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.
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.
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 Instructions on Access to MSDK Universal Link Authorized Login Capability

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

1 Summary

Launch mobile QQ/WeChat client or web page (mobile QQ is not installed) to authorize login. After the user authorizes login, the platform will notify the game through LoginEvent to get LoginRet login information.

2 Registration callback

1)Function description

To receive MSDK's login callback, you need to register the callback function for processing. It is suggested that registration should be performed in Awake function. The login result will be sent to you through the callback function.

2)Interface declaration

public delegate void LoginDelegate(LoginRet loginRet);

3)Parameter description

4)Return value

None

5)Demo code

MsdkEvent.Instance.LoginEvent += (LoginRet loginRet) =>
{
    switch (loginRet.flag)
    {
    case eFlag.eFlag_Succ:
    // Login succeeds; various tokens can be read
    // Game TODO：Enter the game
        int platform= loginRet.platform;
        if((int) ePlatform.ePlatform_Weixin == platform) {
            loginState = "WeChat login succeeds";
        } else if((int) ePlatform.ePlatform_QQ == platform) {
            loginState = "QQ login succeeds;
        } else if((int) ePlatform.ePlatform_QQHall == platform) {
            loginState = "Hall login succeeds";
        } else if((int) ePlatform.ePlatform_Guest == platform) {
            loginState = "Guest login succeeds";
        }
        break;

    // Game TODO: Handle login failures separately. Usually, return to the login page to guide the user to re-authorize
    case eFlag.eFlag_QQ_UserCancel:
    // The player cancels authorization
    case eFlag.eFlag_QQ_LoginFail
    // QQ Login failed
    case eFlag.eFlag_QQ_NotInstall
    // QQ is not installed
    case eFlag.eFlag_Local_Invalid:
    // Automatic login failed, due to the local token expiration, refresh failure and other errors
    case eFlag.eFlag_WX_UserCancel:
    // The player cancels authorization
    case eFlag.eFlag_WX_NotInstall:
    // WeChat is not installed
    case eFlag.eFlag_WX_NotSupportApi:
    // WeChat version is not supported
    case eFlag.eFlag_WX_LoginFail:
    <stong>//WeChat login failed</stong>
    default:
        loginState = "Login failed";
        message = loginRet.ToString();
        break;
    }
};

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

QQ Hall login: QQ Hall login is a login mode that early chess and card games transferred tokens through the QQ Game Hall. Games not accessing the QQ Game Hall don't need to pay attention to it

Recommended login process

3 Call login

1)Function description

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

2)Interface declaration

void WGLogin(ePlatform platform);

3)Parameter description

4)Return value

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

5)Demo code

5)示例代码

WGPlatform.Instance.WGLogin (ePlatform.ePlatform_QQ); //QQ login
WGPlatform.Instance.WGLogin (ePlatform.ePlatform_Weixin); //WeChat login
WGPlatform.Instance.WGLogin (ePlatform.ePlatform_Guest); //Guest login（only for iOS）

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) If WeChat has yet to be logged in, after the game launches WeChat and the user name and password are input, there may be no login callback. This is the known BUG at the WeChat client
  2) If WeChat has yet to be logged in, when you directly click "Return" on the user name and password input page, there may be no login callback. This is the know BUG at the WeChat client
  3) When you click "Return xx game" on the upper left corner of a system higher than iOS9, 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

4 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, int overtime);

3)Parameter description

4)Return value

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

5)Demo code

WGPlatform.Instance.WGLoginOpt (ePlatform.ePlatform_QQ,20); //QQ login
WGPlatform.Instance.WGLoginOpt (ePlatform.ePlatform_Weixin,20); //WeChat login
WGPlatform.Instance.WGLoginOpt (ePlatform.ePlatform_Guest,20); //Guest login（only for iOS）

6)Special description

MSDK adds the login timeout callback

7)Term interpretation

None

guest login

1 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:

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

• Restore and erase iPhone data

• elete 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

2 Registration callback

Refer to Authorized login Registration callback

3 Call login interface

Refer to Authorized loginCall the login interface

4 Call the guest ID refreshing interface

1)Function descriptione

Refresh ID in the guest mode.

2)Interface declaration

void WGResetGuestID();

3)Parameter description

None

4)Return value

None

5)Demo code

WGPlatform.Instance.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

WeChat scan-code login

1)Function descriptione

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 LoginEvent callback

5)Demo code

WGPlatform.Instance.WGQrCodeLogin (ePlatform.ePlatform_Weixin);

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)Term 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 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

When the player clicks the shared information in mobile QQ or WeChat to directly launch and enter a game, the platform will passthrough login-related token information to complete the login and enter the game directly. In this scenario, after the game is launched, the player can enter the game without reauthorization. Relevant codes and callbacks have been configured inside MSDK. Only need to refer to Android and iOS double-end wiki to set the relevant configuration.

Account inconsistency handling

1 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

2 Registration callback

To receive the callback provided by MSDK for the launch of the game, you need to register WakeupEvent callback.

1)Function descriptione

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

2)Interface declaration

public delegate void WakeupDelegate(WakeupRet wakeupRet);

3)Parameter description

4)Return value

None

5)Demo code

MsdkEvent.Instance.WakeupEvent += (WakeupRet wakeupRet) =>
{
    // TODO GAME Add the logic to handle account inconsistency here
    if (eFlag.eFlag_Succ == wakeupRet.flag || eFlag.eFlag_AccountRefresh == wakeupRet.flag) {
        // After the local account login succeeds, directly enter the game
        // Game TODO：Enter the game logic
        if((int) ePlatform.ePlatform_Weixin == wakeupRet.platform) {
            loginState = "WeChat login succeeds";
        } else if ((int) ePlatform.ePlatform_QQ == wakeupRet.platform) {
            loginState = "QQ login succeeds";
        } else if((int) ePlatform.ePlatform_QQHall == wakeupRet.platform) {
            loginState = "Hall login succeeds";
        }
    } else if (eFlag.eFlag_UrlLogin == wakeupRet.flag) {
        // The local has no account information. Automatically login the game with the launched account. The login result is called back in OnLoginNotify()
    } else if (eFlag.eFlag_NeedSelectAccount == wakeupRet.flag) {
        // Game TODO：In case of account inconsistency, the game needs to pop up a prompt box to allow the user to select the account needing to login and calls WGSwitchUser interface according to the user's choice
        Debug.Log("diff account");
        isShowDiffAcount = true;
        message = "Account inconsistency！";
    } else if (eFlag.eFlag_NeedLogin == wakeupRet.flag) {
        // Game TODO： No valid token. Logout of the game so that the user re-login the game
        loginState = "Login failed";
        message = "Please re-login";
    } else {
        loginState = "Not login";
        message = "OnWakeupNotify    flag : " + wakeupRet.flag + "\ndesc : " + wakeupRet.desc;
        WGPlatform.Instance.WGLogout();
    }
};

6)Special description

When eFlag.eFlag_NeedSelectAccount is received, this means that there is account inconsistency. At this time, the game needs to pop up a prompt box to let the user select the account that he wants to login and calls the WGSwitchUser interface according to the user's choice, and wait for the LoginEvent callback to get the result of the account switch.

7)Term interpretation

ePlatform definition description

WakeupRet definition description

3 Switch account

1)Function descriptione

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 LoginEvent.

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

// Account inconsistency prompt pop-up window processing example 
void ShowDiffAcount(int windowID)
{
    // select the local account to login
    if (Button("local account"))
    {
        if(!WGPlatform.Instance.WGSwitchUser(false)){
            WGPlatform.Instance.WGLogout();
            loginState = "Not login";
            loginStateMaybeChange = true;
        }
    }
    // select the launched account to login
    if (Button("The launched account"))
    {
        if(!WGPlatform.Instance.WGSwitchUser(true)){
            WGPlatform.Instance.WGLogout();
            loginState = "Not login";
            loginStateMaybeChange = true;
        }
    }
}

6)Special description

Because WeChat Game Center does not carry the user login status when launching a game, "false" will be returned when switchuser is called in WeChat platform. At this time, it is needed to re-authorize the login.

7)Term interpretation

None

Get token

1 General description

You can get the login callback token by parsing LoginRet in TokenRet in the login callback. In addition, you can call the following interface to get the current login token. LoginRet token 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 Registration callback

None

3 Call interfaces

1)Function descriptione

Get the login's callback token

2)Interface declaration

LoginRet WGGetLoginRecord();

3)Parameter description

None

4)Return value

LoginRet the current login token

5)Demo code

LoginRet loginRet = WGPlatform.Instance.WGGetLoginRecord();
if (loginRet == null || loginRet.open_id == "") {
    // the user fails to login;
    // Game TODO: invalid token; return to the login page
} else {
    // the user has logged in
    // Game TODO: Read the token 
}

6)Special description

1. After a token is obtained through this interface, it is needed to judge LoginRet.flag. If the result is 0 (eFlag_Succ), the token is valid and can be used directly; if it is 5001 (eFlag_Checking_Token), this means that MSDK is verifying the token and the token is invalid. It is needed to try 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.Instance.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.

If mobile QQ is not installed, the game is logged in via Web QQ, but the game crashes soon later. How to solve this problem?

If the game is directly packed into Apk package with Unity, when this problem occurs, it is needed to unpack the contents in assets directory in MSDK's jar package into Android/assets. If the game is packed with other ways, it is needed to properly handle so files and resource files in MSDK's jar package in the package script. If there are other problems, you can try to unpack the contents in "assets" directory in MSDK's jar package into the game project's assets directory.

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 Bluedon Assistant. After packaging the certificate with the "Sign in With Apple" capability, do not perform the re-signing operation.