03/12/2026 16:49:23

MSDK MiniGameSDK 接入指南

Release note:

日期	版本号	更新说明
2026-03-04	1.1.0 正式版，C# 基于 MSDKPIX 5.42.100 版本	兼容 QQ 用户信息差异
2026-02-27	1.1.0 正式版，C# 基于 MSDKPIX 5.42.100 版本	内部优化
2026-02-06	1.0.0 联调版本，仅用于接入测试	更新用户信息，见 2.8 章节
2026-01-28	1.0.0 联调版本，仅用于接入测试	Beacon 上报
2026-01-09	1.0.0 联调版本，仅用于接入测试	微信、QQ 小游戏登录

版本下载：

SDK：1.0.0 正式版

一、工程配置

目前仅支持原生 js 和 untiy/团结引擎。

1.1 SDK 拷贝

原生 js 只需拷贝 MSDK 目录和 MSDKConfig.json 文件到小游戏目录下，这里以团结引擎的 {小游戏工程}/unity-sdk 为例：

拷贝 MSDK 目录到 {unity 工程}/Assets/WX-WASM-SDK-V2/Runtime/wechat-default/unity-sdk 目录
拷贝 MSDKConfig.json 配置文件到 {unity 工程}/Assets/WX-WASM-SDK-V2/Runtime/wechat-default 目录：
仅 unity 接入时需要，拷贝 MSDKBridge.jslib 文件到 {unity 工程}/Assets/WX-WASM-SDK-V2/Runtime/Plugins 目录：

1.2 修改 MSDKConfig.json 配置（重要）

请将以下配置修改为业务自身的，数据类型与示例保持一致，不要将示例配置带上线。

大部分具体可参照移动端： 配置 MSDK 环境。其中 msdk 默认开启了 HTTPDNS，MSDK_HTTPDNS_ENABLE 为 "1" 代表开启，反之可将其设置为 "0" 或者删掉改配置，业务此时需要配置微信服务商 Service ID： MSDK_HTTPDNS_SERVICE_ID，若不配置则默认不走 HTTPDNS，具体请参照：移动解析HttpDNS|微信开放文档。

如果 MSDK 目录被放置在 ${小游戏根目录}/unity-sdk 目录，则此处应填写："MSDK_PROJECT_PATH": "unity-sdk"，该路径相对于小游戏项目根目录，如果直接放置在项目目录，此处填写 "" 或删掉 MSDK_PROJECT_PATH 配置。

{
  "MSDK_DEBUG": "1",  // 是否开启日志，1 开启，0 关闭，上线时请关闭
  "MSDK_SDK_KEY": "itopsigkey",  // 与后台通讯的加密 key，必填
  "MSDK_URL": "https://dev.itop.qq.com",  // MSDK 后台服务域名，必填
  "MSDK_GAME_ID": "12",  // MSDK 用来标记游戏的唯一标识符，必填
  "MSDK_PROJECT_PATH": "unity-sdk",  // MSDK SDK 放置在工程中的位置
  "MSDK_HTTPDNS_ENABLE": "1",  // 是否开启 HTTPDNS
  "MSDK_HTTPDNS_SERVICE_ID": "wxa410372c837a5f26"  // 微信服务商 Service ID
}

1.3 Unity 接口

将 unity 接口导入工程中使用，替换同名文件。 注意：目前 C# 接口基于 MSDKPIX 5.42.100，MSDK 小游戏 unity 接口与移动端是统一的，参数使用可参照移动端。

二、原生 JS 接口说明

若选择 unity 引擎接口，可跳过该部分。 js 使用请参照如下 ts 结构。

2.1 数据结构

2.1.1 MSDKBaseRet

class MSDKBaseRet {
  public retCode: number;
  public retMsg: string;
  public thirdCode: number;
  public thirdMsg: string;
  public extraJson: string;
  public methodNameID: number;
}

2.1.2 MSDKLoginRet

