04/29/2024 11:54:52

接入教程（PC）

一、概述

MSDK PC 版是专为 PC 平台的业务接入微信、QQ、Steam 平台所新开发适配的版本，方便业务在 Unity、UnrealEngine Editor 模式下进行微信、QQ、Steam 平台授权登录。

MSDKPC 5.0.0.21 版本开始，MSDK 新增 PC 端 WebView 能力支持，目前该能力仅用于微信及QQ渠道扫码登录、中控实名认证流程功能， MSDKPC 5.0.0.23 版本增加打开窗口展示网页功能，能力详情参考九、PC 端 WebView 能力。
接入 MSDKPC 5.0.0.21 及以上版本，如游戏已自行实现扫码和实名能力，可以选择不接入此【扫码和中控实名集成方案】，参考9.7 剥离 CEF 库依赖指引删除 CEF 相关库，可以减少包体积。

二、平台权限申请

2.1 微信平台权限

因微信平台不再接受新业务的“SDK 形式登录权限”申请。MSDK PC 从 5.0.0.13 版本开始支持 Web 形式的授权登录，授权流程请参考 4.2 Web形式授权章节。
接入 Web 形式授权的业务需要申请“授权回调重定向 URI”，具体需要接入方联系微信游戏助手提供微信 AppID 申请修改或获取网站应用所需的重定向 URI。

注意：查看 MSDK PC 版本，可参考 FAQ-查看MSDK版本号-PC 。

2.2 QQ平台权限

接入方需要联系 qqconnecthelper 申请“手Q PC 应用”，获取手Q PC 登录权限。
接入 Web 形式授权的业务需要申请“授权回调重定向 URI”，具体需要接入方使用在飞鹰系统注册手游的游戏项目 QQ 账号登录 QQ互联管理系统，登录成功后可看到如下界面。

选择应用管理->创建应用，在弹出框中填写相应信息，以 MSDKDemo 为例。

其中，
①：选择 0-网站应用
②：填入游戏移动端的 QQ AppID
③：选择 1-移动应用
④：填入游戏移动端的 QQ AppKey
⑤：填入游戏的重定向 URI
具体参数可企业微信咨询 qqconnecthelper，填写完成后点提交按钮等待审核。

注意：

使用的手Q Appid 需有 Windows 应用类型，无此应用类型登录时会报错“not pc app the appid: xxx”。若不确定手Q Appid 是否有 Windows 应用类型，可提供手Q Appid 企业微信联系 qqconnecthelper 进行确认。

若遇到报错“100052, appid does not has permission to get paytoken or openid”，需要联系 qqconnecthelper 申请“获取 paytoken 和 openid”权限解决。

2.3 Steam平台权限

Steam 平台暂无需申请权限。

三、工程说明

注意：MSDK 现不再提供 x86 版本，仅提供 x64 版本。

3.1 目录结构

MSDK Windows 版本目录结构如下：

libmsdk 目录，存放 MSDK PC 端原生库；
include 目录，存放 MSDK 所需的头文件；
bin 目录，存放 MSDKCore.dll 以及 MSDK 所依赖的第三方组件；
lib 目录，存放 MSDKCore.lib；
resources 目录，存放 MSDK 所需的资源文件；
libmsdkadapter 目录，存放 Unity 的桥接层，Unity 引擎业务需要接入；

主要文件说明：

【必须】MSDK Core 包
```
  ├── MSDKCore.dll
```
【必须】配置文件
```
  ├── cacert.pem            证书文件
  ├── MSDKConfig.ini        配置信息
  ├── MSDKRetMsg.json        错误码配置信息
```
特别注意：MSDKConfig.ini 含有关键配置信息，发布之前需要对该文件进行加密。请联系 MSDK 助手来协助处理加密逻辑

【必须】依赖库文件

  ├── pthreadGC2.dll        pthread 库依赖
  ├── pthreadVC2.dll
  ├── libcurl.dll            curl 库依赖
  ├── libssh2.dll
  ├── libssl-1_1-x64.dll
  ├── libssl-1_1.dll
  ├── libcrypto-1_1-x64.dll
  ├── libcrypto-1_1.dll
  ├── WebView2Loader.dll    WebView2 运行时依赖
  └── zlibwapi.dll        zlib 库依赖

【按需】Unity 桥阶层
```
  ├── MSDKUnityAdapter.dll
```

【按需】QQ 登录组件（须开通权限）

  ├── QQOpenSDK.dll
  ├── SSOCommon.dll
  ├── SSOPlatform.dll

【按需】微信登录组件（须开通权限）
```
  ├── wxlogin.dll
```

【按需】Steam 组件

  ├── steam_api64.dll        依赖库
  ├── steam_appid.txt        AppID 配置文件

【按需】MSDK 提供的 CEF 库

  ├── MSDKCefWebView.dll
  ├── MSDKWebViewRender.exe

【按需】CEF 库

  ├── cef.pak
  ├── cef_100_percent.pak
  ├── cef_200_percent.pak
  ├── cef_extensions.pak
  ├── chrome_elf.dll
  ├── d3dcompiler_47.dll
  ├── devtools_resources.pak
  ├── icudtl.dat
  ├── libEGL.dll
  ├── libGLESv2.dll
  ├── libcef_msdk.dll(PC 5.0.0.25 之前版本)、libcef.dll(PC 5.0.0.25及之后版本)
  ├── locales
  │   ├── am.pak
  │   ├── ar.pak
  │   ├── bg.pak
      ...
  ├── v8_context_snapshot.bin
  ├── snapshot_blob.bin

