微信小游戏H5 SDK 接入说明

本文档将介绍 小游戏SDK 的接入流程以及相关接口的使用方法。

SDK 提供了以下接口：

初始化接口 Init
登录接口 Login
设置角色接口 SetRoleInfo
支付接口 Pay
分享接口 Share
日志上报接口 Log
获取平台ID GetServiceId
获取发行区域 GetLocaleId
获取客户端IP GetClientIP
获取ServiceCode GetServiceCode
拉起客服 CustomerService
打开公告 OpenNotice
打开调查问卷 OpenQuestionnaire
被动分享 PassiveShare
礼包码兑换 GiftCodeExchange
打开协议 OpenPrivacy
获取客户端平台 GetDevicePlatform

接入流程

一、下载 SDK

微信小游戏:

安装微信Unity工具包

安装微信Unity工具包后,在菜单栏中会多出‘微信小游戏’菜单,如需转化小游戏

1.请添加平台WebGL
2.准备微信appID
3.提示配置node的bin目录, 配置路径: Assets/WX-WASM-SDK/Editor/MiniGameConfig.asset， 在文件中找到配置项CustomNodePath 指定本机node的bin目录
例: CustomNodePath: /Users/wangliang/.nvm/versions/node/v14.19.1/bin

注意：使用稳定且长期支持的node版本

安装平台小游戏SDK

1.安装MINIGAME SDK Unity工具包 MINIGAME_SDK.unitypackage

MINIGAME_SDK.unitypackage 目录结构

Assets
    MINIGAME_SDK
        Models.cs
        SDK.cs
        SDKBase.cs
        SDKBridgeManager.cs
        SDKManager.cs
        Plugins
            SDK_BRIDGE_CALL_JS.jslib
    WX-WASM-SDK
        wechat-default
            minigame-sdk
                index.js

2.修改微信SDK文件 WX-WASM-SDK/wechat-default/game.js 添加内容如下

    // 在文件头部添加
    import './minigame-sdk/index';
    // ...

3.复制GSC配置文件config.json(该文件由技术支持提供)到打包后的minigame-sdk目录中或者放到源工程的WX-WASM-SDK/wechat-default/minigame-sdk目录中

4.因微信小游戏在未发布前无法获取到微信小游戏版本, 现支持研发在开发/体验阶段手动配置小游戏版本, 配置方法如下(如不进行版本配置默认小游戏版本为 0.0.0)

在打包后的minigame-sdk目录下添加gameversion.json 文件内容如下(可选配置)

{
  "minigameVersion": "2.0.0"
}

Patch更新说明: 解压后将index.js文件覆盖到游戏打包后的minigame-sdk目录下来完成Patch更新, 可节省Unity打包时间. 需要注意的是每次Unity打包后还需要进行替换

二、接口API

初始化 SDK

在应用程序中，调用Init接口初始化 SDK。

using MINIGAME_SDK;
SDK.Init(new InitOption() {
  /// 游戏版本号
  version = "1.0.0",
  // 游戏资源版本号
  resVersion = '1.0.0',
  share = new Share() {
      title = '分享标题',
      imageUrl = '分享图片URL',
      imageUrlId = '分享图片在微信后台的编码'
  },
  success = () => {
    // 初始化成功
  },
  fail = (error) => {
    // 初始化失败
  }
});

Share 说明

登录

在需要登录的地方，调用Login接口以获取用户登录状态。注意调用之前需要初始化成功。

using MINIGAME_SDK;
SDK.Login(new LoginOption() {
  success = (user) => {
    // ...
  },
  fail = (error) => {
    // ...
  }
});

User 说明

支付

在需要支付的地方，调用Pay接口以发起支付请求。注意调用之前需要初始化、登录、角色 注册/登录 信息上报。

using MINIGAME_SDK;
SDK.Pay(new PayOption() {
  // 商品ID
  goodsId = "goodsId",
  // 商品名称
  goodsName = "goodsName",
  // 商品描述
  goodsDesc = "goodsDesc",
  // 商品价格，单位为分
  price = "goodsPrice",
  // 购买的虚拟货币名称，比如 钻石，金币，宝石 等
  currency = "钻石",
  // 游戏自定义数据，支付成功后，计费中心会将此字段数据回传给游戏服务器（最
大支持150字符）
  extension = "extension",
  // 商品数量
  quantity = 2,
  // 货币类型(1人民币2美元3日元4港币5英镑6新加坡币7越南盾8台币9韩元10泰铢)
  currencyType = "1",
  success: (order) => {
    // ...
  },
  fail = (error) => {
    // ...
  }
});

Order 说明

分享

在需要分享的地方，调用Share接口以发起分享请求。注意调用之前需要初始化成功。

using MINIGAME_SDK;
SDK.Share(new ShareOption() {
  title = "分享标题",
  imageUrl = "https://inews.gtimg.com/newsapp_bt/0/12171811596_909/0",
  success = () => {
    // ...
  }
});

设置角色

在角色注册、角色登录、角色信息变更、角色注销时, 调用SetRoleInfo接口上报角色信息。注意调用之前需要初始化、登录成功。