class MSDKLoginRet extends MSDKBaseRet {
  public openID = '';
  public token = '';
  // Expiration
  public tokenExpire = -1;
  // Whether to log in for the first time, unknown -1, no 0, yes 1
  public firstLogin = -1;
  // Distribution channel for first registration
  public regChannelDis = '';
  public userName = '';
  public gender = 0;
  public birthdate = '';
  // Avatar link
  public pictureUrl = '';
  public pf = '';
  public pfKey = '';
  // Whether the logo needs real-name authentication
  public realNameAuth = false;
  public channelID = -1;
  public channel = '';
  // Additional channel information
  public channelInfo = '';
  // Confirmation code returned after binding failed
  public confirmCode = '';
  // Confirmation code expiration timestamp
  public confirmCodeExpireTime = 0;
  // Binding information (JSON data, array type)
  public bindList = '';
  public channelOpenID = '';
  // Health Anping Center Field
  public healthGameExt = '';
  public seqID = '';
}

2.2 初始化配置接口

该初始化接口用于初始化 MSDK MiniGameSDK，初始化成功后才可调用 MSDK 其他接口。

// 回调函数
export abstract class InitRetObserver {
  abstract onBaseRetResult(baseRet: MSDKBaseRet): void;
}

// 初始化类
export class MSDKInit {
  public static setInitRetObserver(initRetObserver: InitRetObserver): void {
  }
}

// js 回调设置
class MyInitObserver extends GameGlobal.MSDK.InitRetObserver {
    onBaseRetResult(ret) {
      // to do
    }
}

// 初始化调用
GameGlobal.MSDK.MSDKInit.setInitRetObserver(new MyInitObserver());

2.3 登录接口

// 登录登出回调
export abstract class LoginRetObserver {
  abstract onBaseRetResult(baseRet: MSDKBaseRet): void;
  abstract onLoginRetResult(loginRet: MSDKLoginRet): void;
}

// 登录函数
export class MSDKWrapperLogin {
  public static setLoginRetObserver(loginRetObserver: LoginRetObserver) {}
  public static login(channel: string, permissions = '', subChannel = '', extrajson = ''): void {}
}

// js 回调设置，这里 onBaseRetResult 是登出回调，onLoginRetResult 是登录回调
class MyLoginObserver extends GameGlobal.MSDK.LoginRetObserver {
    onBaseRetResult(baseRet) {
        // to do 
    }
    onLoginRetResult(loginRet) {
        // to do
    }
}
GameGlobal.MSDK.MSDKWrapperLogin.setLoginRetObserver(new MyLoginObserver());

// 登录，以 WeChat 为例
GameGlobal.MSDK.MSDKWrapperLogin.login("WeChat");

2.4 获取登录态接口

export class MSDKWrapperLogin {
    public static getLoginRet(): MSDKLoginRet {}
}

// js 调用登出
GameGlobal.MSDK.MSDKWrapperLogin.logout();

2.5 登出接口

export class MSDKWrapperLogin {
    public static logout(channel = '', subChannel = '', channelOnly = false): void {}
}

// js 调用
let loginRet = GameGlobal.MSDK.MSDKWrapperLogin.getLoginRet();

2.6 Report Init 接口

该接口初始化对应的上报渠道，初始化成功后可进行渠道事件上报。

export default class MSDKWrapperReport {
  public static init(channelArrayStr: string): boolean {}
}

// js 调用
let ret = GameGlobal.MSDK.MSDKWrapperReport.init("Beacon");

2.7 Report Event 接口

export default class MSDKWrapperReport {
  public static reportEvent(eventName: string, params: Map<string, string> | null, spChannel = '', isRealTime = true, extra = '') {}
}

// js 调用 Beacon 上报，上报结果的接入请参照后面 Beacon 接入流程说明
let params = new Map();
params.set("K1", "V1");
params.set("K2", "V2");
GameGlobal.MSDK.MSDKWrapperReport.reportEvent("Report_Event", params, "Beacon");

2.8 更新用户信息接口

该接口用于更新当前登录用户的头像和昵称信息，新增 methodID：MSDK_LOGIN_UPDATE_USERINFO = 144，业务可在 MSDKLogin.LoginBaseRetEvent 回调中依据 methodID 判断结果，返回成功后，需请求 MSDK 后台查询。

