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

文档修订记录

文档版本 文档更新日期 文档更新内容
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'目录下。

接入须知

1.微信小游戏登录&支付&客服等流程介绍， 点击进入

2.微信小游戏接入配置指引，点击进入

3.AccessToken 全局唯一处理，需要接入令牌服务，点击进入

4.服务端文档请查阅，点击进入

接口

具体对接代码可以参考对接资源中的范例'Script/Menu.cs'

初始化(必接)

1.方法

public void Init(string gameVersion)

2.说明

  • 游戏需要在刚启动游戏的时候调用。
  • 初始化完成后会回调初始化回调，并返回星云配置参数

3.调用范例

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

4.参数说明

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

5.回调方法

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

登录(必接)

1.方法

public void Login()

2.说明

  • 玩家需要登录时调用
  • 登录后会通过登录成功回调，返回json格式的用户信息，游戏通过解析json获取相应的用户信息

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.说明

  • 玩家需要支付时调用
  • 游戏订单号需要由游戏生成一个唯一值，并存放在服务端，后续支付校验使用

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.回调方法

// 支付回调
PayCallback

调试模式(选接)

1.说明

可以进行对接问题排查和检测功能是否完整接入，上线后请务必将调试状态关闭！！！
调试模式开启情况进入，星云开放平台 → 游戏中心 → 选择游戏 → 对接中心 → SDK 对接 → SDK 调试 → H5 → 微信小游戏 SDK → SDK 调试，进行调试结果查看

file

file

2.调用范例

Nebula.NebulaSDKBridge.Instance.NebulaDebug(false);

3.参数说明

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

回调

请在游戏代码中，设置好的相应的委托方法，并编写游戏的回调逻辑。具体对接代码可以参考对接资源中的范例'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

登录回调

1.方法

Nebula.NebulaSDKBridgeCallback.LoginCallback

2.说明

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

3.参数

data参数：

参数 类型 说明
nbOpenId string 聚合渠道用户 openId,可作为游戏内玩家的唯一用户标识
openId string 微信小游戏 openId,可作为用户扩展属性值使用
token string 星云通行证凭证 Token

4.使用方式

Nebula.NebulaSDKBridgeCallback.LoginCallback = (loginInfo) =>
{
    Debug.Log("###LoginCallback>>status:"+ loginInfo.status + ">>code:" + loginInfo.code + ">>msg:" + loginInfo.msg + ">>openId:" + loginInfo.data.openId + ">>token:" + loginInfo.data.token  + ">>nbOpenId:" + loginInfo.data.nbOpenId);

    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
    {
        // 支付失败
    }
};

导出测试

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

FAQ

  • 支付金额错误

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

  • 商品 ID 错误

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

  • 提示环境不支持

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

  • 渠道支付配置关闭

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

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

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

  • 无法原生支付

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

文章目录