【按需】自建账号验证码
```
  ├── captcha_encrpted
  ├── oversea
  │   └── captcha_encrpted
```
二选一即可， oversea 目录为海外版本，根据业务请，oversea 移动到外层覆盖源文件即可
【按需】 Xbox 登录插件
```
  ├── MSDKXbox.dll
  ├── XCurl.dll
  ├── GraphicsLogo.png
  ├── LargeLogo.png
  ├── SmallLogo.png
  ├── SplashScreen.png
  ├── StoreLogo.png
```
其中，这里的 png 文件仅为提示参考作用，需要配合 GDK 的 MicrosoftGame.config 具体配置来处理这些资源文件

更多信息请参考：https://learn.microsoft.com/en-us/gaming/gdk/_content/gc/system/overviews/microsoft-game-config/microsoftgameconfig-overview#microsoftgameconfig-creation

3.2 发布文件剔除说明

MSDK 默认提供了 pdb、exp、lib 文件，方便开发者进行编译调试。游戏在发布时，须删掉对应的文件。

3.3 DLL 签名文件说明

MSDK 的库文件默认不带签名，业务需要自行对 DLL 进行签名。

四、授权流程

4.1 SDK形式授权

-->①用户点击登录按钮 -->②Game Client调用MSDK登录接口 -->③Game Client监听MSDK二维码回调 -->④Game Client向用户展示二维码 -->⑤用户扫码 -->⑥Game Client监听MSDK登录回调 -->⑦Game Client同步票据给Game Server -->⑧Game Server向MSDK Sercer鉴权 -->⑨Game Server接收到鉴权结果 -->⑩Game Server同步鉴权结果给Game Client

授权时序如下：

4.2 Web形式授权

Web 形式授权可通过以下两种方式接入，业务自行打开扫码页面和 MSDK 打开扫码页面，其中【MSDK 打开扫码界面】的方式在 5.0.0.21 及以上版本开始支持，详细能力介绍参考：九、PC 端 WebView 能力。

4.2.1 业务自行打开扫码页面

-->①用户点击登录按钮 -->②Game Client使用浏览器插件打开QQ/WeChat Web授权页 -->③用户扫码 -->④Game Client监听重定向URI开头的请求，拦截截取URI上的code参数 -->⑤Game Client关闭浏览器插件，调用MSDK登录接口并传递code等参数 -->⑥Game Client监听MSDK登录回调 -->⑦Game Client同步票据给Game Server -->⑧Game Server向MSDK Sercer鉴权
-->⑨Game Server接收到鉴权结果 -->⑩Game Server同步鉴权结果给Game Client

授权时序如下：

注意：

PC Web 形式是通过 WeChat、QQ 平台的 oauth 协议进行授权登录，简单来说就是通过 code 换 token，可点击 QQ平台、微信平台了解双平台的 oauth 授权流程细节。

PC Web 形式授权获取的 token 与手游授权获取的 token 类型一致。接入方在进行服务端鉴权的时候务必确认 json body 中无需额外传递 "client_os":5，同时请求 URL 中的 os 字段不要传入 5，否则会造成鉴权失败。

4.2.2 MSDK 打开扫码页面（MSDKPC 5.0.0.21 及以上版本支持）

-->①用户点击登录按钮 -->②Game Client调用MSDK登录接口 -->③MSDK向用户展示二维码 -->④用户扫码 -->⑤Game Client监听MSDK登录回调 -->⑥Game Client同步票据给Game Server -->⑦Game Server向MSDK Sercer鉴权 -->⑧Game Server接收到鉴权结果 -->⑨Game Server同步鉴权结果给Game Client

授权时序如下：

五、Visual Studio接入指引

5.1 添加头文件包含目录

5.2 添加MSDKCore.lib依赖

5.3 将MSDKCore.dll及MSDK所依赖的第三方组件copy至可执行文件目录

5.4 可执行文件目录配置MSDKConfig.ini、MSDKRetMsg.Json、cacert.pem

1、MSDKConfig.ini 文件中，MSDK_URL 字段为 MSDK Server 地址。业务对外发布时必须改为 MSDK 现网环境 https://itop.qq.com;
2、MSDK_GAME_ID、MSDK_SDK_KEY、WECHAT_APP_ID、QQ_APP_ID、QQ_APP_KEY、STEAM_APP_ID 需修改为业务自身的；
3、MSDKRetMsg.Json 文件为 MSDK 客户端的 json 解析协议描述。业务可无需过多关注，直接从 resources 目录拷贝至可执行文件目录即可；
4、cacert.pem 文件为 MSDK 客户端与服务端通信的公钥。可直接从 resources 目录拷贝至可执行文件目录；

注意：从 GCloud 官网下载的版本，因 QQ_APP_KEY 字段为业务敏感信息，该字段仍需要各业务手动配置。

5.5 添加预编译参数GCLOUD_MSDK_WINDOWS