注意：MSDK 在用户调用 Login 时，也会判断是否有授权过用户信息，若用户已经授权了，会自动请求后台更新，并在登录回调中返回。

该接口支持 MSDK 内部自动获取，也支持业务自定义传入用户信息，严格按照 update_info（固定字段）、raw_data、signature（参照微信文档：wx.getUserInfo(Object object)|微信开放文档）字段结构，如下：

export class MSDKWrapperLogin {
    public static updateUserInfo(extrajson = ''): void {}
}

// js 调用
GameGlobal.MSDK.MSDKWrapperLogin.updateUserInfo();

三、Unity 接口说明

3.1 数据结构

3.1.1 MSDKBaseRet

public class MSDKBaseRet : JsonSerializable
{
        private int methodNameID;
        private int retCode;
        private string retMsg;
        private int thirdCode;
        private string thirdMsg;
        private string extraJson;
}

3.1.2 MSDKLoginRet

namespace GCloud.MSDK
{
    public class MSDKLoginRet : MSDKBaseRet
    {
        private string openID;
        private string token;
        private long tokenExpire;
        private int firstLogin;
        private string regChannelDis;
        private string userName;
        private int gender;
        private string birthdate;
        private string pictureUrl;
        private string pf;
        private string pfKey;
        private bool realNameAuth;
        private int channelID;
        private string channel;
        private string channelInfo;
        private string confirmCode;
        private long confirmCodeExpireTime;
        private string bindList;
    }
}

3.2 初始化配置接口

该初始化接口用于初始化 MSDK MiniGameSDK，初始化成功后才可调用 MSDK 其他接口。

namespace GCloud.MSDK
{
    public class MSDK
    {
        public static void Init();
    }
}

// 回调设置
  public void onInitResult(MSDKBaseRet result)
{
    ShowLogInNewLine(string.Format("onInitResult: {0}", Tools.Instance.GetRetString(result)));
}

// 添加回调
MSDK.InitRetEvent += onInitResult;
// 移除回调
MSDK.InitRetEvent -= onInitResult;

// 调用
MSDK.Init();

3.3 登录接口

public class MSDKLogin
{
    public static void Login(string channel, string permissions = "", string subChannel = "", string extraJson = "")
}

// 回调设置
public void OnLoginResult(MSDKLoginRet result)
{
  ShowLogInNewLine(string.Format("OnLoginResult: {0}", Tools.Instance.GetRetString(result)));
}

// 添加回调
MSDKLogin.LoginRetEvent += OnLoginResult;
// 移除回调
MSDKLogin.LoginRetEvent -= OnLoginResult;

// 调用 QQ 或 WeChat
MSDKLogin.Login("QQ");

3.4 获取登录态接口

public class MSDKLogin
{
    public static MSDKLoginRet GetLoginRet()
}

// 调用
MSDKLoginRet result = MSDKLogin.GetLoginRet();

3.5 登出接口

public class MSDKLogin
{
    public static void Logout(string channel = "", string subChannel = "", bool channelOnly = false)
}

// 回调设置
public void OnLoginBaseResult(MSDKBaseRet result)
{
  ShowLogInNewLine(string.Format("OnLoginBaseResult: {0}", Tools.Instance.GetRetString(result)));
}

// 添加回调
MSDKLogin.LoginBaseRetEvent += OnLoginBaseResult;
// 移除回调
MSDKLogin.LoginBaseRetEvent -= OnLoginBaseResult;

// 调用
MSDKLogin.Logout();

3.6 Report Init 接口

该接口初始化对应的上报渠道，初始化成功后可进行渠道事件上报。

public class MSDKReport
{
    public static bool Init (string channel)
}

// 调用 Beaacon 初始化
string channel = "Beacon";
bool ret = MSDKReport.Init(channel);
ShowLogInNewLine(string.Format("MSDKReport init {0} result: {1}", channel, ret));

3.7 Report Event 接口

public class MSDKReport
{
    public static void ReportEvent (string eventName, Dictionary<string, string> paramsDic,
                                    string spChannels="", bool isRealTime=true)
}