using MINIGAME_SDK;
SDK.SetRoleInfo(new SetRoleInfoOption() {
  sendtype = RoleSendtype.register,
  serverName = "serverName",
  serverId = "serverId",
  roleName = "roleName",
  roleId = "roleId",
  roleLevel = "1",
  vipLevel = "v2",
  // 角色创建时间（服务器采集）时间类型：long 精度：秒 （即10位数)
  roleCreateTime = 1680598796,
  // 角色等级变化时间（服务器采集）时间类型：long 精度：秒 （即10位数)
  roleLevelMTime = 1680598796,
  success = () => {
  }
});

RoleSendtype 说明: RoleSendtype.register、RoleSendtype.login、RoleSendtype.change、RoleSendtype.logout

注: 当sendtype为RoleSendtype.logout时 其它属性均可不传

日志上报

在需要上报日志的地方，调用Log接口以上报日志。注意调用之前需要初始化、登录成功、设置角色成功。

using MINIGAME_SDK;
SDK.Log(new MINIGAME_SDK.LogOption() {
  eventId = "fight.mineer",
  eventName = "战斗.狗头人矿工",
  classifiedId = "Dungeons",
  classifiedName = "副本",
  detail = "begin"
 });

获取平台ID

在需要获取平台ID的地方，调用GetServiceId接口以获取。(游戏联运渠道ID,游戏可根据此ID区分各发行渠道)。注意调用之前需要初始化成功。

using MINIGAME_SDK;
SDK.GetServiceId(new Callbacks<string>() {
  success = (serviceId) => {
     // ...
  }
});

获取发行区域获取发行区域

在需要获取发行区域的地方，调用GetLocaleId接口以获取。注意调用之前需要初始化成功。

using MINIGAME_SDK;
SDK.GetLocaleId(new Callbacks<string>() {
  success = (localeId) => {
     // ...
  }
});

获取客户端IP

在需要获取客户端IP的地方，调用GetClientIP接口以获取。

using MINIGAME_SDK;
SDK.GetClientIP(new Callbacks<string>() {
  success = (ip) => {
     // ...
  }
});

获取ServiceCode

在需要获取ServiceCode的地方，调用GetServiceCode接口以获取。注意调用之前需要初始化、登录成功。获取服务器端 发送日志使用的ServiceCode 提供给BI日志用。

using MINIGAME_SDK;
SDK.GetServiceCode(new Callbacks<string>() {
  success = (serviceCode) => {
     // ...
  }
});

客服

在需要拉起客服的地方，调用CustomerServer接口以发起拉起客服请求。注意调用之前需要初始化成功。

using MINIGAME_SDK;
SDK.CustomerServer(new Callbacks() {
  success = () => {
     // ...
  }
});

打开公告

在需要打开公告的地方, 调用OpenNotice接口以发起打开公告请求.

using MINIGAME_SDK;
SDK.OpenNotice(new Callbacks() {
  success = () => {
     /// 成功打开公告
  }
});

打开调查问卷

在需要打开调查问卷的地方, 调用OpenQuestionnaire接口以发起打开调查问卷请求.

using MINIGAME_SDK;
var customParams = new Dictionary
customParams.Add("key1", "value1");
customParams.Add("key2", "value2");
SDK.OpenQuestionnaire(new OpenQuestionnaireOption() {
  questionId = "745",
  customParams = customParams,
  success = () => {
     /// 成功打开问卷
  }
});

被动分享

调用PassiveShare接口来监听并修改用户点击平台提供的分享内容, 每一次的接口调用将取消上一次的监听和修改

using MINIGAME_SDK;
SDK.PassiveShare((callback) => {
    // 在此可监听用户点击了平台提供的分享 通过shareType可以区分是好友分享 还
是朋友圈分享
    Debug.Log("分享类型" + callback.shareType);
    callback.SetShare(new ShareOption() {
        title = "转发标题"
    });
});

参数类型: Action

PassiveShareCallback 说明

礼包码兑换

调用GiftCodeExchange接口来进行礼包码兑换

using MINIGAME_SDK;
SDK.GiftCodeExchange(new ShareOption() {
    code = "xxxx",
    url = "xxxx",
    extendParams = "xxx",
    success = (result) => {
    }
});

GiftCodeExchangeResult 说明

打开协议

调用OpenPrivacy接口来打开协议

using MINIGAME_SDK;
SDK.OpenPrivacy(new Callbacks() {
    success = () => {
    }
});

获取客户端平台

调用GetDevicePlatform接口来获取客户端平台

using MINIGAME_SDK;
SDK.GetDevicePlatform(new Callbacks<string>() {
    success = (platform) => {
        // ios android mac windows devtools
    }
});

三、Error说明

1.code错误码规则说明:

1. 固定为4位数字

2. 左数2位数字表示接口类型(11: 初始化, 12: 登录, 13: 支付, 14: 分享, 15: 日志上报, 16: 角色上报, 17:获取平台ID, 18:获取区域ID, 19:获取IP, 20: 获取ServiceCode, 21: 客服)

3. 左数第3位数字表示 错误来源(0: SDK, 1: 服务端, 2: 平台(微信), 其它预留)

4. 最后一位预留

2.状态码：

四、Debug

在开发阶段可以开启debug模式, 开启方法在配置文件config.json中添加 “debug”: true

{
    "debug": true
}

开启后每次的接口调用都会以确认框的形式打印接口返回的成功信息或失败信息, 方便调试接口

• 注: 发布到线上时需要把debug改为false或去掉debug属性