Skip to content

SDK 调用微信 API

初始化

调用Unity SDK前,需要在主入口进行SDK初始化,回调后再执行主逻辑。

csharp
WX.InitSDK((int code)=> {
// 你的主逻辑
});

支持范围

Unity SDKWXSDK的支持大体与官网 API 文档相同。

具体支持的 API 可以查看WX.cs文件,其中有详细注释说明。

更新机制

新版Unity SDK会在lib.wx.api.d.ts更新后及时更新。 若基础库更新后lib.wx.api.d.ts暂未更新,开发者可参考自定义SDK调用临时调用WXSDK。 以wx.shareAppMessageToGroup为例:

csharp
using WeChatWASM;

public class ShareAppMessageToGroupOption
{
    public string title;
    public string path;
    public string imageUrl;
}

// 合适位置调用
WX.CallJSFunction("wx", "shareAppMessageToGroup", new ShareAppMessageToGroupOption
{
    title = "群任务",
});

Unity SDK 特供API

此处列出lib.wx.api.d.ts中未列出,仅在Unity SDK中可用的API列表。

类别函数名备注
基础功能InitSDK初始化SDK
CanIUse判断API在当前环境是否可用
SetDevicePixelRatio设置设备像素比
CallJSFunction调用JS函数
CallJSFunctionWithReturn调用JS函数并获取返回值
字体GetWXFont获取微信字体
广告CreateFixedBottomMiddleBannerAd创建固定底部中间的bannerAd
社交组件CreateMiniGameChat创建社交组件
开放数据域ShowOpenData显示开放数据域Canvas
HideOpenData显示开放数据域Canvas
音频PreDownloadAudios预下载音频资源
云测试IsCloudTest是否小游戏云测试环境
隐私协议弹窗PrivacyAuthorizeResolve由于C#侧无法直接返回JS绑定函数,所以新增一个API专门用于在WX.OnNeedPrivacyAuthorization的回调内调用
本地缓存StorageSetIntSync同wx.setStorageSync
StorageGetIntSync同wx.getStorageSync
StorageSetStringSync同wx.setStorageSync
StorageSetFloatSync同wx.setStorageSync
StorageGetFloatSync同wx.getStorageSync
StorageDeleteAllSync同wx.clearStorageSync
StorageDeleteKeySync同wx.removeStorageSync
StorageHasKeySync判断本地缓存中是否包含该key
文件缓存清理CleanAllFileCache清理所有文件缓存
CleanFileCache清理文件缓存
RemoveFile删除文件
GetCachePath获取缓存路径
性能GetTotalMemorySize获取当前UnityHeap总内存(峰值)
GetTotalStackSize获取当前UnityHeap Stack大小
GetStaticMemorySize获取当前UnityHeap静态内存
GetDynamicMemorySize获取当前UnityHeap动态内存
GetUsedMemorySize获取已使用UnityHeap内存大小
GetUnAllocatedMemorySize获取未分配UnityHeap内存大小
LogUnityHeapMem打印UnityHeap内存
GetBundleNumberInMemory获取当前AssetBundle在JS内存中的数量
GetBundleNumberOnDisk获取当前AssetBundle在磁盘中不可清理的数量
GetBundleSizeInMemory获取当前AssetBundle在JS内存中的体积
GetBundleSizeOnDisk获取当前AssetBundle在磁盘中不可清理的体积
OpenProfileStats打开性能面板
ProfilingMemoryDumpProfilingMemory内存Dump
LogManagerWriteLog同LogManager.log
WriteWarn同LogManager.warn
LogManagerDebug同LogManager.debug
LogManagerInfo同LogManager.info
LogManagerLog同LogManager.log
LogManagerWarn同LogManager.warn
上报ReportUserBehaviorBranchAnalytics分支相关的UI组件相关事件的上报
UncaughtException异常上报
ReportGameSceneError上报游戏自定义场景的错误信息
插件配置SetDataCDN设置数据CDN
SetPreloadList设置预加载列表
启动剧情GetLaunchOperaHandler获取启动剧情交互句柄
其他ReportGameStart游戏开始运行时上报
HideLoadingPage隐藏加载页
PreloadConcurrent控制预载并发数
OnLaunchProgress获取启动loader的启动数据

