05/15/2024 15:19:45

PC Access Guide

I. Overview

MSDK PC is a newly developed and adapted version of MSDK specially designed for PC games to access WeChat, QQ and Steam platforms, so as to facilitate games to perform authorization login on WeChat, QQ and Steam platforms under Unity and UnrealEngine Editor modes.

Starting from MSDKPC 5.0.0.21, MSDK has added PC WebView capability support. Currently, this capability is only used for the code scanning-based login and central control real name authentication process functions of WeChat and QQ channels. For details of the capability, please refer to IX. PC-side WebView Capability - Code Scanning-based Login and Real Name Popup
Connect to MSDKPC 5.0.0.21 or higher version. If the game has already implemented code scanning and real name capabilities by itself, you can choose not to connect to [Code Scanning and Central Control Real Name Integration Solution]. Refer to 9.5 Peel off CEF Library Dependency guidelines to delete CEF related libraries. This can reduce the package volume

II. Platform permission application

2.1 WeChat platform permissions

The WeChat platform no longer accepts applications from new games for "SDK-based login permissions". Since version 5.0.0.13, MSDK PC has supported Web-based authorization login. For details about the authorization process, please refer to "4.2 Web-based authorization".
Games which want to access the web-based authorization need to apply for "Authorization Callback Redirect URI". Specifically, the access party needs to contact wxgame to provide WeChat AppID to apply for modification or obtain the redirect URI required by the website application.

Note: If you want to check the MSDK PC version, please refer to FAQ-View MSDK Version Number-PC.

2.2 QQ platform permissions

The access party needs to contact qqconnecthelper to apply for "QQ PC application" and obtain QQ PC login permission.
Games which want to access the web-based authorization need to apply for "Authorization Callback Redirect URI". Specifically, the access party needs to log in QQ-Connect management system with the game project's QQ account which is used to register mobile games at Feiying System. After successful login, you can see the following user interface (UI).

Select "Application Management->Create Application", and then fill in the corresponding information in the pop-up box. Take MSDKDemo as an example.

Wherein,
①: Select 0-Website Application
②: Fill in QQ AppID on the mobile terminal of the game
③: Select 1-Mobile Application
④: Fill in QQ AppKey on the mobile terminal of the game
⑤: Fill in the redirect URI of the game
As for specific parameters, you can consult qqconnecthelper via Enterprise WeChat. After filling in relevant information, click the Submit button to wait for review.

Note:

1. The QQ Appid used must have the Windows application type. Otherwise, an error like "not pc app the appid: xxx" will occur during login. If you are not sure whether your QQ Appid has a Windows application type, you can contact qqconnecthelper and provide your QQ Appid to the latter via your WeCom for confirmation.
   
2. If you encounter an error like "100052, appid does not has permission to get paytoken or openid", you need to contact qqconnecthelper to apply for the permission to "get paytoken and openid" to solve the problem.
   

2.3 Steam platform permissions

There is currently no need to apply for permissions on the Steam platform.

III. The directory structure

MSDK no longer provides x86 but only provides x64.
libmsdk directory, which stores MSDK PC-side native libraries;
include directory, which stores the header files required by MSDK;
bin directory, which stores MSDKCore.dll and third-party components that MSDK depends on;
lib directory, which stores MSDKCore.lib;
resources directory, which stores the resource files required by MSDK;
libmsdkadapter directory, which stores Unity's bridging layer, which Unity engine businesses need to access;

IV. Authorization process

4.1 SDK-based authorization

-->①The user clicks the "Login" button -->②Game Client invokes MSDK's login interface -->③Game Client listens to MSDK's QR code callback -->④Game Client displays the QR code to the user -->⑤The user scans the QR code -->⑥Game Client listens to MSDK's login callback -->⑦Game Client sends the token to Game Server synchronically -->⑧Game Server authenticates MSDK Server -->⑨Game Server receives the authentication result -->⑩Game Server sends the authentication result to Game Client synchronically

The authorization sequence is as follows:

4.2 Web-based authorization

The Web-form authorization can be accessed through the following two methods: the app opens the code-scanning page by itself and MSDK opens the code-scanning page. Among them, the [MSDK opens the code-scanning page] method is supported in 5.0.0.21 and above. For the detailed introduction of the capability, please refer to: IX. PC-side WebView capability - Code Scanning-based Login and Real Name Popup.

4.2.1 The app opens the code-scanning page by itself

-->①The user clicks the "Login" button -->②Game Client uses the WebView plug-in to open the QQ/WeChat Web authorization page -->③The user scans the QR code -->④Game Client listens to the request at the beginning of redirect URI and intercepts the code parameter on the URI -->⑤Game Client closes the WebView plug-in, invokes MSDK's login interface and passes parameters such as code -->⑥Game Client listens to MSDK's login callback -->⑦Game Client sends the token to Game Server synchronically -->⑧Game Server authenticates MSDK Server -->⑨Game Server receives the authentication result -->⑩Game Server sends the authentication result to Game Client synchronically

The authorization sequence is as follows:

Note:

1. The PC Web-based authorization is to authorize login through the oauth protocol of WeChat and QQ platforms. In short, it is to exchange token with code. Click QQ platform 、WeChat platform to learn about more about the oauth authorization process of dual platforms.
   
2. The token obtained by the PC Web-based authorization has the same type as the token obtained by the mobile game authorization does. When performing server authentication, the access party must confirm that there is no need to additionally pass "client_os":5 in the json body while 5 is not passed in the os field in Request URL; otherwise, the authentication will fail.
   

4.2.2 MSDK opens the code-scanning page (supported by MSDKPC 5.0.0.21 and above)

-->① The user clicks the Login button -->② Game Client invokes MSDK login interface -->③ MSDK shows QR code to the user -->④ The user scans QR code -->⑤ Game Client listens to MSDK login callback -->⑥ Game Client synchronizes the token to Game Server -->⑦ Game Server makes authentication to MSDK Server -->⑧ Game Server receives the authentication result -->⑨ Game Server synchronizes the authentication result to Game Client

The authorization sequence is as follows:

V. Visual Studio access guidelines

5.1 Add the include directory, which stores header files

5.2 Add MSDKCore.lib dependency

5.3 Copy MSDKCore.dll and the third-party components that MSDK depends on to the executable file directory

5.4 Configure MSDKConfig.ini, MSDKRetMsg.Json and cacert.pem in the executable file directory

1. The MSDK_URL field in the MSDKConfig.ini file is the MSDK Server address. When the game is released, the URL must be changed to the MSDK release environment, that is, https://itop.qq.com;
   
2. MSDK_GAME_ID, MSDK_SDK_KEY, WECHAT_APP_ID, QQ_APP_ID, QQ_APP_KEY and STEAM_APP_ID need to be changed to those of the game;
   
3. The MSDKRetMsg.Json file is the description of the json parsing protocol of the MSDK client. The game developer doesn't need to pay too much attention to it. It can be copied directly from the resources directory to the executable file directory;
   
4. The cacert.pem file is the public key for the communication between the MSDK client and the MSDK server. It can be copied directly from the resources directory to the executable file directory;
   

Note: For versions downloaded from GCloud's official website, the QQ_APP_KEY field still needs to be manually configured by each game because it is the sensitive information of the game.

5.5 Add precompiled parameter GCLOUD_MSDK_WINDOWS

Add precompiled parameter GCLOUD_MSDK_WINDOWS so that the MSDK Windows version can be compiled normally.

5.6 Access login

5.6.1 Import header files

    #include "MSDKLogin.h"

5.6.2 Set callback

    MyObserver *observer = MyObserver::GetInstance();
    MSDKLogin::SetLoginObserver(observer);

5.6.3 Login

Invoke MSDKLogin::Login interface

SDK-based authorization (only supported by QQ and Steam)

    MSDKLogin::Login("QQ", "", "");
    or
    MSDKLogin::Login("Steam", "", "");

    Please pay attention to the following points when logging in through the Steam channel:
    1. The steam_appid.txt file must be configured in the same directory as .exe during the joint test phase and the Steam client must be started and logged in in advance. There is no need to configure the `STEAM_APP_ID` parameter in the MSDKConfig.ini file; otherwise, the Steam channel login will fail;
    2. There is no need to submit the steam_appid.txt file when submitting the release version to Steam Store, but the `STEAM_APP_ID` parameter must be configured in the MSDKConfig.ini file; otherwise, the authorization login will not be able to invoke the Steam client when the Steam client is not running, thus leading to the failure of Steam channel login;

Web-based authorization (only supported by QQ and WeChat)

The Web-form authorization can be accessed through the following two methods: the app opens the code-scanning page by itself and MSDK opens the code-scanning page. Among them, the [MSDK opens the code-scanning page] method is supported in 5.0.0.21 and above. For the detailed introduction of the capability, please refer to: IX. PC-side WebView capability - Code Scanning-based Login and Real Name Popup.

• The app opens the code-scanning page by itself. At this case, it is needed to intercept code and transfer it to MSDK

    std::string extra_json = "{\"channel\":\"QQ\",\"channelID\":2,\"channelOpenID\":\"\",\"pluginData\":{\"code\":\"xxx\",\"redirect_uri\":\"xxx\",\"msdk_qq_login_use_code\":1}}";
    MSDKLogin::Login("", "", "", extra_json.c_str());
    or
    std::string extra_json = "{\"channel\":\"WeChat\",\"channelID\":1,\"channelOpenID\":\"\",\"pluginData\":{\"code\":\"xxx\"}}";
    MSDKLogin::Login("", "", "", extra_json.c_str());

    1. For Web-based authorization, it is needed to pass "" to the first input parameter of the Login interface;
    2. In addition to passing the `code` parameter to the `extra_json` field of the QQ channel, it is needed to additionally pass `redirect_uri` and `msdk_qq_login_use_code` to it, where `redirect_uri` is the redirect URI of the game, and `msdk_qq_login_use_code` is fixed to 1;

• MSDK opens the code-scanning page (supported by MSDKPC 5.0.0.21 and above)