添加预编译参数 GCLOUD_MSDK_WINDOWS 以便可以正常编译 MSDK Windows 版本。

5.6 接入登录

5.6.1 引入头文件

    #include "MSDKLogin.h"

5.6.2 设置回调

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

5.6.3 登录

调用MSDKLogin::Login接口

SDK 形式授权（仅 QQ、Steam 支持）

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

    Steam 渠道登录请务必注意以下几点： 
    1. 联调阶段必须在 .exe 相同目录配置 steam_appid.txt 文件且预先启动登录 Steam 客户端，无需在 MSDKConfig.ini 文件中配置 STEAM_APP_ID 参数，否则会导致 Steam 渠道登录失败；
    2. 向 Steam Store 提交发布版本时无需提交 steam_appid.txt 文件但必须在 MSDKConfig.ini 文件中配置 STEAM_APP_ID 参数，否则会导致在未运行 Steam 客户端的情况下授权登录拉不起 Steam 客户端进而导致 Steam 渠道登录失败；

Web 形式授权（仅 QQ、WeChat 支持）

业务自行打开扫码页面，需要截取 code 传给 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());
    或
    std::string extra_json = "{\"channel\":\"WeChat\",\"channelID\":1,\"channelOpenID\":\"\",\"pluginData\":{\"code\":\"xxx\"}}";
    MSDKLogin::Login("", "", "", extra_json.c_str());

    1. Web 形式授权，Login 接口第一个入参需传空 ""；
    2. QQ 渠道 extra_json 字段除了传递 code 参数外，还需要额外传递 redirect_uri 和 msdk_qq_login_use_code，其中 redirect_uri 为业务的重定向 URI，msdk_qq_login_use_code 固定填 1；

MSDK 打开扫码页面（MSDKPC 5.0.0.21 及以上版本支持）

// 通过 webview 弹窗打开扫码页面，使用 WebView2 模式
std::string ext_json = "{\"login_use_msdk_webview\": 1, \"webview_type\": 2}"；       
MSDKLogin::Login("QQ", "", "", ext_json);
或
// 通过 webview 弹窗打开扫码页面，使用 CEF 模式
std::string ext_json = "{\"login_use_msdk_webview\": 1, \"webview_type\": 1}"；       
MSDKLogin::Login("WeChat", "", "", ext_json);

1. MSDK 打开扫码页面 Web 形式授权，Login 接口第一个入参传入 QQ 或 WeChat；
2. login_use_msdk_webview 配置为 1 表示使用 MSDKWebView 能力进行弹窗扫码登录，不传此配置项 或 配置为 0 表示不使用弹窗扫码登录，维持业务原来的登录逻辑；
3. webview_type 在 login_use_msdk_webview 值传为 1 的基础上：
填 1 表示使用 CEF 模式，填 2 表示使用 WebView2 模式，不传此配置项，则会按 MSDKConfig.ini 中配置的 WebView 默认模式进行扫码弹窗。

实现二维码回调（仅 SDK 形式授权需要，Web 形式不需要）

    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. QQ 平台的 qr_code_url 字段为二维码下载链接，可直接下载后展示给用户；
    2. Steam 平台无需监听该回调，直接监听 OnLoginRetNotify 即可；

实现登录回调

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

    }

    Steam 渠道登录请务必注意以下几点：
    1. 联调阶段接收到 loginRet.retCode = 17 时，请检查是否有配置 steam_appid.txt 文件以及运行 Steam 客户端；
    2. 发布阶段接收到 loginRet.retCode = 17 时，请关闭游戏进程，MSDK 会拉起 Steam 客户端并从 Steam 客户端重启游戏；

5.6.4 自动登录（仅在 MSDK 联调环境下生效）

调用MSDKLogin::AutoLogin接口

    //自动登录仅在 MSDK 联调环境下生效
    MSDKLogin::AutoLogin();

实现登录回调

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

    }

5.6.5 自助实名注册

MSDK PC在5.0.0.19版本开始支持业务自助实名注册。若登录账号为未实名账号，MSDK会将需实名的错误码retCode&登录票据信息&中控实名信息在登录回调OnLoginRetNotify中一并回调给业务，中控实名信息存放在MSDKLoginRet.channelInfo字段中。业务侧可自行根据中控相关信息打开Webview组件进行实名注册，实名注册成功后调用MSDKLogin::OnRealNameAuthFinished接口透传登录态&实名结果继续进行登录流程，并监听MSDK登录回调。

调用MSDKLogin::OnRealNameAuthFinished接口

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

5.6.6 获取登录票据

调用MSDKLogin::GetLoginRet接口

    MSDKLoginRet loginRet;
    MSDKLogin::GetLoginRet(loginRet);

5.6.7 设置安装渠道号

PC 需要游戏自行设置安装渠道，在初始化 MSDK 之后调用。如果设置了安装渠道，会使用已设置的渠道值；未设置则使用默认值 "Windows"。

   MSDKLogin::SetInstallChannel(const String &channel)

5.6.8 登出

调用MSDKLogin::Logout接口

    MSDKLogin::Logout();

实现登出回调

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

    }

5.6.9 卸载MSDK

调用MSDKLogin::UnInstall接口

    //游戏关闭时需调用下该接口，以防游戏不能正常关闭
    MSDKLogin::UnInstall();