暂未支持的WXAPI

暂未支持的WXAPI中有一部分接口需要在开放数据域调用,故暂无法支持。

主类别副类别函数名描述
基础分包加载wx.loadSubpackage触发分包加载
转发wx.checkHandoffEnabled检查是否可以进行接力
wx.startHandoff开始进行接力
界面窗口wx.setWindowSize设置窗口大小
网络WebSocketwx.sendSocketMessage通过 WebSocket 连接发送数据
wx.onSocketOpen监听 WebSocket 连接打开事件
wx.onSocketMessage监听 WebSocket 接收到服务器的消息事件
wx.onSocketError监听 WebSocket 错误事件
wx.onSocketClose监听 WebSocket 连接关闭事件
wx.closeSocket关闭 WebSocket 连接
数据缓存wx.getStorage异步获取本地缓存
wx.setStorage异步存储本地缓存
wx.setStorageSync同步存储本地缓存
wx.getStorageSync同步获取本地缓存
wx.clearStorage异步清理本地缓存
wx.clearStorageSync同步清理本地缓存
wx.createBufferURL创建Buffer URL
渲染图片wx.createImage创建图片对象
开放接口开放数据wx.getFriendCloudStorage获取同玩好友托管数据
wx.getGroupCloudStorage获取群同玩成员游戏数据
wx.getGroupInfo获取群信息
wx.getPotentialFriendList获取可能对游戏感兴趣的未注册的好友名单
wx.getUserCloudStorage获取当前用户托管数据
wx.getUserCloudStorageKeys获取当前用户托管数据键值
wx.modifyFriendInteractiveStorage修改好友的互动型托管数据
wx.shareMessageToFriend给指定的好友分享游戏信息
工具wx.encode将字符串编码成ArrayBuffer
wx.decode将ArrayBuffer解码成字符串

调用方法

Unity 版本的 API 大体与官网 API 文档的 JS 版本 API 类似,使用时可以参考。

如 JS 版的 banner 广告的调用如下:

js
var bannerAd = wx.createBannerAd({
    adUnitId: "xxxx",
    adIntervals: 30,
    style: {
        left: 0,
        top: 0,
        width: 600,
        height: 200,
    },
});
bannerAd.onLoad(() => {
    bannerAd.show();
});
bannerAd.onError((res) => {
    console.log(res);
});

而对于 Unity 版的调用如下:

csharp
var bannerAd = WX.CreateBannerAd(new WXCreateBannerAdParam()
{
    adUnitId = "xxxx",
    adIntervals = 30,
    style = new Style()
    {
        left = 0,
        top = 0,
        width = 600,
        height = 200
    }
});
bannerAd.OnLoad(()=> {
    bannerAd.Show();
});
bannerAd.OnError((WXADErrorResponse res)=>
{
    Debug.Log(res.errCode);
});

大体是将 JS 版中的wx替换为 Unity 版的WX,然后对应方法名首字母由小写改为大写,如createBannerAd就变为CreateBannerAd

基础库

在 Unity 中兼容低版本基础库

使用WX.CanIUse可以判断当前版本是否支持该 API(仅支持 wx),例如想要判断当前环境WX.ReportScene是否可用,可以用WX.CanIUse("ReportScene")来判断

开发建议

API 示例

使用示例我们会逐渐补充到Demo, 其中 API 项目为常见使用范例,请优先查阅用法。

联调效率

如果开发者有简单的 JS 代码经验,建议先以 JS 方式直接修改 minigame 的 JS 代码进行调试,完成之后再使用 C# SDK 修改 Unity 工程:

  1. 只保留 game.js 前面 import 部分,其余删除,即不运行游戏逻辑。
  2. 增加以下代码:
js
const gl = GameGlobal.canvas.getContext("webgl");
gl.clear(gl.COLOR_BUFFER_BIT);
  1. 使用 JS 编写需要调试的 API

注意事项

  1. 广告接口是否需要上线后才能调试
  • 是的,需要上线并累计 UV>1000 才可以开通广告主

Released under the MIT License.