// 调用 Beacon 上报
Dictionary<string, string> paramsDic = new Dictionary<string, string>();
paramsDic.Add("k1", "v1");
paramsDic.Add("k2", "v2");
paramsDic.Add("k3", "v3");
MSDKReport.ReportEvent("Report_Event", paramsDic, "Beacon");

3.8 更新用户信息接口

注意：MSDK 在用户调用 Login 时，也会判断是否有授权过用户信息，若用户已经授权了，会自动请求后台更新，并在登录回调中返回。

该接口支持 MSDK 内部自动获取，也支持业务自定义传入用户信息，严格按照 update_info（固定字段）、raw_data、signature（参照微信文档：）wx.getUserlnfo(Object object) | 微信开放文档字段结构，如下：

public class MSDKLogin
{
    public static void UpdateUserInfo(string extraJson = "")
}

// 
string extra = "{\"update_info\":{\"raw_data\":\"{\\\"nickName\\\":\\\"ssrshhWX\\\",\\\"gender\\\":0,\\\"language\\\":\\\"zh_CN\\\",\\\"city\\\":\\\"\\\",\\\"province\\\":\\\"\\\",\\\"country\\\":\\\"\\\",\\\"avatarUrl\\\":\\\"https://thirdwx.qlogo.cn/mmopen/vi_32/.../132\\\"}\",\"signature\":\"8f3c484fa2608b99d0dcb2300ff24884183760e5\"}}";

// 调用，若不传入则 MSDK 内部自动获取
MSDKLogin.UpdateUserInfo(extra);

四、js 初始化说明

以放置在 unity-sdk 目录为例，业务需要在 game.js 中按顺序完成以下操作。

4.1 初始化 MSDK 接口（重要）

在 game.js 开始处引入 MSDKBridge.js 文件

import './unity-sdk/MSDK/MSDKBridge';

4.2 QQ 小游戏支持（可选）

MSDK 支持 QQ 小游戏插件化，此时自动会判断是 WeChat 或 QQ APP 环境并进行渠道登录。如不需要支持 QQ 小游戏可跳过该部分。业务如需支持 QQ 小游戏，请先阅读：【QQ小游戏迁移微小方案：for司内游戏】产运文档（1）在 game.json 中添加 QGame 微小迁移 SDK 配置，其中 version 为插件版本，provider 为插件ID，请参照【微信小游戏--QQ插件】技术文档；iOS 需开启高性能模式，请参照：高性能＋模式 | 微信开放文档

"plugins": {
    "qq-wxa-plugin": {
      "version": "latest", 
      "provider": "wxa804f88ab7500362"
    }
},
"iOSHighPerformance": true,
"iOSHighPerformance+": true,
ss

（2）在 game.js 中初始化 qq 小游戏插件，并挂载给 MSDK：

GameGlobal.MSDK.QQ = requirePlugin('qq-wxa-plugin');
GameGlobal.MSDK.QQ.initPlugin(wx);

4.3 TDM 插件化（可选）

业务如果接入 TDM 插件，可在 game.js 将其初始化并挂载给 MSDK，这样 MSDK 可实现内部 TDM 的登录、登出等上报。下列配置请改为业务自身的。其中，userId 在 MSDK 没有登录之前是获取不到的，可填写为 ""，不影响功能，具体参照 TDM 官网：http://docs.tdm.woa.com/docs/sdks/js-sdk.html#js-character

// TDM 初始化并挂载给 MSDK，以 tdm-wxmg 为例，放置在 unity-sdk/TDM 目录下
GameGlobal.MSDK.TDM = require('./unity-sdk/TDM/tdm-wxmg');
GameGlobal.MSDK.TDM.init({
    routeBaseUrl: routeBaseUrl, // 路由地址（必填）
    appId: appId,    // 业务ID（必填）    
    appVer: appVer,  // 业务版本号
    userId: userId,  // 用户ID（用户openid等可以标识用户的ID）
    channel: channel  // 应用渠道（如果不填写，默认从url中的ADTAG取值）
  }).then(() => {
    console.log("TDM init success");
  }).catch(errMessage => {
    console.log("TDM init fail: " + errMessage);
  });