5.7 接入公告

5.7.1 引入头文件

    #include "MSDKNotice.h"

5.7.2 设置回调

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

5.7.3 获取公告数据

调用MSDKNotice::LoadNoticeData接口

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

实现公告回调

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

    }

5.8 获取加密票据

PC 与移动端获取加密票据方式一致，详情可参见获取加密票据说明。

六、Unity接入指引

6.1 按指引接入MSDK Script

按照 GCloud接入指引接入 MSDK Script。

6.2 将MSDKCore.dll、MSDKUnityAdapter.dll及MSDK所依赖的第三方组件copy至asset/Plugins目录

6.3 asset/Plugins目录配置MSDKConfig.ini、MSDKRetMsg.Json、cacert.pem

1、MSDKConfig.ini 文件中 MSDK_URL 字段为 MSDK Server 地址。业务对外发布时必须改为 MSDK 现网环境 https://itop.qq.com;
2、MSDK_GAME_ID、MSDK_SDK_KEY、WECHAT_APP_ID、QQ_APP_ID、QQ_APP_KEY、STEAM_APP_ID 需修改为业务自身的；
3、MSDKRetMsg.Json 文件为 MSDK 客户端的 json 解析协议描述。业务可无需过多关注，直接从 resources 目录拷贝；
4、cacert.pem 文件为 MSDK 客户端与服务端通信的公钥。可直接从 resources 目录拷贝；

注意：从 GCloud 官网下载的版本，因 QQ_APP_KEY 字段为业务敏感信息，该字段仍需要各业务手动配置。

6.4 Editor模式下工程根目录配置steam_appid.txt

注意：Editor 模式下 copy steam_appid.txt 至工程根目录，否则会导致 Editor 模式下 Steam 授权失败，未接入 Steam 授权的业务可忽略此配置。

6.5 将MSDK的C#脚本拷贝至asset目录

6.6 添加预编译参数GCLOUD_MSDK_WINDOWS

添加预编译参数 GCLOUD_MSDK_WINDOWS 以便可以正常编译 MSDK Windows 版本。

6.7 接入登录

6.7.1 初始化MSDK

    using GCloud.MSDK;
    MSDK.Init ();

6.7.2 设置回调

    private void setLoginObserver ()
    {
        //登录回调
        MSDKLogin.LoginRetEvent += OnLoginRetEvent;
        //登出回调
        MSDKLogin.LoginBaseRetEvent += OnLoginBaseRetEvent;
#if GCLOUD_MSDK_WINDOWS
        //Windows平台二维码回调（仅 SDK 形式授权需要，Web 形式不需要）
        MSDKLogin.QrCodeRetEvent += OnQrCodeRetEvent;
#endif
    }

6.7.3 实现回调

#if GCLOUD_MSDK_WINDOWS
    private void OnQrCodeRetEvent (MSDKQrCodeRet qrCodeRet)
    {
        //登录二维码回调（仅 SDK 形式授权需要，Web 形式不需要）
        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. QQ 平台的 QrCodeUrl 字段为二维码下载链接，可直接下载后展示给用户；
    2. Steam 平台无需监听该回调，直接监听 OnLoginRetNotify 即可；
#endif

    private void OnLoginRetEvent (MSDKLoginRet loginRet)
    {
        //登录回调
    }

    Steam 渠道登录请务必注意以下几点：
    1. 联调阶段接收到 loginRet.retCode = 17 时，请检查是否有配置 steam_appid.txt 文件以及运行 Steam 客户端；
    2. 发布阶段接收到 loginRet.retCode = 17 时，请关闭游戏进程，MSDK 会拉起 Steam 客户端并从 Steam 客户端重启游戏；

    private void OnLoginBaseRetEvent (MSDKBaseRet baseRet)
    {
        //登出回调
    }

6.7.4 登录

调用MSDKLogin.Login接口

SDK 形式授权（仅 QQ、Steam 支持）

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

    Steam 渠道登录请务必注意以下几点：
    1. 联调阶段必须在工程根目录配置 steam_appid.txt 文件且预先启动登录 Steam 客户端，无需在 MSDKConfig.ini 文件中配置 STEAM_APP_ID 参数，否则会导致 Steam 渠道登录失败；
    2. 向 Steam Store 提交发布版本时无需提交 steam_appid.txt 文件但必须在 MSDKConfig.ini 文件中配置 STEAM_APP_ID 参数，否则会导致在未运行 Steam 客户端的情况下授权登录拉不起 Steam 客户端进而导致 Steam 渠道登录失败；

Web 形式授权（仅 QQ、WeChat 支持）

业务自行打开扫码页面，需要截取 code 传给 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);
    或
    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. Web 形式授权，Login 接口第一个入参需传空 ""；
    2. QQ 渠道 extra_json 字段除了传递 code 参数外，还需要额外传递 redirect_uri 和 msdk_qq_login_use_code ，其中 redirect_uri 为业务的重定向 URI，msdk_qq_login_use_code 固定填 1。

MSDK 打开扫码页面（MSDKPC 5.0.0.21 及以上版本支持）