//Open the code-scanning page through the Webview pop-up window, and use the WebView2 mode
std::string ext_json = "{\"login_use_msdk_webview\": 1, \"webview_type\": 2}"；       
MSDKLogin::Login("QQ", "", "", ext_json);
or
//Open the code-scanning page through the Webview pop-up window, and use the CEF mode
std::string ext_json = "{\"login_use_msdk_webview\": 1, \"webview_type\": 1}"；       
MSDKLogin::Login("WeChat", "", "", ext_json);

1. MSDK opens the code-scanning page for Web-form authorization, and the first input parameter of the Login interface is passed in as `QQ` or `WeChat`;
2. If `login_use_msdk_webview` is configured as 1, this means that the MSDKWebView capability is used for the pop-up code-scanning login. If the configuration option is not transferred or is configured as 0, this means that the pop-up code-scanning login is not used and the original login logic of the app is maintained;
3. On the basis that the value of `login_use_msdk_webview` is set to 1:
if webview_type is filled in with 1, this means to use the CEF mode; if it is filled in with 2, this means to use the WebView2 mode. If this configuration option is not transferred, the default mode of WebView configured in MSDKConfig.ini will be used for scanning the QR code and popping up the window.

Implement QR code callback (only required for SDK-based authorization, but not required for Web-based authorization)

    void MyObserver::OnQrCodeNotify(const MSDKQrCodeRet &qrCodeRet)
    {
        std::string url_str = "start ";
        if (qrCodeRet.channel == "QQ")
        {
            url_str = url_str + qrCodeRet.qrCodeUrl;
        }
        else if (qrCodeRet.channel == "WeChat")
        {
            url_str = url_str + "https://cli.im/api/qrcode/code?text=" + qrCodeRet.qrCodeUrl;
        }

        system(url_str.c_str());
    }

    1. The `qr_code_url` field of the QQ platform is the QR code download link and can be directly downloaded and displayed to the user;
    2. Steam platform does not need to listen to the callback, but just listens to OnLoginRetNotify directly;

Implement the login callback

    void MyObserver::OnLoginRetNotify(const MSDKLoginRet &loginRet)
    {

    }

    Please pay attention to the following points when logging in through the Steam channel:
    1. When loginRet.retCode = 17 is received during the joint test stage, please check whether the steam_appid.txt file is configured and the Steam client is running;
    2. When loginRet.retCode = 17 is received during the release stage, please close the game process. MSDK will invoke the Steam client and restart the game from the Steam client;