4.4 Beacon 插件化（可选）

业务如果接入 Beacon 插件，可在 game.js 将其初始化并挂载给 MSDK，可选在 unity 接口 MSDKReport 或 js 接口 GameGlobal.MSDK.MSDKWrapperReport 进行 Beacon 数据上报。Beacon 从 @tencent/beacon-mp-sdk@4.4.1 版本支持小游戏，初始化流程请参照：https://iwiki.woa.com/p/490519715 。

// Beacon 初始化并挂载给 MSDK，示例采用 npm 引入
let BeaconAction = require('@tencent/beacon-mp-sdk');
GameGlobal.MSDK.Beacon = new BeaconAction({
  appkey: "appkey", //小程序appKey，从DataHub官网获取,必填
  versionCode: 'versionCode', //小程序版本号，选填
  channelID: 'channelID', //小程序渠道号，选填
  openid: 'openid', // 用户标示符号，选填
  unionid: 'unionid', // 用户唯一标示符号，选填
  delay: 2000, // 普通事件延迟上报时间(单位毫秒), 默认2000(2秒),选填
  onReportSuccess: success, // 上报成功回调，选填
  onReportFail: fail, // 上报失败回调，选填
});

// js 初始化, 与 unity MSDKReport.Init 只会有一次成功，重复的会提示已经初始化
GameGlobal.MSDK.MSDKWrapperReport.init("Beacon");
// js 直接调用上报，参数定义与 unity 接口一致
let params = new Map();
params.set("K1", "V1");
params.set("K2", "V2");
GameGlobal.MSDK.MSDKWrapperReport.reportEvent("Report_Event", params, "Beacon", true);

五、错误码

可参照 MSDK 产品概览• MSDK Developer Reference 登录模块。

MSDK MiniGameSDK

MSDK MiniGameSDK 接入指南

Release note:

一、工程配置

1.1 SDK 拷贝

1.2 修改 MSDKConfig.json 配置（重要）

1.3 Unity 接口

二、原生 JS 接口说明

2.1 数据结构

2.1.1 MSDKBaseRet

2.1.2 MSDKLoginRet

2.2 初始化配置接口

2.3 登录接口

2.4 获取登录态接口

2.5 登出接口

2.6 Report Init 接口

2.7 Report Event 接口

2.8 更新用户信息接口

三、Unity 接口说明

3.1 数据结构

3.1.1 MSDKBaseRet

3.1.2 MSDKLoginRet

3.2 初始化配置接口

3.3 登录接口

3.4 获取登录态接口

3.5 登出接口

3.6 Report Init 接口

3.7 Report Event 接口

3.8 更新用户信息接口

四、js 初始化说明

4.1 初始化 MSDK 接口（重要）

4.2 QQ 小游戏支持（可选）

4.3 TDM 插件化（可选）

4.4 Beacon 插件化（可选）

五、错误码

results matching ""

No results matching ""

MSDK MiniGameSDK 接入指南

Release note:

一、 工程配置

1.1 SDK 拷贝

1.2 修改 MSDKConfig.json 配置（重要）

1.3 Unity 接口

二、原生 JS 接口说明

2.1 数据结构

2.1.1 MSDKBaseRet

2.1.2 MSDKLoginRet

2.2 初始化配置接口

2.3 登录接口

2.4 获取登录态接口

2.5 登出接口

2.6 Report Init 接口

2.7 Report Event 接口

2.8 更新用户信息接口

三、Unity 接口说明

3.1 数据结构

3.1.1 MSDKBaseRet

3.1.2 MSDKLoginRet

3.2 初始化配置接口

3.3 登录接口

3.4 获取登录态接口

3.5 登出接口

3.6 Report Init 接口

3.7 Report Event 接口

3.8 更新用户信息接口

四、js 初始化说明

4.1 初始化 MSDK 接口（重要）

4.2 QQ 小游戏支持（可选）

4.3 TDM 插件化（可选）

4.4 Beacon 插件化（可选）

五、错误码

results matching ""

No results matching ""

一、工程配置