// 通过 webview 弹窗打开扫码页面，使用 WebView2 模式
std::string ext_json = "{\"login_use_msdk_webview\": 1, \"webview_type\": 2}"；       
MSDKLogin::Login("QQ", "", "", ext_json);
或
// 通过 webview 弹窗打开扫码页面，使用 CEF 模式
std::string ext_json = "{\"login_use_msdk_webview\": 1, \"webview_type\": 1}"；       
MSDKLogin::Login("WeChat", "", "", ext_json);

1. MSDK 打开扫码页面 Web 形式授权，Login 接口第一个入参传入 QQ 或 WeChat；
2. login_use_msdk_webview 配置为 1 表示使用 MSDKWebView 能力进行弹窗扫码登录，不传此配置项 或 配置为 0 表示不使用弹窗扫码登录，维持业务原来的登录逻辑；
3. webview_type 在 login_use_msdk_webview 值传为 1 的基础上：
填 1 表示使用 CEF 模式，填 2 表示使用 WebView2 模式，不传此配置项，则会按 MSDKConfig.ini 中配置的 WebView 默认模式进行扫码弹窗。

6.7.5 自动登录（仅在 MSDK 联调环境下生效）

调用MSDKLogin.AutoLogin接口

    //自动登录仅在 MSDK 联调环境下生效
    MSDKLogin.AutoLogin();

6.7.6 自助实名注册

调用MSDKLogin::OnRealNameAuthFinished接口

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

6.7.7 获取登录票据

调用MSDKLogin.GetLoginRet接口

    MSDKLoginRet ret = MSDKLogin.GetLoginRet ();

6.7.8 设置安装渠道号

PC 需要游戏自行设置安装渠道，在初始化 MSDK 之后调用。如果设置了安装渠道，会使用已设置的渠道值；未设置则使用默认值 "Windows"。

   MSDKLogin::SetInstallChannel(const String &channel)

6.7.9 登出

调用MSDKLogin.Logout接口

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

6.7.10 卸载MSDK

调用MSDK.UnInstall接口

    //游戏关闭时需调用下该接口，以防游戏不能正常关闭
    MSDK.UnInstall();

6.8 接入公告

6.8.1 引入头文件

    #include "MSDKNotice.h"

6.8.2 设置回调

    MSDKNotice.NoticeRetEvent += mOthersCallBack.OnNoticeRetEvent;

6.8.3 获取公告数据

调用MSDKNotice::LoadNoticeData接口

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

实现公告回调

    public void OnNoticeRetEvent(MSDKNoticeRet noticeRet)
    {

    }

6.9 获取加密票据

PC 与移动端获取加密票据方式一致，详情可参见获取加密票据说明。

七、UnrealEngine接入指引

7.1 按指引下载接入MSDK整包套件

从 GCloud 下载 MSDK 整包套件，下载解压后如下图所示。

7.2 Copy MSDKCore至Plugins目录

将下载的压缩包解压后根目录的 MSDKCore 文件夹整个 copy 至 Plugins/OneSDKPlugins 目录，如下图所示。

7.3 修改MSDKConfig.ini配置文件

将 Plugins 目录下的 MSDKConfig.ini 文件配置修改为业务自身的配置信息，路径如下。

注意：从 GCloud 官网下载的版本，因 QQ_APP_KEY 字段为业务敏感信息，该字段仍需要各业务手动配置。

7.4 修改业务编译脚本，添加对MSDKCore的依赖

业务的 Build.cs 中添加对 MSDKCore 的依赖，示例如下。

7.5 接入登录

7.5.1 引入头文件

    #include "MSDKLogin.h"

7.5.2 设置回调

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

7.5.3 登录

调用MSDKLogin::Login接口

SDK 形式授权（仅 QQ、Steam 支持）

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

    Steam 渠道登录请务必注意以下几点：
    1. 联调阶段必须在 .exe 相同目录配置 steam_appid.txt 文件且预先启动登录 Steam 客户端，无需在 MSDKConfig.ini 文件中配置 STEAM_APP_ID 参数，否则会导致 Steam 渠道登录失败；
    2. 向 Steam Store 提交发布版本时无需提交 steam_appid.txt 文件但必须在 MSDKConfig.ini 文件中配置 STEAM_APP_ID 参数，否则会导致在未运行 Steam 客户端的情况下授权登录拉不起 Steam 客户端进而导致 Steam 渠道登录失败；

Web 形式授权（仅 QQ、WeChat 支持）

业务自行打开扫码页面，需要截取 code 传给 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());
    或
    std::string extra_json = "{\"channel\":\"WeChat\",\"channelID\":1,\"channelOpenID\":\"\",\"pluginData\":{\"code\":\"xxx\"}}";
    MSDKLogin::Login("", "", "", extra_json.c_str());

    1. Web 形式授权，Login 接口第一个入参需传空 ""；
    2. QQ 渠道 extra_json 字段除了传递 code 参数外，还需要额外传递 redirect_uri 和 msdk_qq_login_use_code，其中 redirect_uri 为业务的重定向 URI，msdk_qq_login_use_code 固定填 1；

MSDK 打开扫码页面（MSDKPC 5.0.0.21 及以上版本支持）

