微信小游戏SDK-Unity(C#)

文章目录

文档修订记录
接入准备
接入须知
接口
回调
导出测试
FAQ

文档修订记录

文档版本	文档更新日期	文档更新内容
3.3.81	2024.12.26	1.登录回调新增是否首次登录标识
3.3.64	2024.09.11	1.新增「打开客服会话」方法
3.3.63	2024.08.27	1.「初始化回调」新增"增渠道模板标识"等配置参数；2.新增「配置参数获取」方法
3.3.62	2024.08.14	1.「接入准备」新增安装WXSDK指引；2.新增「问卷」、「消息订阅」、「游戏圈」、「广告」、「转发」等微信小游戏功能集成
3.3.58	2024.06.19	新增初始化回调

接入准备

1.下载对接资源：点我下载

2.将文件NebulaWeixin.unitypackage导入到您的Unity工程的Assets文件夹下。

3.将对接资源中的'wechat-default'目录下的'nebula-unity-sdk.js'拷贝到Unity工程的'Assets/WX-WASM-SDK-V2/Runtime/wechat-default'目录下。

4.打开Untiy工程中的'Assets/WX-WASM-SDK-V2/Runtime/wechat-default/game.js'文件，在文件中添加如下代码

import './nebula-unity-sdk'

5.从星云开放平台下载 'fy-config.json' ，拷贝到Untiy工程的'Assets/Resources'目录下。下载路径：星云开放平台->对接中心->渠道配置->抖音小游戏渠道->操作->下载配置文件

6.安装WXSDK

打开 Unity工程 -> Window 菜单栏 -> Package Manager -> 左上方 “+” -> Add package from git URL
添加地址：https://gitee.com/wechat-minigame/minigame-tuanjie-transform-sdk.git
点击Add完成WXSDK导入
参考文档：微信SDK安装
对接代码中引入命名空间：using WeChatWASM;

接入须知

1.微信小游戏SDK-Unity(C#)SDK下载：点击进入

2.微信小游戏支撑服务介绍：点击进入

3.微信小游戏接入配置指引：点击进入

4.微信小游戏服务端文档请查阅：点击进入

接口

必接接口：游戏必须要接入
选接接口：按照游戏发行需求来接入
回调：某些接口有相应的回调游戏需要进行处理，具体请查看本文档的「回调」章节
案例：更详细案例可以参考对接资源中的范例'Script/Menu.cs'

初始化`(必接)`

1.方法

public void Init(string gameVersion)

2.说明

作用：用来加载SDK的初始化配置
调用时机：游戏需要在刚启动游戏的时候调用
回调说明：初始化完成后会回调初始化回调，并返回星云配置参数，包括星云开放平台AppID、渠道ID等

3.调用范例

Nebula.NebulaSDKBridge.Instance.Init("1.0.0");

4.参数说明

参数	类型	说明	是否必传
gameVersion	string	游戏版本号	是

5.回调方法

// 初始化回调
Nebula.NebulaSDKBridgeCallback.InitCallback

登录`(必接)`

1.方法

public void Login()

2.说明

作用：获取用户登录信息
调用时机：初始化完成后，玩家需要登录时调用
登录流程：点我查看
回调说明：登录后会回调LoginCallback，返回json格式的用户信息，游戏通过解析json获取相应的用户信息，包括星云nbOpenId和微信OpenId等

3.调用范例

Nebula.NebulaSDKBridge.Instance.Login();

4.参数说明
无

5.回调方法

// 登录回调
Nebula.NebulaSDKBridgeCallback.LoginCallback

支付`(必接)`

1.方法

public void Pay(int goodsPrice, string tradeNo, string goodsId, string goodsName, string playerId, string playerName, string playerLevel, string vipLevel, string serverId, string zoneId, int sandbox, string notifyUrl, string notifyExt)

2.说明

作用：拉起支付界面
调用时机：玩家进行商品购买时调用
支付流程：点我查看
服务端回调：需配置游戏服务端的支付回调地址，支付完成后会通过此地址回调支付结果，配置路径：星云开放平台->对接中心->SDK对接->SDK列表->基础接入参数->游戏支付回调地址
注意事项：客户端的支付回调不能作为支付成功的依据，不能在此处发放道具，客户端的支付回调只可以用来控制游戏界面显示，例如loading框的关闭、遮罩层的关闭。判断支付是否成功要根据服务端的支付回调。具体的服务端回调请看服务端接入文档

3.调用范例

Nebula.NebulaSDKBridge.Instance.Pay(100, tradeNo, "1", "100钻石", "1", "1号玩家", "1", "1", "1", "1", "1", 1, "http://example.com", "example");

4.参数说明

参数	类型	默认值	说明	必传
goodsPrice	int	-	商品价格，单位：分，对应服务端支付回调的 total_amount 参数	是
tradeNo	string	-	游戏订单号，由游戏生成并管理。服务端支付回调会回传，游戏需进行唯一性校验，防止重复下发商品给玩家，50个字符内。对应服务端支付回调的out_trade_no参数	是
goodsId	string	-	商品 ID,对应服务端支付回调的 goods_id 参数	是
goodsName	string	-	商品名称	是
playerId	string	-	角色 ID，对应服务端支付回调的 player_id 参数	是
playerName	string	-	玩家名称	是
playerLevel	string	-	玩家等级	是
vipLevel	string	0	VIP 等级	否
serverId	string	-	服务器 ID,对应服务端支付回调的 server_id 参数	是
zoneId	string	1	分区 ID，对应小游戏平台的支付分区	否
sandbox	int	0	沙箱支付，0=正式支付、1=沙箱支付，微信直购商品未发布必须使用 1	否
notifyUrl	string	-	1.通过该值能在客户端动态传递服务端支付回调地址；2.若您在客户端传递了该地址，则支付完成后会通过此地址回调支付结果；3.若您同时也在星云后台配置了支付回调地址，会优先回调客户端传递的地址；4.需要先配置支付回调可信域名，请前往"星云后台->对接中心->回调配置->支付回调可信域名"进行配置，否则无法回调成功；5.若您在客户端传递了该地址，在游戏包体发布之前，建议您仔细检查该参数是否配置正确，以防止包体发布后支付出现问题	否
notifyExt	string	-	额外参数，游戏的透传参数可通过此参数传递，支付完成后平台服务端会回调此参数给游戏服务端。对应服务端支付回调的notify_ext参数	否

5.回调方法

// 支付回调
Nebula.NebulaSDKBridgeCallback.PayCallback

调试模式`(选接)`

1.说明

作用：可以进行对接问题排查和检测功能是否完整接入
查看调试结果：打开调试界面进行调试结果查看，调试界面入口：星云开放平台 → 游戏中心 → 选择游戏 → 对接中心 → SDK 对接 → SDK 调试 → H5 → 微信小游戏SDK-Unity(C#) → SDK 调试
注意事项：上线后请务必将调试状态关闭！！！

file

2.调用范例

Nebula.NebulaSDKBridge.Instance.NebulaDebug(false);

3.参数说明

参数	类型	默认值	说明	必传
isDebug	bool	false	true:开启调试/false:关闭调试	是

问卷`(选接)`

1.方法

/// <summary>
/// 创建问卷
/// </summary>
/// <param name="serverId">游戏服ID</param>
/// <param name="surveyId">问卷ID，要传星云开放平台配置的问卷ID</param>
public void CreateSurvey(string serverId, int surveyId)

/// <summary>
/// 显示问卷
/// </summary>
/// <param name="surveyId">问卷ID，要传星云开放平台配置的问卷ID</param>
public void ShowSurvey(int surveyId)

2.说明

作用：通过传入星云开放平台的问卷ID，来确定问卷是否有效，并打开相应的问卷界面
配置问卷：需先在腾讯问卷创建问卷，获取问卷链接，然后在星云开放平台配置好问卷链接、标题等，配置路径：星云开放平台->GM系统->微信小游戏运营工具->腾讯问卷
创建问卷：在打开问卷之前，要先调用CreateSurvey方法，CreateSurveyCallback回调会返回问卷是否有效，游戏根据此结果决定是否展示问卷入口
展示问卷：调用ShowSurvey方法，ShowSurveyCallback回调会返回问卷是否填写完成，游戏根据此结果决定是否下发奖励
参数说明：surveyId获取路径：星云开放平台->GM系统->微信小游戏运营工具->腾讯问卷->问卷ID

3.调用范例

创建问卷

Nebula.NebulaSDKBridge.Instance.CreateSurvey("1", 1);

显示问卷

Nebula.NebulaSDKBridge.Instance.ShowSurvey(1);

4.回调方法

创建问卷回调

Nebula.NebulaSDKBridgeCallback.CreateSurveyCallback

显示问卷回调

Nebula.NebulaSDKBridgeCallback.ShowSurveyCallback

订阅消息`(选接)`

1.方法

/// <summary>
/// 订阅消息
/// 参考文档：https://developers.weixin.qq.com/minigame/dev/api/open-api/subscribe-message/wx.requestSubscribeMessage.html
/// </summary>
/// <param name="tmplIds">
/// 订阅消息模版ID，可以一次性传3个模版ID，以字符串数组的形式传入
/// 订阅消息模版ID获取途径：微信公众平台->功能->订阅消息->模版ID
/// </param>
public void RequestSubscribeMessage(string[] tmplIds)

2.说明

作用：通过传入微信公众平台维护的模版ID，来拉起相应订阅消息
配置订阅消息：需先到微信公众平台，配置好订阅消息模版，配置路径：微信公众平台->功能->订阅消息
参数说明：tmplIds最多可以一次性传3个模版ID，可以一次性订阅3个订阅消息，获取路径：微信公众平台->功能->订阅消息->模板ID
注意事项：由于微信的规定，一定要在按钮按下时触发订阅消息，否则无法正常拉起，所以游戏应监听按钮的PointerDown事件，在PointerDown事件回调中调用此方法；
回调：订阅成功后会回调SubscribeMessageCallback，返回各个模版ID的订阅状态，比如"接受"、"拒绝"等
推送订阅消息：完成订阅后，游戏服务端应在合适的时机调用星云的订阅推送接口，玩家微信客户端将收到相应的订阅消息，因为此方法接受的是一次性订阅消息模版，所以玩家每订阅一次，游戏只能推送一次消息给到玩家，详情请查看微信小游戏订阅消息服务端文档
更多介绍：请参考微信小游戏订阅消息介绍文档
案例介绍：以游戏签到活动为例，游戏使用签到按钮，让玩家拉起订阅消息弹窗，玩家接受订阅后，游戏服务端可以在第二天发起订阅消息推送，从而让玩家收到一条订阅消息

3.调用范例

设置按钮的PointerDown事件

// 游戏获取按钮对象（参考代码，游戏根据自身情况进行调整）
Button subscribeMessageButton = FYUIHelper.FindChildGameObject<Button>(this.gameObject, "SubscribeMessageButton"); 
EventTrigger.Entry entry = new EventTrigger.Entry();
entry.eventID = EventTriggerType.PointerDown;
entry.callback.AddListener(SubscribeMessageAction);
subscribeMessageButton.gameObject.AddComponent<EventTrigger>();
subscribeMessageButton.gameObject.GetComponent<EventTrigger>().triggers.Add(entry);

按钮的PointerDown事件回调

public void SubscribeMessageAction(BaseEventData eventData)
{
    string[] tmplIds = new string[] {
        "xxx1",
        "xxx2",
        "xxx3"
    };
    Nebula.NebulaSDKBridge.Instance.RequestSubscribeMessage(tmplIds);
}

4.回调方法

订阅消息回调

Nebula.NebulaSDKBridgeCallback.SubscribeMessageCallback

游戏圈`(选接)`

1.方法

/// <summary>
/// 创建游戏圈按钮
/// 参考文档：https://developers.weixin.qq.com/minigame/dev/api/open-api/game-club/wx.createGameClubButton.html
/// </summary>
/// <param name="param">微信游戏圈按钮参数对象</param>
/// <returns>微信游戏圈按钮对象</returns>
public WXGameClubButton CreateGameClubButton(WXCreateGameClubButtonParam param)

2.说明

作用：创建游戏圈按钮并显示，玩家可以点击游戏圈按钮打开游戏圈
参数说明：调用该方法需传入微信的参数对象WXCreateGameClubButtonParam，在这个对象中可以自定义按钮的样式
返回值说明：该方法返回的是微信游戏圈按钮对象WXGameClubButton，通过这个对象可以控制游戏圈按钮的一些行为
更多介绍：请参考微信游戏圈介绍文档以及微信游戏圈接口文档

3.调用范例

创建游戏圈按钮，并对游戏圈按钮点击进行监听

var param = new WXCreateGameClubButtonParam();
param.icon = GameClubButtonIcon.green;
param.type = GameClubButtonType.image;
param.style = new GameClubButtonStyle();
param.style.left = 10;
param.style.top = 76;
param.style.width = 40;
param.style.height = 40;

var button = Nebula.NebulaSDKBridge.Instance.CreateGameClubButton(param);
button.Show();
button.OnTap(() =>
{
    Debug.Log("###GameClubButton OnTap");
});

4.回调方法

无

激励视频广告`(选接)`

1.方法

/// <summary>
/// 创建激励视频广告组件
/// 参考文档：https://developers.weixin.qq.com/minigame/dev/api/ad/wx.createRewardedVideoAd.html
/// </summary>
/// <param name="param">微信激励视频广告参数对象</param>
/// <returns>微信激励视频广告组件对象</returns>
public WXRewardedVideoAd CreateRewardedVideoAd(WXCreateRewardedVideoAdParam param)

2.说明

作用：创建微信小游戏的激励视频广告组件对象，通过这个对象展示激励视频广告
配置激励视频广告：微信小游戏后台->流量主->广告管理->激励广告->新建广告位
参数说明：调用该方法需传入微信的参数对象WXCreateRewardedVideoAdParam，在这个对象中可以设置激励视频广告的参数，比如广告ID；adUnitId（广告ID）获取路径：微信公众平台->流量主->广告管理->激励广告->广告位ID
返回值说明：该方法返回的是微信对象WXRewardedVideoAd，通过这个对象可以控制激励视频广告的一些行为
监听事件说明：OnLoad监听加载完成，OnError监听加载失败，OnClose监听广告观看是否完成，游戏可根据isEnded参数来判断是否下发奖励
注意事项：（1）不要直接在OnLoad中调用Show，否则会不断触发Show，导致无法关闭广告，因为该组件每次关闭广告后会自动加载，并触发一次OnLoad；（2）游戏可以自定义initRewardedVideoAd属性，标识是否首次创建广告，如果是首次创建，则在OnLoad中调用Show，如果非首次则在监听事件外部调用Show；（3）游戏可以自定义loadRewardedVideoAd属性，标识广告是否已加载，应确保广告已加载才能调用Show
更多介绍：请参考微信激励视频广告介绍文档以及微信激励视频广告接口文档

3.调用范例

游戏定义属性标识是否首次创建广告、标识广告是否已加载

private bool initRewardedVideoAd;
private bool loadRewardedVideoAd;

创建激励视频广告、设置监听事件并展示

var param = new WXCreateRewardedVideoAdParam();
param.adUnitId = "xxx";
var rewardedVideoAd = Nebula.NebulaSDKBridge.Instance.CreateRewardedVideoAd(param);
rewardedVideoAd.OnLoad((WXADLoadResponse response) => {
    // 广告已加载
    Debug.Log($"###ShowRewardedVideoAd OnLoad");
    // 标识广告已加载
    this.loadRewardedVideoAd = true;

    // 首次创建等加载完成后可以调用Show展示广告
    // 不要直接在OnLoad中调用Show，否则会不断触发Show，导致无法关闭广告
    if (!this.initRewardedVideoAd)
    {
        rewardedVideoAd?.Show();
        this.initRewardedVideoAd = true;
        // 首次展示完广告后将已加载标识置为否
        this.loadRewardedVideoAd = false;
    }
});
rewardedVideoAd.OnError((WXADErrorResponse error) => {
    // 加载错误
    Debug.Log($"###ShowRewardedVideoAd OnError>>errCode:{error.errCode}");
    // 标识广告未加载
    this.loadRewardedVideoAd = false;
});
rewardedVideoAd.OnClose((WXRewardedVideoAdOnCloseResponse response) => {
    Debug.Log($"###ShowRewardedVideoAd OnClose>>isEnded:{response.isEnded}");
    if (response != null && response.isEnded)
    {
        // 广告观看完成
    }
    else
    {
        // 未看完广告
    }
});
// 非首次创建，并且广告已经加载才能展示
if (this.initRewardedVideoAd && this.loadRewardedVideoAd)
{
    rewardedVideoAd.Show();
}

4.回调方法
无

Banner广告`(选接)`

1.方法

/// <summary>
/// 创建Banner广告组件对象
/// 参考文档：https://developers.weixin.qq.com/minigame/dev/api/ad/wx.createBannerAd.html
/// </summary>
/// <param name="param">微信banner广告参数对象</param>
/// <returns>微信banner广告组件对象</returns>
public WXBannerAd CreateBannerAd(WXCreateBannerAdParam param)

2.说明

作用：创建Banner广告组件并显示，通过这个对象展示Banner广告
配置Banner广告：微信小游戏后台->流量主->广告管理->Banner广告->新建广告位
参数说明：调用该方法需传入微信的参数对象WXCreateBannerAdParam，在这个对象中可以设置Banner广告的参数，比如广告ID、广告样式等；adUnitId（广告ID）获取路径：微信公众平台->流量主->广告管理->Banner广告->广告位ID
返回值说明：该方法返回的是微信游戏圈按钮对象WXBannerAd，通过这个对象可以控制Banner广告的一些行为
监听事件说明：OnLoad监听加载完成，OnError监听加载失败，OnResize监听广告尺寸变化
广告样式说明：Banner广告宽度最小300，小于 300 时，会取作 300；高度不用设置，会根据比例自动缩放；如果要根据Banner广告长宽算出Banner放置的位置，则需要在OnResize监听中获取到Banner最终真实的长宽，从而计算出left和top坐标
性能优化说明：如果离开Banner广告所展示的游戏页面，要调用Destroy方法销毁banner广告，释放内存资源
更多介绍：请参考微信Banner广告介绍文档以及微信Banner广告接口文档

3.调用范例

定义Banner广告属性

private WXBannerAd bannerAd;

创建Banner广告，设置宽度为300，并水平居中垂直靠下显示

var info = WX.GetWindowInfo();
var screenWidth = info.screenWidth;
var screenHeight = info.screenHeight;
Debug.Log($"###screenWidth:{screenWidth}>>screenHeight:{screenHeight}");

var param = new WXCreateBannerAdParam();
param.adUnitId = adUnitId;
param.adIntervals = 30;
// banner广告宽度最小300，小于 300 时，会取作 300
// banner广告高度不用设置，会自动缩放
param.style.width = 300;

this.bannerAd = Nebula.NebulaSDKBridge.Instance.CreateBannerAd(param);
this.bannerAd.OnLoad((WXADLoadResponse response) => {
    Debug.Log($"###BannerAd OnLoad>>rewardValue:{response.rewardValue}>>shareValue:{response.shareValue}");
});
this.bannerAd.OnError((WXADErrorResponse error) => {
    Debug.Log($"###BannerAd OnError>>errCode:{error.errCode}");
});
this.bannerAd.OnResize((WXADResizeResponse res)=> {
    Debug.Log($"###BannerAd OnResize>>res.width:{res.width}>>res.height:{res.height}" );
    // 居中靠下显示
    this.bannerAd.style.left = (int)((screenWidth - res.width) / 2);
    this.bannerAd.style.top = (int)(screenHeight - res.height);
    Debug.Log($"###left:{this.bannerAd.style.left}>>top:{this.bannerAd.style.top}>>width:{this.bannerAd.style.width}>>height:{this.bannerAd.style.height}");
});

显示Banner广告

this.bannerAd?.Show();

隐藏Banner广告

this.bannerAd?.Hide();

销毁Banner广告

this.bannerAd?.Destroy();

4.回调方法
无

插屏广告`(选接)`

1.方法

/// <summary>
/// 创建插屏广告组件
/// 参考文档：https://developers.weixin.qq.com/minigame/dev/api/ad/wx.createInterstitialAd.html
/// </summary>
/// <param name="param">微信插屏广告参数对象</param>
/// <returns>微信插屏广告组件对象</returns>
public WXInterstitialAd CreateInterstitialAd(WXCreateInterstitialAdParam param)

2.说明

作用：创建插屏广告组件，通过这个对象展示插屏广告
配置插屏广告：微信小游戏后台->流量主->广告管理->插屏广告->新建广告位
参数说明：调用该方法需传入微信的参数对象WXCreateInterstitialAdParam，在这个对象中可以设置插屏广告的参数，比如广告ID；adUnitId（广告ID）获取路径：微信公众平台->流量主->广告管理->插屏广告->广告位ID
返回值说明：该方法返回的是微信对象WXInterstitialAd，通过这个对象可以控制激励视频广告的一些行为
监听事件说明：OnLoad监听加载完成，OnError监听加载失败，OnClose监听广告被关闭
注意事项：可以直接在OnLoad中调用Show方法，加载完成后直接显示广告，因为该组件在关闭后就自动销毁了，不会再次调用OnLoad
更多介绍：请参考微信插屏广告介绍文档以及微信激励视频广告接口文档

3.调用范例

var param = new WXCreateInterstitialAdParam();
param.adUnitId = adUnitId;
var interstitialAd = CreateInterstitialAd(param);
interstitialAd.OnLoad((WXADLoadResponse response) => {
    Debug.Log($"###ShowInterstitialAd OnLoad>>rewardValue:{response.rewardValue}>>shareValue:{response.shareValue}");
    // 创建完后直接显示
    interstitialAd?.Show();
});
interstitialAd.OnError((WXADErrorResponse error) => {
    Debug.Log($"###ShowInterstitialAd OnError>>errCode:{error.errCode}");
});
interstitialAd.OnClose(() => {
    Debug.Log($"###ShowInterstitialAd OnClose");
});
interstitialAd.Load();

4.回调方法
无

原生模板广告`(选接)`

1.方法

/// <summary>
/// 创建原生模板广告组件
/// 参考文档：https://developers.weixin.qq.com/minigame/dev/api/ad/wx.createCustomAd.html
/// </summary>
/// <param name="param">微信原生模板广告参数对象</param>
/// <returns>微信原生模板广告组件</returns>
public WXCustomAd CreateCustomAd(WXCreateCustomAdParam param)

2.说明

作用：创建原生模板广告组件并显示
配置原生模版广告：微信小游戏后台->流量主->广告管理->原生模版广告->新建广告位
参数说明：调用该方法需传入微信的参数对象WXCreateCustomAdParam，在这个对象中可以设置插屏广告的参数，比如广告ID、广告样式；adUnitId（广告ID）获取路径：微信公众平台->流量主->广告管理->原生模版广告->广告位ID
返回值说明：该方法返回的是微信对象WXCustomAd，通过这个对象可以控制激励视频广告的一些行为
监听事件说明：OnLoad监听加载完成，OnError监听加载失败，OnClose监听广告被关闭
性能优化说明：如果离开原生模版广告所展示的游戏页面，要调用Destroy方法销毁原生模版广告，释放内存资源
更多介绍：请参考微信原生模版广告介绍文档以及微信原生模版广告接口文档

3.调用范例

创建原生模版广告，并水平靠左垂直居中

var info = WX.GetWindowInfo();
var screenWidth = info.screenWidth;
var screenHeight = info.screenHeight;

Debug.Log($"###screenWidth:{screenWidth}>>screenHeight:{screenHeight}");

var param = new WXCreateCustomAdParam();
param.adUnitId = adUnitId;
// 靠左居中显示
param.style.left = 0;
param.style.top = (int)(screenHeight / 2);

Debug.Log($"###left:{param.style.left}>>top:{param.style.top}");

this.customAd = Nebula.NebulaSDKBridge.Instance.CreateCustomAd(param);
this.customAd.OnLoad((WXADLoadResponse response) => {
    Debug.Log($"###CustomAd OnLoad>>rewardValue:{response.rewardValue}>>shareValue:{response.shareValue}");
});
this.customAd.OnError((WXADErrorResponse error) => {
    Debug.Log($"###CustomAd OnError>>errCode:{error.errCode}");
});
this.customAd.OnClose(() => {
    Debug.Log($"###CustomAd OnClose");
});

显示原生模版广告

this.customAd?.Show();

隐藏原生模版广告

this.customAd?.Hide();

销毁原生模版广告

this.customAd?.Destroy();

4.回调方法

无

显示转发按钮`(选接)`

1.方法

/// <summary>
/// 显示转发按钮（右上角菜单的转发按钮）
/// 参考文档：https://developers.weixin.qq.com/minigame/dev/api/share/wx.showShareMenu.html
/// </summary>
/// <param name="param">微信显示转发按钮参数对象</param>
public void ShowShareMenu(ShowShareMenuOption param)

2.说明

作用：菜单中的“转发”选项默认不展示，通过此接口可动态显示这个选项，请在打开游戏以后及时调用此接口显示此转发按钮
参数说明：调用该方法需传入微信的参数对象ShowShareMenuOption，在这个对象中可以设置转发类型（好友、朋友圈）、是否显示成功的监听等
更多介绍：请参考微信转发介绍文档以及微信显示转发按钮接口文档

3.调用范例

var param = new ShowShareMenuOption();
// "shareAppMessage"表示“发送给朋友”按钮，"shareTimeline"表示“分享到朋友圈”按钮
// 显示“分享到朋友圈”按钮时必须同时显示“发送给朋友”按钮，显示“发送给朋友”按钮时则允许不显示“分享到朋友圈”按钮
param.menus = new string[] { "shareAppMessage", "shareTimeline" }; 
param.success = (GeneralCallbackResult response) => {
    Debug.Log($"###ShowShareMenu success");
};
param.fail = (GeneralCallbackResult response) => {
    Debug.Log($"###ShowShareMenu fail");
};
Nebula.NebulaSDKBridge.Instance.ShowShareMenu(param);

4.回调方法

无

隐藏转发按钮`(选接)`

1.方法

/// <summary>
/// 隐藏转发按钮（右上角菜单的转发按钮）
/// 参考文档：https://developers.weixin.qq.com/minigame/dev/api/share/wx.hideShareMenu.html
/// </summary>
/// <param name="param">微信隐藏转发按钮参数对象</param>
public void HideShareMenu(HideShareMenuOption param)

2.说明

作用：通过此接口可动态隐藏菜单中的“转发”选项
参数说明：调用该方法需传入微信的参数对象HideShareMenuOption，在这个对象中可以设置是否隐藏成功的监听等
更多介绍：请参考微信转发介绍文档以及微信隐藏转发按钮接口文档

3.调用范例

var param = new HideShareMenuOption();
param.success = (GeneralCallbackResult response) => {
    Debug.Log($"###HideShareMenu success");
};
param.fail = (GeneralCallbackResult response) => {
    Debug.Log($"###HideShareMenu fail");
};
Nebula.NebulaSDKBridge.Instance.HideShareMenu(param);

4.回调方法

无

主动转发-方式一（使用星云开放平台维护的卡片）`(选接)`

1.方法

/// <summary>
/// 主动转发
/// 使用星云开放平台维护的卡片，主动拉起转发，进入选择通讯录界面
/// </summary>
/// <param name="messageCardId">卡片ID，要传星云开放平台配置的卡片ID</param>
public void ShareAppMessage(int messageCardId)

2.说明

作用：此方法通过星云开放平台维护的卡片信息，来控制转发的标题、图片等，并主动拉起转发界面
配置转发卡片：星云开放平台->GM系统->微信小游戏运营工具->微信转发，配置好卡片标题、图片等
参数说明：需传入星云开放平台配置的卡片ID，获取路径：星云开放平台->GM系统->微信小游戏运营工具->微信转发->卡片ID
回调说明：如果转发拉起成功，会回调ShareAppMessageCallback通知游戏，注意：调用此方法后立即回调，而不是完成分享跳转回来后才回调
更多介绍：如果想要更自定义分享的内容，请查看"主动转发-方式二"接口

3.调用范例

Nebula.NebulaSDKBridge.Instance.ShareAppMessage(1);

4.回调方法

Nebula.NebulaSDKBridgeCallback.ShareAppMessageCallback

主动转发-方式二（使用微信的参数对象进行配置）`(选接)`

1.方法

/// <summary>
/// 主动转发
/// 使用微信的参数对象进行配置转发内容，主动拉起转发，进入选择通讯录界面
/// 参考文档：https://developers.weixin.qq.com/minigame/dev/api/share/wx.shareAppMessage.html
/// </summary>
/// <param name="param">微信转发参数对象</param>
public void ShareAppMessage(ShareAppMessageOption param)

2.说明

作用：此方法通过使用微信的参数对象进行配置，来控制转发的标题、图片等，并主动拉起转发界面，例如：可以实时截取游戏的画面当成分享的图片，具体方式请查看调用范例
参数说明：调用该方法需传入微信的参数对象ShareAppMessageOption，在这个对象中可以设置分享的标题、图片等
更多介绍：请参考微信转发介绍文档以及微信主动转发接口文档

3.调用范例

截取游戏画面中间部分作为分享的图片

// 使用Unity的接口获取屏幕高度，截取屏幕高度的1/3
int ShareHeight = Screen.height / 3;
WXCanvas.ToTempFilePath(new WXToTempFilePathParam()
{
    x = (Screen.width - ShareHeight) / 2,// 水平方向居中
    y = ShareHeight,
    width = ShareHeight, // 宽度和高度相等
    height = ShareHeight,
    destWidth = ShareHeight, // 目标图片的宽度，会将截取的部分拉伸或压缩至该数值
    destHeight = ShareHeight, // 目标图片的高度，会将截取的部分拉伸或压缩至该数值
    success = (result) =>
    {
        Debug.Log("###ToTempFilePath success" + JsonUtility.ToJson(result));

        var param = new ShareAppMessageOption()
        {
            title = "自定义分享",
            imageUrl = result.tempFilePath,
        };

        Nebula.NebulaSDKBridge.Instance.ShareAppMessage(param);
    },
    fail = (result) =>
    {
        Debug.Log("###ToTempFilePath fail" + JsonUtility.ToJson(result));
    },
    complete = (result) =>
    {
        Debug.Log("###ToTempFilePath complete" + JsonUtility.ToJson(result));
    },
});

4.回调方法

无

被动转发-方式一（使用星云开放平台维护的卡片）`(选接)`

1.方法

/// <summary>
/// 被动转发
/// 使用星云开放平台维护的卡片，配置右上角菜单的转发内容
/// </summary>
/// <param name="messageCardId">卡片ID，要传星云后台配置的卡片ID</param>
public void OnShareAppMessage(int messageCardId)

2.说明

作用：此方法通过星云开放平台维护的卡片信息，来控制小游戏右上角菜单的转发标题、图片等内容
配置转发卡片：需先配置星云开放平台的转发卡片，配置好卡片标题、图片等，配置路径：星云开放平台->GM系统->微信小游戏运营工具->微信转发
参数说明：需传入星云开放平台配置的卡片ID，获取路径：星云开放平台->GM系统->微信小游戏运营工具->微信转发->卡片ID
回调说明：调用完成后会回调OnShareAppMessageCallback来告诉游戏是否有设置成功，注意：调用此方法后立即回调，而不是完成分享跳转回来后才回调
更多介绍：如果想要更自定义分享的内容，请查看"被动转发-方式二"接口

3.调用范例

Nebula.NebulaSDKBridge.Instance.OnShareAppMessage(1);

4.回调方法

Nebula.NebulaSDKBridgeCallback.OnShareAppMessageCallback

被动转发-方式二（使用微信的参数对象进行配置）`(选接)`

1.方法

/// <summary>
/// 被动转发
/// 使用微信的参数对象进行配置，配置右上角菜单的转发内容
/// 参考文档：https://developers.weixin.qq.com/minigame/dev/api/share/wx.onShareAppMessage.html
/// </summary>
/// <param name="defaultParam">默认的设置内容</param>
/// <param name="action">用户点击右上角菜单的「转发」按钮时触发的事件的回调函数，请在回调后三秒内，触发 Action<WXShareAppMessageParam>返回设置的内容,否则会使用 defaultParam</param>
public void OnShareAppMessage(WXShareAppMessageParam defaultParam, Action<Action<WXShareAppMessageParam>> action = null)

2.说明

作用：此方法通过使用微信的参数对象进行配置，来控制小游戏右上角菜单的转发标题、图片等内容
参数说明：调用该方法需传入微信的参数对象WXShareAppMessageParam，在这个对象中可以设置默认的分享的标题、图片等；第二个参数为可选参数，通过Action回调来实时设置自定义的分享内容，如没有则使用第一个参数作为默认的分享内容
更多介绍：请参考微信转发介绍文档以及微信主动转发接口文档

3.调用范例

var defaultParam = new WXShareAppMessageParam();
defaultParam.title = "自定义分享标题"; // 分享的标题
defaultParam.imageUrl = "xxx"; // 图片地址

Nebula.NebulaSDKBridge.Instance.OnShareAppMessage(defaultParam, (shareAction) =>
{
    shareAction(new WXShareAppMessageParam
    {
        title = "自定义分享标题",
        imageUrl = "xxx"
    });
});

4.回调方法

无

打开客服会话`(选接)`

1.方法

/// <summary>
/// 打开客服会话
/// </summary>
/// <param name="param">微信客户会话参数对象</param>
public void OpenCustomerServiceConversation(OpenCustomerServiceConversationOption param)

2.说明

作用：调用此方法打开客服会话
参数说明：调用该方法需传入微信的参数对象OpenCustomerServiceConversationOption
更多介绍：请参考微信客服会话接口文档

3.调用范例

var param = new OpenCustomerServiceConversationOption();
// 会话来源
//param.sessionFrom = "xxx"; 
// 是否显示会话内消息卡片
//param.showMessageCard = true;
// 会话内消息卡片标题
//param.sendMessageTitle = "xxx标题";
// 会话内消息卡片路径
//param.sendMessagePath = "";
// 会话内消息卡片图片路径
//param.sendMessageImg = "";
// 接口调用成功的回调函数
param.success = (result) => {
    Debug.Log("###OpenCustomerService success" + JsonUtility.ToJson(result));
};
// 接口调用失败的回调函数
param.fail = (result) => {
    Debug.Log("###OpenCustomerService fail" + JsonUtility.ToJson(result));
};
// 接口调用结束的回调函数（调用成功、失败都会执行）
param.complete = (result) => {
    Debug.Log("###OpenCustomerService complete" + JsonUtility.ToJson(result));
};
Nebula.NebulaSDKBridge.Instance.OpenCustomerServiceConversation(param);

4.回调方法

无

获取配置参数`(选接)`

1.说明

如果想在初始化之前就获取到星云的配置参数，可以直接读取fy-config.json，参考如下调用范例

2.调用范例

var json = Resources.Load<TextAsset>("fy-config");
Debug.Log($"###fy-config>>{json}");
var config = JsonUtility.FromJson<Nebula.NebulaSDKConfig>(json.text);
// 星云开放平台AppID 
var appId = config.nbAppId;
// 星云开放平台渠道ID
var channelId = config.nbChannelId;
// 星云开放平台渠道模板标识
var channelTemplateCode = config.nbChannelTemplateCode;
// 星云开放平台通行证标识
var passportCode = config.passportCode;
// 星云开放平台支付标识
var paymentCode = config.paymentCode;

回调

说明：请在游戏代码中，设置好的相应的委托方法，并编写游戏的回调逻辑
案例：更详细案例可以参考对接资源中的范例'Script/Menu.cs'
统一返回对象格式如下：

属性名	说明
status	成功`success`、失败`error`
code	响应状态码，根据不同状态进行处理和错误原因排查
msg	提示消息
data	返回值，响应结果不同请求数据格式参照方法说明文档

code统一错误码：

错误码	说明
10001	当前环境不支持
10002	未进行初始化调用
10003	未进行登录调用
10004	获取渠道配置
10005	创建聚合订单失败
10006	订单回调失败
10007	预创建订单失败
10008	创建扫码订单失败
20001	登录失败
30001	支付失败
30002	渠道支付配置关闭
30003	游戏币支付失败
30004	直购支付失败
30005	打开客服支付取消
30006	创建客服支付失败
30007	创建扫码支付失败

初始化回调

1.方法

Nebula.NebulaSDKBridgeCallback.InitCallback

2.说明

初始化后会回调此方法，并返回配置参数
应在确保收到初始化成功回调后才能调用其他接口

3.参数

data参数：

参数	类型	说明
nbAppId	string	星云开放平台AppID
nbChannelId	string	星云开放平台渠道ID，如果游戏要对渠道做差异化处理时，可以使用此ID作为区分
nbChannelTemplateCode	string	星云开放平台渠道模板标识，用来标明该渠道使用的是哪个渠道模板（一级渠道，在“对接中心-渠道打包-渠道配置”中添加渠道时所选的渠道模板），如果游戏要对不同渠道模板做差异化处理时，可以使用此标识作为区分，例如：针对不同渠道模板进行玩家信息隔离。所有渠道的渠道模板标识请看渠道版本信息
passportCode	string	星云开放平台通行证标识，用来标明该渠道用什么通行证进行登录
paymentCode	string	星云开放平台支付标识，用来标明该渠道用什么支付方式

4.使用方式

Nebula.NebulaSDKBridgeCallback.InitCallback = (initInfo) =>
{
    Debug.Log($"###InitCallback>>status:{initInfo.status}>>code:{initInfo.code}>>msg:{initInfo.msg}>>nbAppId:{initInfo.data.nbAppId}>>nbChannelId:{initInfo.data.nbChannelId}>>nbChannelTemplateId:{initInfo.data.nbChannelTemplateId}>>passportCode:{initInfo.data.passportCode}>>paymentCode:{initInfo.data.paymentCode}");

    // initInfo.data.nbAppId;
    // initInfo.data.nbChannelId;
    // initInfo.data.nbChannelTemplateCode; 
    // initInfo.data.passportCode;
    // initInfo.data.paymentCode;

    if ("success".Equals(initInfo.status))
    {
        // 初始化成功
        IsInitFinish = true;
    }
    else
    {
        // 初始化失败
        IsInitFinish = false;
    }

登录回调

1.方法

Nebula.NebulaSDKBridgeCallback.LoginCallback

2.说明

调用登录后会回调此方法，游戏在此方法中做登录的逻辑处理

3.参数

data参数：

参数	类型	说明
nbOpenId	string	聚合渠道用户 openId,`可作为游戏内玩家的唯一用户标识`
openId	string	微信小游戏 openId,可作为用户扩展属性值使用
token	string	星云通行证凭证 Token
firstLogin	bool	是否首次登录，true 表示首次登录，false 表示非首次登录

4.使用方式

Nebula.NebulaSDKBridgeCallback.LoginCallback = (loginInfo) =>
{
    LogManager.Instance.Add("###LoginCallback>>status:" + loginInfo.status + ">>code:" + loginInfo.code + ">>msg:" + loginInfo.msg + ">>openId:" + loginInfo.data.openId + ">>token:" + loginInfo.data.token + ">>nbOpenId:" + loginInfo.data.nbOpenId + ">>firstLogin:" + loginInfo.data.firstLogin);

    if ("success".Equals(loginInfo.status))
    {
        // 登录成功
    } 
    else
    {
        // 登录失败
    }
};

支付回调

1.方法

Nebula.NebulaSDKBridgeCallback.PayCallback

2.说明

调用支付后会回调此方法，游戏在此方法中做支付的逻辑处理
此回调只是客户端的支付成功回调，不能作为发放道具的依据，具体是否真正支付成功，需要等服务端的支付成功回调

3.参数

data参数：

属性	类型	说明
payType	int	支付方式，1=原生支付、2=客服支付、3=二维码支付，支付成功状态`success`下，不同的支付方式最终结果都以服务端通知为基准 1.安卓和 PC 端的原生支付：返回值可代表微信支付的状态 2.iOS 客服和 PC 扫码支付：由于这两种模式已脱离了 SDK，所以返回值无法代表支付状态,`仅代表成功唤起`
orderNo	string	星云订单号

4.使用方法

Nebula.NebulaSDKBridgeCallback.PayCallback = (payInfo) =>
{
    Debug.Log("###PayCallback>>status:"+ payInfo.status + ">>code:" + payInfo.code + ">>msg:" + payInfo.msg + ">>orderNo:" + payInfo.data.orderNo + ">>payType:" + payInfo.
                data.payType);

    if ("success".Equals(payInfo.status))
    {
        // 支付成功   
    } else
    {
        // 支付失败
    }
};

创建问卷回调

1.方法

Nebula.NebulaSDKBridgeCallback.CreateSurveyCallback

2.说明

调用CreateSurvey方法后会回调此方法，通知游戏问卷是否有效，游戏可根据是否有效来决定显示问卷按钮

3.参数

status：返回"success"则问卷有效，否则为问卷无效
data参数：

属性	类型	说明
surveyId	int	问卷ID
surveyTitle	string	问卷标题

4.使用方法

Nebula.NebulaSDKBridgeCallback.CreateSurveyCallback = (info) =>
{
    Debug.Log("###CreateSurveyCallback>>status:" + info.status + ">>code:" + info.code + ">>msg:" + info.msg + ">>surveyId:" + info.data.surveyId + "surveyTitle:" + info.data.surveyTitle);
    if ("success".Equals(info.status))
    {
        // 问卷有效
    }
    else
    {
        // 问卷无效
    }
};

显示问卷回调

1.方法

Nebula.NebulaSDKBridgeCallback.ShowSurveyCallback

2.说明

调用ShowSurvey方法后会回调此方法，通知游戏是否有完成回答问卷，游戏可根据此来判断是否下发奖励

3.参数

status：返回"success"则问卷有效，否则为问卷无效
data参数：

属性	类型	说明
surveyId	int	问卷ID
surveyTitle	string	问卷标题
answerStatus	string	回答状态，"answered"：已回答，其他：未回答

4.使用方法

Nebula.NebulaSDKBridgeCallback.ShowSurveyCallback = (info) =>
{
    Debug.Log("###ShowSurveyCallback>>status:" + info.status + ">>code:" + info.code + ">>msg:" + info.msg + ">>surveyId:" + info.data.surveyId);

    if ("success".Equals(info.status))
    {
        if (info.data.answerStatus == "answered")
        {
            // 问卷填写完成，下发奖励

        }
    }
    else
    {
        // 问卷已失效

    }
};

订阅消息回调

1.方法

Nebula.NebulaSDKBridgeCallback.SubscribeMessageCallback

2.说明

调用RequestSubscribeMessage方法后会回调此方法，通知游戏是否有订阅成功，并下发模版ID以及相应的订阅状态

3.参数

status：返回"success"则订阅成功，否则为订阅失败
data参数：

属性	类型	说明
tmplId	string	模版ID
always	string	是否勾选保持状态，"true":总是保持允许，"false":总是保持拒绝
status	string	订阅状态，"accept":接受、"filter":过滤、"reject":拒绝、"ban":封禁

4.使用方法

Nebula.NebulaSDKBridgeCallback.SubscribeMessageCallback = (info) =>
{
    Debug.Log("###SubscribeMessageCallback>>status:" + info.status + ">>code:" + info.code + ">>msg:" + info.msg);

    string log = "";

    if ("success".Equals(info.status))
    {
        // 已成功订阅消息

        foreach (var data in info.data)
        {
            log += $"###tmplId:{data.tmplId}>>always:{data.always}>>status:{data.status}\n";
        }

        Debug.Log(log);

    }
    else
    {
        // 订阅消息失败
    }
};

主动转发回调（方式一）

1.方法

Nebula.NebulaSDKBridgeCallback.ShareAppMessageCallback

2.说明

调用ShareAppMessage（主动转发-方式一）方法后会回调此方法，通知游戏是否成功拉起转发界面

3.参数

status：返回"success"则拉起成功，否则为拉起失败

4.使用方法

Nebula.NebulaSDKBridgeCallback.ShareAppMessageCallback = (info) =>
{
    if ("success".Equals(info.status))
    {
        // 拉起转发成功

    }
    else
    {
        // 拉起转发失败
    }
};

被动转发回调（方式一）

1.方法

Nebula.NebulaSDKBridgeCallback.OnShareAppMessageCallback

2.说明

调用OnShareAppMessage（被动转发-方式一）方法后会回调此方法，通知游戏是否成功设置被动转发
注意：设置完成后立即回调

3.参数

status：返回"success"则设置成功，否则为设置失败

4.使用方法

Nebula.NebulaSDKBridgeCallback.OnShareAppMessageCallback = (info) =>
{
    if ("success".Equals(info.status))
    {
        // 设置转发成功

    }
    else
    {
        // 设置转发失败
    }
};

导出测试

在Unity工程对接好SDK的接口和回调之后，打开Unity工程的"微信小游戏"插件，导出小游戏工程即可进行测试。

FAQ

支付金额错误

支付金额单位是分，要进行转换

商品 ID 错误

小游戏直购未发布的商品只能使用沙箱模式支付，商品金额和商品 ID 必须与小游戏后台配置的一致

提示环境不支持

由于开发游戏可能用不使用微信开发者工具，在其他 IDE 中无法调用微信小游戏的接口，所以会提示环境不支持

渠道支付配置关闭

渠道支付配置关闭，通过星云渠道配置进行开启，不开启游戏支付返回失败，建议可以根据状态码30002进行自定义处理，显示友好提示

客服支付和扫码支付，手机还未进行付款返回结果支付成功

客服支付和扫码支付，无法检测到用户是否已经付款，打开客服和生成二维码即可算成功，可以根据返回值payType进行自定义处理

无法原生支付

商品ID和商品价格必须与微信后台一致，否则可能提示系统错误

微信小游戏SDK-Unity(C#)

文档修订记录

接入准备

接入须知

接口

初始化(必接)

登录(必接)

支付(必接)

调试模式(选接)

问卷(选接)

订阅消息(选接)

游戏圈(选接)

激励视频广告(选接)

Banner广告(选接)

插屏广告(选接)

原生模板广告(选接)

显示转发按钮(选接)

隐藏转发按钮(选接)

主动转发-方式一（使用星云开放平台维护的卡片）(选接)

主动转发-方式二（使用微信的参数对象进行配置）(选接)

被动转发-方式一（使用星云开放平台维护的卡片）(选接)

被动转发-方式二（使用微信的参数对象进行配置）(选接)

打开客服会话(选接)

获取配置参数(选接)

回调

初始化回调

登录回调

支付回调

创建问卷回调

显示问卷回调

订阅消息回调

主动转发回调（方式一）

被动转发回调（方式一）

导出测试

FAQ

初始化`(必接)`

登录`(必接)`

支付`(必接)`

调试模式`(选接)`

问卷`(选接)`

订阅消息`(选接)`

游戏圈`(选接)`

激励视频广告`(选接)`

Banner广告`(选接)`

插屏广告`(选接)`

原生模板广告`(选接)`

显示转发按钮`(选接)`

隐藏转发按钮`(选接)`

主动转发-方式一（使用星云开放平台维护的卡片）`(选接)`

主动转发-方式二（使用微信的参数对象进行配置）`(选接)`

被动转发-方式一（使用星云开放平台维护的卡片）`(选接)`

被动转发-方式二（使用微信的参数对象进行配置）`(选接)`

打开客服会话`(选接)`

获取配置参数`(选接)`