5.6.4 Automatic login(Effective only under MSDK's test environment)

Invoke MSDKLogin::AutoLogin interface

    //Automatic login only takes effect in the MSDK joint test environment
    MSDKLogin::AutoLogin();

Implement the login callback

    void MyObserver::OnLoginRetNotify(const MSDKLoginRet &loginRet)
    {

    }

5.6.5 Self-service real name registration

MSDK PC supports self-service real name registration since version 5.0.0.19. If the login account is not a real name account, MSDK will call back the real-name-related error code retCode&login token information&central control real name information to the game through the login callback OnLoginRetNotify. The central control real name information will be stored in the MSDKLoginRet.channelInfo field. The game side can open the Webview component for real name registration according to the relevant information of the central control. After the real name registration is successful, your APP can invoke the MSDKLogin::OnRealNameAuthFinished interface to transmit the login status & the real name results to continue the login process, and listen for the MSDK login callback.

Invoke the MSDKLogin::OnRealNameAuthFinished interface

    MSDKLogin::OnRealNameAuthFinished(channel, openid, token ,true);

5.6.6 Get the login token

Invoke MSDKLogin::GetLoginRet interface

    MSDKLoginRet loginRet;
    MSDKLogin::GetLoginRet(loginRet);

5.6.7 Logout

Invoke MSDKLogin::Logout interface

    MSDKLogin::Logout();

Implement the logout callback

    void MyObserver::OnBaseRetNotify(const MSDKBaseRet &baseRet)
    {

    }

5.6.8 Uninstall MSDK

Invoke MSDKLogin::UnInstall interface

    //The interface needs to be invoked when the game is closed, so as to prevent the game from being unable to be closed normally
    MSDKLogin::UnInstall();

5.7 Access the Notice module

5.7.1 Import header files

    #include "MSDKNotice.h"

5.7.2 Set callback

    MyObserver *observer = MyObserver::GetInstance();
    MSDKNotice::SetNoticeObserver(observer);

5.7.3 Get the notice data

Invoke MSDKNotice::LoadNoticeData interface

    std::string group = "1";
    std::string language = "zh-CN";
    int region = = 156;
    std::string partition = "0";
    std::string extra_json = "{}";
    MSDKNotice::LoadNoticeData(group, language, region, partition, extra_json);

Implement the notice callback

    void MyObserver::OnLoadNoticeData(const MSDKNoticeRet &noticeRet)
    {

    }

5.8 Get the encrypted token

The methods of obtaining encrypted tokens on the PC and the mobile terminal are the same. For details, please refer to Instructions for obtaining encrypted tokens.

VI. Unity access guidelines

6.1 Follow the instructions to access the MSDK Script

Follow GCloud Access Guidelines to access MSDK Script.

6.2 Copy MSDKCore.dll, MSDKUnityAdapter.dll as well as the third-party components that MSDK depends on to the asset/Plugins directory

6.3 Configure MSDKConfig.ini, MSDKRetMsg.Json and cacert.pem in the asset/Plugins directory

1. The MSDK_URL field in the MSDKConfig.ini file is the MSDK Server address. When the game is released, the URL must be changed to the MSDK release environment, that is, https://itop.qq.com;
   
2. MSDK_GAME_ID, MSDK_SDK_KEY, WECHAT_APP_ID, QQ_APP_ID, QQ_APP_KEY and STEAM_APP_ID need to be changed to those of the game;
   
3. The MSDKRetMsg.Json file is the description of the json parsing protocol of the MSDK client. The game developer doesn't need to pay too much attention to it. It can be copied directly from the resources directory to the executable file directory;
   
4. The cacert.pem file is the public key for the communication between the MSDK client and the MSDK server. It can be copied directly from the resources directory to the executable file directory;
   

Note: For versions downloaded from GCloud's official website, the QQ_APP_KEY field still needs to be manually configured by each game because it is the sensitive information of the game.

6.4 The project's root directory needs to be configured with steam_appid.txt in Editor mode

Note: Copy steam_appid.txt to the project's root directory in Editor mode; otherwise, Steam authorization in Editor mode will fail. Games not accessing Steam authorization can ignore this configuration.

6.5 Copy MSDK's C# script to the asset directory

6.6 Add precompiled parameter GCLOUD_MSDK_WINDOWS

Add precompiled parameter GCLOUD_MSDK_WINDOWS so that the MSDK Windows version can be compiled normally.

6.7 Access login

6.7.1 Initialize MSDK

    using GCloud.MSDK;
    MSDK.Init ();

6.7.2 Set callback

    private void setLoginObserver ()
    {
        //Login callback
        MSDKLogin.LoginRetEvent += OnLoginRetEvent;
        //Logout callback
        MSDKLogin.LoginBaseRetEvent += OnLoginBaseRetEvent;
#if GCLOUD_MSDK_WINDOWS
        //Windows platform's QR code callback (only required for SDK-based authorization, but not required for Web-based authorization)
        MSDKLogin.QrCodeRetEvent += OnQrCodeRetEvent;
#endif
    }

6.7.3 Implement the callback

#if GCLOUD_MSDK_WINDOWS
    private void OnQrCodeRetEvent (MSDKQrCodeRet qrCodeRet)
    {
        //Login QR code callback (only required for SDK-based authorization, but not required for Web-based authorization)
        Debug.Log ("OnQrCodeRetEvent in Login." + " channel:" + qrCodeRet.Channel + " qrCodeUrl:" + qrCodeRet.QrCodeUrl);
        if (qrCodeRet.Channel == "QQ") {
            StartCoroutine (loadImage (qrCodeRet.QrCodeUrl));
        } else if (qrCodeRet.Channel == "WeChat") {
            if (qrEncodeController != null) {
                qrEncodeController.Encode(qrCodeRet.QrCodeUrl);
            }
        }
    }

    1. The `QrCodeUrl` field of the QQ platform is the QR code download link and can be directly downloaded and displayed to the user;
    2. Steam platform does not need to listen to the callback, but just listens to OnLoginRetNotify directly;
#endif

    private void OnLoginRetEvent (MSDKLoginRet loginRet)
    {
        //Login callback
    }

    Please pay attention to the following points when logging in through the Steam channel:
    1. When loginRet.retCode = 17 is received during the joint test stage, please check whether the steam_appid.txt file is configured and the Steam client is running;
    2. When loginRet.retCode = 17 is received during the release stage, please close the game process. MSDK will invoke the Steam client and restart the game from the Steam client;

    private void OnLoginBaseRetEvent (MSDKBaseRet baseRet)
    {
        //Logout callback
    }

6.7.4 Login

Invoke MSDKLogin.Login interface

SDK-based authorization (only supported by QQ and Steam)

    MSDKLogin.Login("QQ");
    or
    MSDKLogin.Login("Steam");

    Please pay attention to the following points when logging in through the Steam channel:
    1. In the joint test stage, the steam_appid.txt file must be configured in the project's root directory and the Steam client login must be started and logged in in advance. There is no need to configure the `STEAM_APP_ID` parameter in the MSDKConfig.ini file; otherwise, the Steam channel login will fail;
    2. There is no need to submit the steam_appid.txt file when submitting the release version to Steam Store, but the `STEAM_APP_ID` parameter must be configured in the MSDKConfig.ini file; otherwise, the authorization login will not be able to invoke the Steam client when the Steam client is not running, thus leading to the failure of Steam channel login;

Web-based authorization (only supported by QQ and WeChat)

The Web-form authorization can be accessed through the following two methods: the app opens the code-scanning page by itself and MSDK opens the code-scanning page. Among them, the [MSDK opens the code-scanning page] method is supported in 5.0.0.21 and above. For the detailed introduction of the capability, please refer to: IX. PC-side WebView capability - Code Scanning-based Login and Real Name Popup.

• The app opens the code-scanning page by itself. At this case, it is needed to intercept code and transfer it to MSDK

    JSONObject jsonObject = new JSONObject();
    jsonObject.put("channel", "QQ");
    jsonObject.put("channelID", 2);
    jsonObject.put("channelOpenID", "");
    JSONObject pluginDataJsonObject = new JSONObject();
    pluginDataJsonObject.put("code", "xxx");
    pluginDataJsonObject.put("redirect_uri", "xxx");
    pluginDataJsonObject.put("msdk_qq_login_use_code", 1);
    jsonObject.put("pluginData", pluginDataJsonObject);
    string extraJson = jsonObject.toString();
    MSDKLogin.Login("", "", "", extraJson);
    or
    JSONObject jsonObject = new JSONObject();
    jsonObject.put("channel", "WeChat");
    jsonObject.put("channelID", 1);
    jsonObject.put("channelOpenID", "");
    JSONObject pluginDataJsonObject = new JSONObject();
    pluginDataJsonObject.put("code", "xxx");
    jsonObject.put("pluginData", pluginDataJsonObject);
    string extraJson = jsonObject.toString();
    MSDKLogin.Login("", "", "", extraJson);

    1. For Web-based authorization, it is needed to pass "" to the first input parameter of the Login interface;
    2. In addition to passing the `code` parameter to the `extra_json` field of the QQ channel, it is also needed to pass `redirect_uri' and `msdk_qq_login_use_code` to it additionally, where `redirect_uri` is the redirect URI of the game and `msdk_qq_login_use_code` is fixed to 1.

• MSDK opens the code-scanning page (supported by MSDKPC 5.0.0.21 and above)

//Open the code-scanning page through the Webview pop-up window, and use the WebView2 mode
std::string ext_json = "{\"login_use_msdk_webview\": 1, \"webview_type\": 2}"；       
MSDKLogin::Login("QQ", "", "", ext_json);
or
//Open the code-scanning page through the Webview pop-up window, and use the CEF mode
std::string ext_json = "{\"login_use_msdk_webview\": 1, \"webview_type\": 1}"；       
MSDKLogin::Login("WeChat", "", "", ext_json);

1. MSDK opens the code-scanning page for Web-form authorization, and the first input parameter of the Login interface is passed in as `QQ` or `WeChat`;
2. If `login_use_msdk_webview` is configured as 1, this means that the MSDKWebView capability is used for the pop-up code-scanning login. If the configuration option is not transferred or is configured as 0, this means that the pop-up code-scanning login is not used and the original login logic of the app is maintained;
3. On the basis that the value of `login_use_msdk_webview` is set to 1:
if webview_type is filled in with 1, this means to use the CEF mode; if it is filled in with 2, this means to use the WebView2 mode. If this configuration option is not transferred, the default mode of WebView configured in MSDKConfig.ini will be used for scanning the QR code and popping up the window.

6.7.5 Automatic login(Effective only under MSDK's test environment)

Invoke MSDKLogin.AutoLogin interface

    //Automatic login only takes effect in the MSDK joint test environment
    MSDKLogin.AutoLogin();

6.7.6 Self-service real name registration

MSDK PC supports self-service real name registration since version 5.0.0.19. If the login account is not a real name account, MSDK will call back the real-name-related error code retCode&login token information&central control real name information to the game through the login callback OnLoginRetNotify. The central control real name information will be stored in the MSDKLoginRet.channelInfo field. The game side can open the Webview component for real name registration according to the relevant information of the central control. After the real name registration is successful, your APP can invoke the MSDKLogin.OnRealNameAuthFinished interface to transmit the login status & the real name results to continue the login process, and listen for the MSDK login callback.

Invoke the MSDKLogin.OnRealNameAuthFinished interface

    MSDKLogin.OnRealNameAuthFinished(channel, openid, token ,true);

6.7.7 Get the login token

Invoke MSDKLogin.GetLoginRet interface

    MSDKLoginRet ret = MSDKLogin.GetLoginRet ();

6.7.8 Logout

Invoke MSDKLogin.Logout interface

    MSDKLogin.Logout ("QQ", "", true);

6.7.9 Uninstall MSDK

Invoke MSDK.UnInstall interface

    //The interface needs to be invoked when the game is closed, so as to prevent the game from being unable to be closed normally
    MSDK.UnInstall();

6.8 Access the Notice module

6.8.1 Import header files

    #include "MSDKNotice.h"

6.8.2 Set callback

    MSDKNotice.NoticeRetEvent += mOthersCallBack.OnNoticeRetEvent;

6.8.3 Get the notice data

Invoke MSDKNotice::LoadNoticeData interface

    string group = "1";
    string language = "zh-CN";
    int region = = 156;
    string partition = "0";
    string extra_json = "{}";
    MSDKNotice.LoadNoticeData(group, language, region, partition, extra);

Implement the notice callback

    public void OnNoticeRetEvent(MSDKNoticeRet noticeRet)
    {

    }

6.9 Get the encrypted token

The methods of obtaining encrypted tokens on the PC and the mobile terminal are the same. For details, please refer to Instructions for obtaining encrypted tokens.

VII. UnrealEngine access guidelines

7.1 Follow instructions to download and access the entire MSDK package

Download the entire MSDK package from GCloud. After the package is downloaded and unzipped, its structure is shown in the figure below.

7.2 Copy MSDKCore to Plugins directory

Unzip the downloaded compressed package and then copy the entire MSDKCore folder in the root directory to the Plugins/OneSDKPlugins directory, as shown in the following figure.

7.3 Modify the MSDKConfig.ini configuration file

Modify the configuration information of the MSDKConfig.ini file in the Plugins directory to the configuration information of the game itself. The path is as follows.

1. The MSDK_URL field in the MSDKConfig.ini file is the MSDK Server address. When the game is released, the URL must be changed to the MSDK release environment, that is, https://itop.qq.com;
   
2. MSDK_GAME_ID, MSDK_SDK_KEY, WECHAT_APP_ID, QQ_APP_ID, QQ_APP_KEY and STEAM_APP_ID need to be changed to those of the game;
   
3. The MSDKRetMsg.Json file is the description of the json parsing protocol of the MSDK client. The game developer doesn't need to pay too much attention to it. It can be copied directly from the resources directory to the executable file directory;
   
4. The cacert.pem file is the public key for the communication between the MSDK client and the MSDK server. It can be copied directly from the resources directory to the executable file directory;
   

Note: For versions downloaded from GCloud's official website, the QQ_APP_KEY field still needs to be manually configured by each game because it is the sensitive information of the game.

7.4 Modify the game's compilation script and add a dependency on MSDKCore

Add a dependency on MSDKCore in the Build.cs file of the game. An example is as follows.

7.5 Access login

7.5.1 Import header files

    #include "MSDKLogin.h"

7.5.2 Set callback

    MyObserver *observer = MyObserver::GetInstance();
    MSDKLogin::SetLoginObserver(observer);

7.5.3 Login

Invoke MSDKLogin::Login interface

SDK-based authorization (only supported by QQ and Steam)

    MSDKLogin::Login("QQ", "", "");
    or
    MSDKLogin::Login("Steam", "", "");

    Please pay attention to the following points when logging in through the Steam channel:
    1. The steam_appid.txt file must be configured in the same directory as .exe during the joint test phase and the Steam client must be started and logged in in advance. There is no need to configure the `STEAM_APP_ID` parameter in the MSDKConfig.ini file; otherwise, the Steam channel login will fail;
    2. There is no need to submit the steam_appid.txt file when submitting the release version to Steam Store, but the `STEAM_APP_ID` parameter must be configured in the MSDKConfig.ini file; otherwise, the authorization login will not be able to invoke the Steam client when the Steam client is not running, thus leading to the failure of Steam channel login;

Web-based authorization (only supported by QQ and WeChat)

The Web-form authorization can be accessed through the following two methods: the app opens the code-scanning page by itself and MSDK opens the code-scanning page. Among them, the [MSDK opens the code-scanning page] method is supported in 5.0.0.21 and above. For the detailed introduction of the capability, please refer to: IX. PC-side WebView capability - Code Scanning-based Login and Real Name Popup.

• The app opens the code-scanning page by itself. At this case, it is needed to intercept code and transfer it to MSDK

    std::string extra_json = "{\"channel\":\"QQ\",\"channelID\":2,\"channelOpenID\":\"\",\"pluginData\":{\"code\":\"xxx\",\"redirect_uri\":\"xxx\",\"msdk_qq_login_use_code\":1}}";
    MSDKLogin::Login("", "", "", extra_json.c_str());
    or
    std::string extra_json = "{\"channel\":\"WeChat\",\"channelID\":1,\"channelOpenID\":\"\",\"pluginData\":{\"code\":\"xxx\"}}";
    MSDKLogin::Login("", "", "", extra_json.c_str());

    1. For Web-based authorization, it is needed to pass "" to the first input parameter of the Login interface;
    2. In addition to passing the `code` parameter to the `extra_json` field of the QQ channel, it is needed to additionally pass `redirect_uri` and `msdk_qq_login_use_code` to it, where `redirect_uri` is the redirect URI of the game, and `msdk_qq_login_use_code` is fixed to 1;

• MSDK opens the code-scanning page (supported by MSDKPC 5.0.0.21 and above)

//Open the code-scanning page through the Webview pop-up window, and use the WebView2 mode
std::string ext_json = "{\"login_use_msdk_webview\": 1, \"webview_type\": 2}"；       
MSDKLogin::Login("QQ", "", "", ext_json);
or
//Open the code-scanning page through the Webview pop-up window, and use the CEF mode
std::string ext_json = "{\"login_use_msdk_webview\": 1, \"webview_type\": 1}"；       
MSDKLogin::Login("WeChat", "", "", ext_json);

1. MSDK opens the code-scanning page for Web-form authorization, and the first input parameter of the Login interface is passed in as `QQ` or `WeChat`;
2. If `login_use_msdk_webview` is configured as 1, this means that the MSDKWebView capability is used for the pop-up code-scanning login. If the configuration option is not transferred or is configured as 0, this means that the pop-up code-scanning login is not used and the original login logic of the app is maintained;
3. On the basis that the value of `login_use_msdk_webview` is set to 1:
if webview_type is filled in with 1, this means to use the CEF mode; if it is filled in with 2, this means to use the WebView2 mode. If this configuration option is not transferred, the default mode of WebView configured in MSDKConfig.ini will be used for scanning the QR code and popping up the window.

Implement QR code callback (only required for SDK-based authorization, but not required for Web-based authorization)

    void MyObserver::OnQrCodeNotify(const MSDKQrCodeRet &qrCodeRet)
    {
        std::string url_str = "start ";
        if (qrCodeRet.channel == "QQ")
        {
            url_str = url_str + qrCodeRet.qrCodeUrl;
        }
        else if (qrCodeRet.channel == "WeChat")
        {
            url_str = url_str + "https://cli.im/api/qrcode/code?text=" + qrCodeRet.qrCodeUrl;
        }

        system(url_str.c_str());
    }

    1. The `qr_code_url` field of the QQ platform is the QR code download link and can be directly downloaded and displayed to the user;
    2. Steam platform does not need to listen to the callback, but just listens to OnLoginRetNotify directly;

Implement the login callback

    void MyObserver::OnLoginRetNotify(const MSDKLoginRet &loginRet)
    {

    }

    Please pay attention to the following points when logging in through the Steam channel:
    1. When loginRet.retCode = 17 is received during the joint test stage, please check whether the steam_appid.txt file is configured and the Steam client is running;
    2. When loginRet.retCode = 17 is received during the release stage, please close the game process. MSDK will invoke the Steam client and restart the game from the Steam client;

7.5.4 Automatic login(Effective only under MSDK's test environment)

Invoke MSDKLogin::AutoLogin interface

    //Automatic login only takes effect in the MSDK joint test environment
    MSDKLogin::AutoLogin();

Implement the login callback

    void MyObserver::OnLoginRetNotify(const MSDKLoginRet &loginRet)
    {

    }

7.5.5 Self-service real name registration

MSDK PC supports self-service real name registration since version 5.0.0.19. If the login account is not a real name account, MSDK will call back the real-name-related error code retCode&login token information&central control real name information to the game through the login callback OnLoginRetNotify. The central control real name information will be stored in the MSDKLoginRet.channelInfo field. The game side can open the Webview component for real name registration according to the relevant information of the central control. After the real name registration is successful, your APP can invoke the MSDKLogin::OnRealNameAuthFinished interface to transmit the login status & the real name results to continue the login process, and listen for the MSDK login callback.

Invoke the MSDKLogin::OnRealNameAuthFinished interface

    MSDKLogin::OnRealNameAuthFinished(channel, openid, token ,true);

7.5.6 Get the login token

Invoke MSDKLogin::GetLoginRet interface

    MSDKLoginRet loginRet;
    MSDKLogin::GetLoginRet(loginRet);

7.5.7 Logout

Invoke MSDKLogin::Logout interface

    MSDKLogin::Logout();

Implement the logout callback

    void MyObserver::OnBaseRetNotify(const MSDKBaseRet &baseRet)
    {

    }

7.5.8 Uninstall MSDK

Invoke MSDKLogin::UnInstall interface

    //The interface needs to be invoked when the game is closed, so as to prevent the game from being unable to be closed normally
    MSDKLogin::UnInstall();

7.6 Access the Notice module

7.6.1 Import header files

    #include "MSDKNotice.h"

7.6.2 Set callback

    MyObserver *observer = MyObserver::GetInstance();
    MSDKNotice::SetNoticeObserver(observer);

7.6.3 Get the notice data

Invoke MSDKNotice::LoadNoticeData interface

    std::string group = "1";
    std::string language = "zh-CN";
    int region = = 156;
    std::string partition = "0";
    std::string extra_json = "{}";
    MSDKNotice::LoadNoticeData(group, language, region, partition, extra_json);

Implement the notice callback

    void MyObserver::OnLoadNoticeData(const MSDKNoticeRet &noticeRet)
    {

    }

7.7 Get the encrypted token

The methods of obtaining encrypted tokens on the PC and the mobile terminal are the same. For details, please refer to Instructions for obtaining encrypted tokens.

VIII. Server authentication

For server authentication, please refer to Backend - Login Authentication.

IX. PC-side WebView capability - Code Scanning-based Login and Real Name Popup

9.1 Version characteristics

Based on CEF and Webview2, MSDKPC V5.0.0.21 adds PC-side WebView capability support. At present, this capability is only used for the following functions to support in-game popups (no need to skip to the system's Webview):

• Code-scanning login on WeChat and QQ channels
  
• Central-control real-name authentication process
  

9.2 Pre-description (Important)

• CEF and WebView2 are supported by default in the PC library provided by MSDK;
  
• If you need to use MSDKWebView to pop up the QR code-scanning pop-up window and the central-control real-name authentication pop-up window, you need to add DEFAULT_WEBVIEW_TYPE in the configuration file MSDKConfig.ini to specify the default mode so as to enable the Webview capability;
  
• The volume of CEF library dependencies is relatively large. If you do not want to access CEF, relevant CEF library dependencies can be removed. Please refer to Split CEF Library Dependencies;
  
• The volume of WebView2 library dependencies is small, and the WebView2 mode needs to be supported by the WebView2 runtime environment. If the WebView2 mode is selected, please refer to WebView2 Runtime Environment for processing;
  

9.3 Function example

9.3.1 Add configuration

MSDKConfig.ini adds DEFAULT_WEBVIEW_TYPE configuration to specify the default WebView mode (disabled, CEF or WebView2).
OPENURL configures the open platform's link, an open code scanning page; REDIRECT URI configures the redirect URI, the redirect address after scanning the code

9.3.2 Code-scanning login

The extraJson method of the login interface MSDKLogin::Login has added two extension parameters to support in-game pop-up code-scanning login. Currently, the code-scanning login scenes of WeChat and QQ channels are supported:

WeChat code-scanning login
Note: Support to open WeChat's code-scanning page for login in the form of in-game pop-up window
Invoke example:

//Open the code-scanning page through the Webview pop-up window, and use the CEF mode
std::string ext_json = "{\"login_use_msdk_webview\": 1, \"webview_type\": 1}";       
MSDKLogin::Login("WeChat", "", "", ext_json);

QQ code-scanning login
Note: Support to open QQ's code-scanning page for login in the form of in-game pop-up window
Invoke example:

//Open the code-scanning page through the Webview pop-up window, and use the WebView2 mode
std::string ext_json = "{\"login_use_msdk_webview\": 1, \"webview_type\": 2}";       
MSDKLogin::Login("QQ", "", "", ext_json);

9.4 Central-control real-name authentication

MSDKPC 5.0.0.21 has embedded the central-control real-name authentication process in the login process; According to the backend strategy, there are the following performances:

• If the player needs to conduct real name authentication, [Real-Name Authentication Popup Window] will be triggered. After completing real-name authentication, the player can log in again to achieve a successful login
  

9.4.1 Real-name pop-up window

This is issued by the backend strategy. You can click the Return to the Game button to close the pop-up window, and the real-name authentication fails. You can perform real-name authentication. After the real-name authentication is completed, please close the pop-up window. When you log in again, you will complete the login authentication.

9.5 Split CEF Library Dependencies

In the MSDK library package, the following dependencies are added to support the CEF mode. The CEF dependencies have a large volume. If you do not use the CEF mode, you can delete dependencies according to the following table to save package volume:

9.6 WebView2 runtime environment

If App chooses to access WebView2,the user needs to have a WebView2 runtime environment to support the operation of WebView2
During the installation of the game package, you need to help or guide the user to install the WebView2 runtime environment to ensure that the WebView2 mode scene can run normally
For details, please refer to the official WebView2 runtime environment documentation:
https://learn.microsoft.com/en-us/microsoft-edge/webview2/concepts/distribution

It is recommended to test and verify key paths such as code-scanning login and automatic login after accessing the PC WebView solution.

9.7 Known problems and their solutions

1、Problem description: When a Unity game is in full screen, if you make an in-game popup this time, the Unity game will lose focus and will be automatically minimized:
Solution: https://answers.unity.com/questions/17360/how-to-prevent-a-fullscreen-application-from-minim.html

When the game is packaged, it is needed to check the Visible In Background option

2、Problem description: The libcef.dll.pdb file cannot be found in the debugging error report of Visual Studio Debug

Solution:
Due to the large size of the libcef.dll.pdb file (approximately 3G+), MSDK cannot provide it with the distribution package. Games can solve this problem by choosing one of the following methods:

• Compiling the program with Release will not cause the above problem
  

• If a game indeed connects to MSDK's integrated code scanning and real name popup solution and needs to debug and locate the problem, it is necessary to use libcef.dll.pdb. In this case, you can download this file at CEF and then place it into the package (it is recommended that the package should not include this pdb file when it is officially released, so as to avoid the package from having an excessive volume)
  

  

  The method for checking the version number in the second step shown in the above image:
  

  

  In the third step, place the downloaded libcef.dll.pdb file into the library directory of the project:
  

  

X. FAQ

1. Among the parameters returned by PC login, avatars and nicknames are empty. This is a normal phenomenon. The PC version does not support avatars and nicknames temporarily.
   

2. After Unity engine or UnrealEngine engine is packaged as an exe file, it is necessary to copy MSDK's libraries, third-party libraries that MSDK depends on, and the resource files of MSDK to the exe directory; otherwise, an exception will occur when you run the exe file. If you compile Windows first and then compile Android or iOS, you need to clear the cache first.
   

3. The token obtained through PC Web-based authorization has the same type as that obtained through mobile game authorization. When performing server authentication, the access party must confirm that in json body, there is no need to additionally pass "client_os":5 and 5 is not passed into the os field in Request URL; otherwise, the authentication will fail.
   

4. If you want to get MSDK PC logs, please refer to FAQ-Get MSDK logs-PC. If you want to get the MSDK PC version, please refer to FAQ-Check MSDK Version Number-PC.