// 通过 webview 弹窗打开扫码页面，使用 WebView2 模式
std::string ext_json = "{\"login_use_msdk_webview\": 1, \"webview_type\": 2}"；       
MSDKLogin::Login("QQ", "", "", ext_json);
或
// 通过 webview 弹窗打开扫码页面，使用 CEF 模式
std::string ext_json = "{\"login_use_msdk_webview\": 1, \"webview_type\": 1}"；       
MSDKLogin::Login("WeChat", "", "", ext_json);

1. MSDK 打开扫码页面 Web 形式授权，Login 接口第一个入参传入 QQ 或 WeChat；
2. login_use_msdk_webview 配置为 1 表示使用 MSDKWebView 能力进行弹窗扫码登录，不传此配置项 或 配置为 0 表示不使用弹窗扫码登录，维持业务原来的登录逻辑；
3. webview_type 在 login_use_msdk_webview 值传为 1 的基础上：
填 1 表示使用 CEF 模式，填 2 表示使用 WebView2 模式，不传此配置项，则会按 MSDKConfig.ini 中配置的 WebView 默认模式进行扫码弹窗。

实现二维码回调（仅 SDK 形式授权需要，Web 形式不需要）

    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. QQ 平台的 qr_code_url 字段为二维码下载链接，可直接下载后展示给用户；
    2. Steam 平台无需监听该回调，直接监听 OnLoginRetNotify 即可；

实现登录回调

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

    }

    Steam 渠道登录请务必注意以下几点：
    1. 联调阶段接收到 loginRet.retCode = 17 时，请检查是否有配置 steam_appid.txt 文件以及运行 Steam 客户端；
    2. 发布阶段接收到 loginRet.retCode = 17 时，请关闭游戏进程，MSDK 会拉起 Steam 客户端并从 Steam 客户端重启游戏；

7.5.4 自动登录（仅在 MSDK 联调环境下生效）

调用MSDKLogin::AutoLogin接口

    //自动登录仅在 MSDK 联调环境下生效
    MSDKLogin::AutoLogin();

实现登录回调

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

    }

7.5.5 自助实名注册

调用MSDKLogin::OnRealNameAuthFinished接口

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

7.5.6 获取登录票据

调用MSDKLogin::GetLoginRet接口

    MSDKLoginRet loginRet;
    MSDKLogin::GetLoginRet(loginRet);

7.5.7 设置安装渠道号

PC 需要游戏自行设置安装渠道，在初始化 MSDK 之后调用。如果设置了安装渠道，会使用已设置的渠道值；未设置则使用默认值 "Windows"。

   MSDKLogin::SetInstallChannel(const String &channel)

7.5.8 登出

调用MSDKLogin::Logout接口

    MSDKLogin::Logout();

实现登出回调

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

    }

7.5.9 卸载MSDK

调用MSDKLogin::UnInstall接口

    //游戏关闭时需调用下该接口，以防游戏不能正常关闭
    MSDKLogin::UnInstall();

7.6 接入公告

7.6.1 引入头文件

    #include "MSDKNotice.h"

7.6.2 设置回调

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

7.6.3 获取公告数据

调用MSDKNotice::LoadNoticeData接口

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

实现公告回调

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

    }

7.7 获取加密票据

PC 与移动端获取加密票据方式一致，详情可参见获取加密票据说明。

八、服务端鉴权

服务端鉴权请参考后台-登录鉴权。

九、PC 端 WebView 能力

9.1 版本特性

MSDKPC V5.0.0.21 版本基于 CEF 和 Webview2 增加了 PC 端 WebView 能力支持，该版本能力仅用于以下功能以支持游戏内弹窗（无需跳转系统浏览器）：

微信及QQ渠道扫码登录
中控实名认证流程

MSDKPC V5.0.0.23 版本基于上个版本的特性，增加以下功能：

拉起窗口展示网页
JS关闭浏览器功能，回传数据功能
扫码窗口和实名窗口支持自定义窗口大小
webview模式（CEF 或 WebView2）窗口支持右键菜单语言自定义

9.2 前置说明（重要）

CEF 和 WebView2 在 MSDK 提供的 PC 库中默认支持；
如需使用 MSDKWebView 进行扫码弹窗和中控实名认证弹窗，需要在 MSDKConfig.ini 配置文件中新增 DEFAULT_WEBVIEW_TYPE 配置，指定默认模式，用以开启 webview 能力；
CEF 库依赖体积比较大，如果不希望接入 CEF，CEF 相关库依赖可以进行移除；可参考【剥离 CEF 库依赖】章节；
WebView2 库依赖体积小，WebView2 模式需要 WebView2 Rumtime 运行时环境支持，如果选择 WebView2 模式，请参考【WebView2 运行时环境】章节进行处理；

9.3 功能示例

9.3.1 新增配置

MSDKConfig.ini 新增了 DEFAULT_WEBVIEW_TYPE 配置，用来指定默认 WebView 模式（不开启、CEF 或 WebView2）。
OPEN_URL 配置开放平台链接，打开的扫码页；REDIRECT_URI 配置重定向 URI，扫码后的跳转地址。

配置	参数取值	说明
DEFAULT_WEBVIEW_TYPE	0 - 不开启 1 - CEF 2 - WebView2	在 MSDKConfig.ini 中 - 默认无此配置项或配置为 0 表示不开启 webview 能力 - 配置为 1 表示默认使用 CEF 模式; - 配置为 2 表示默认使用 WebView2模式；重要：如果仅接入其中一种模式，在填写此默认配置时，请根据实际接入模式填写此配置项的值
WECHAT_OPEN_URL	默认即可	微信开放平台的链接，打开的扫码页
WECHAT_REDIRECT_URI	配置为2.1 微信平台权限中的重定向 URI	扫码后的跳转链接
QQ_OPEN_URL	默认即可	QQ 开放平台的链接，打开的扫码页
QQ_REDIRECT_URI	配置为2.2 QQ平台权限中的授权回调重定向 URI	扫码后的跳转链接

9.3.2 扫码登录

MSDKLogin::Login 登录接口的 extraJson 新增了两个扩展参数来支持游戏内弹窗扫码登录，目前支持微信和 QQ 渠道的扫码登录场景：

扩展参数	参数取值	说明
login_use_msdk_webview	0 - 不使用 webview 弹窗 1 - 使用 webview 弹窗	可选； - 不传此配置项或配置为 0 表示不使用弹窗扫码登录；维持业务原来的登录逻辑； - 配置为 1 表示使用 MSDKWebView 能力进行弹窗扫码登录；
webview_type	1 - CEF 2 - WebView2	可选；在 login_use_msdk_webview 值传为 1 的基础上 - 不传此配置项，则会按 MSDKConfig.ini 中配置的 WebView 默认模式进行扫码弹窗； - 填 1 表示使用 CEF 模式； - 填 2 表示使用 WebView2 模式；重要：如果仅接入其中一种模式，请根据实际的情况来决定此参数的具体传值
webview_window_scale	0 ~ 1.0	PC 5.0.0.23支持自定义窗体大小示例 {\"webview_window_scale\": 0.7 } ：弹窗大小指定为【0.7 * 游戏窗体大小】
webview_address_visible	true - 显示 false - 不显示	PC 5.0.0.24 版本新增控制窗口是否显示地址 , 若未配置默认不显示。示例 {\"webview_address_visible\": true}：显示地址

微信扫码
说明：支持以游戏内弹窗的形式打开微信扫码页面进行登录；
调用示例：

// 通过 webview 弹窗打开扫码页面，使用 CEF 模式
std::string ext_json = "{\"login_use_msdk_webview\": 1, \"webview_type\": 1}"；       
MSDKLogin::Login("WeChat", "", "", ext_json);

QQ 扫码
说明：支持以游戏内弹窗的形式打开 QQ扫码页面进行登录；
调用示例：

// 通过 webview 弹窗打开扫码页面，使用 WebView2 模式
std::string ext_json = "{\"login_use_msdk_webview\": 1, \"webview_type\": 2}"；       
MSDKLogin::Login("QQ", "", "", ext_json);

9.4 中控实名认证

MSDKPC 5.0.0.21 版本在登录流程中嵌入了中控实名认证流程；根据后台策略，有以下表现：

如果该玩家需要进行实名认证，会触发【实名认证弹窗】；完成实名认证后再次登录即可登录成功；

中控弹窗使用的WebView模式（CEF 或 WebView2），取决于业务在 MSDKConfig.ini 中的 DEFAULT_WEBVIEW_TYPE 配置，详情可以参考前面【9.3.1 新增配置】章节进行配置；

9.4.1 实名弹窗

由后台策略下发，可以点击返回游戏关闭弹窗，实名失败；可以进行实名认证，实名完成后关闭弹窗，再次登录即可完成登录鉴权。

9.5 拉起窗口展示网页

MSDKPC 5.0.0.23 版本新增打开网页功能及网页 JS 调用接收回调功能。

展示网页的窗口使用的 WebView 模式（CEF 或 WebView2），取决于业务在 MSDKConfig.ini 中的 DEFAULT_WEBVIEW_TYPE 配置，详情可以参考前面【9.3.1 新增配置】章节进行配置；

9.5.1 功能使用

1）打开网页

static void MSDKWebView::OpenUrl(const String& url, int screenType = 1, bool isFullScreen = false,
            bool isUseURLEncode = true, const String& extraJson = "",
            bool isBrowser = false);

参数说明

参数名称	参数类型	说明
url	string	打开的网页链接，webview2 模式下要求 https 头，否则打开空白页。
screenType	int	webview模式，0-不使用；1-CEF; 2-WebView2
isFullScreen	bool	是否以全屏的方式打开 - true：以全屏展示(跟游戏窗体同大小)，不可拖拽改变大小。 - false：可以通过扩展参数改变窗体行为，不传递扩展参数则以全屏展示(跟游戏窗体同大小)。
isUseURLEncode	bool	是否在 URL 后附加加密的登录态 itopencodeparam，默认 true。解密加密登录态参考接口：解密校验
extraJson	string	扩展参数，json字符串，目前支持以下扩展参数： - webview_window_scale：设置缩放比例, 范围 0 ~ 1.0 ，比如 0.5 表示相对于游戏一半展示，仅在 isFullScreen 为 false 生效。 - webview_window_resizable：true - 可以、false - 不可以，表示弹窗是否可以通过拖拽边框改变大小，仅在 isFullScreen 为 false 生效。 - is_closable：配置右上角关闭按钮展示 true - 可关闭、false - 不可关闭，传入此选项则默认启用该功能，若传入 false 则需要退出游戏才能关闭页面，页面可调用 JS 接口关闭。 - webview_address_visible：true - 显示、false - 不显示，PC 5.0.0.24 版本新增控制窗口地址是否显示功能，默认不展示。例如：{"webview_window_scale":0.5,"webview_window_resizable":true} 表示相对于游戏窗体以 0.5 的缩放进行展示，且可以进行拖拽改变窗体大小。
isBrowser	bool	暂未支持使用

2）加密URL

static std::string MSDKWebView::GetEncodeUrl(const String& url)

3）关闭网页

static void MSDKWebView::Close();

4）接收回调

网页可调用 JS 接口实现关闭 webview 窗口、JS 传递数据到游戏的功能，调用方式请参考MSDK js demo。

JS 回传给游戏的数据通过 MSDKWebViewObserver 将结果返回。

class MSDK_EXPORT MSDKWebViewObserver
{
public:
virtual ~MSDKWebViewObserver() {};
virtual void OnWebViewOptNotify(const MSDKWebViewRet& webViewRet) {};
};

void MSDKWebView::SetWebViewObserver(MSDKWebViewObserver* webViewObserver);

9.6 右键菜单语言自定义

MSDKPC 5.0.0.23 版本支持 webview 右键菜单语言自定义化，通过在 MSDKConfig.ini 中配置 MSDK_WEBVIEW_LOCALE 的方式来指定所使用的语言，不配置则默认按用户系统设置的语言展示。

注：右键菜单为 cef 和 webview2 默认提供的能力，MSDK 未对右键菜单进行规划，暂维持 cef 和 webview2 的默认实现。

配置示例：

MSDK_WEBVIEW_LOCALE = zh-CN

9.7 剥离 CEF 库依赖

在 MSDK 库包体中，增加了以下依赖来支持 CEF 模式。CEF 依赖体积较大，如您不使用 CEF 模式，为节省包体积，可以根据下表进行删除：

依赖	是否可删除
cef_100_percent.pak	是
cef_200_percent.pak	是
cef_extensions.pak	是
cef.pak	是
chrome_elf.dll	是
d3dcompiler_47.dll	是
devtools_resources.pak	是
icudtl.dat	是
libcef_msdk.dll(PC 5.0.0.25 之前版本)、libcef.dll(PC 5.0.0.25及之后版本)	是
libEGL.dll	是
libGLESv2.dll	是
locales 文件夹	是
MSDKCefWebView.dll	是
MSDKCefWebView.exp	是
MSDKCefWebView.lib	是
MSDKCefWebView.pdb	是
snapshot_blob.bin	是
v8_context_snapshot.bin	是

9.8 WebView2 运行时环境

如果业务选择接入 WebView2 的方案，需要用户有 WebView2 运行时环境才能支持 WebView2 的运行。
游戏包安装过程中需要帮助或引导用户安装 WebView2 运行时环境，以保证 WebView2 模式场景工作正常。
详情可以参考官方 WebView2 运行时文档进行处理：
https://learn.microsoft.com/en-us/microsoft-edge/webview2/concepts/distribution

建议接入 PC WebView 方案后，进行扫码登录、自动登录等关键路径的测试验证。

9.9 已知问题及处理方式

1、问题描述：Unity 游戏全屏时，如果进行游戏内弹窗，Unity 游戏会失去焦点，游戏会自动最小化：
解决方案：https://answers.unity.com/questions/17360/how-to-prevent-a-fullscreen-application-from-minim.html

游戏打包的时候，需要勾选 Visible In Background 选项

2、问题描述：Visual Studio Debug 调试报错找不到 libcef.dll.pdb 文件。

解决方案：
由于 libcef.dll.pdb 文件过大（约 3G+），MSDK 不会随发布包提供。业务可以在下述方法中择其一解决：

使用 release 编译，不会出现上述问题；
如业务确实接入了MSDK 集成的扫码和实名弹窗方案且需要调试定位问题，有必要用 libcef.dll.pdb，可以到 CEF 下载一个放进去（建议正式发布时不带该 pdb，避免包体积过大：

上图第二步中查版本号的方法：

第三步中，下载好后，获取 libcef.dll.pdb 文件放到工程中库目录下：

十、常见问题

1、PC 登录返回的参数中，头像和昵称是空的，是正常现象，PC 版本暂不支持头像和昵称。

2、Unity 引擎或 UnrealEngine 引擎打 exe 包后需注意将 MSDK 库、MSDK 所依赖的第三方库以及 MSDK 的资源文件 copy 至 exe 目录（Unity 至 Plugins 目录，即 MSDKCore.dll 同目录），否则运行 exe 会报异常。如先编 Windows 再编 Android 或 iOS， 需要先清缓存 。

3、PC Web 形式授权获取的 token 与手游授权获取的 token 类型一致。接入方在进行服务端鉴权的时候务必确认 json body 中无需额外传递 "client_os":5，同时请求 URL 中的 os 字段不要传入 5，否则会造成鉴权失败。

4、获取 MSDK PC 日志，可参考 FAQ-获取MSDK日志-PC 。获取 MSDK PC 版本，可参考 FAQ-查看MSDK版本号-PC 。