小游戏聚合SDK-Unity(C#)

文章目录 [显示]

文档修订记录

文档版本	文档更新日期	文档更新内容
3.3.92	2025.04.11	1.「渠道平台指引」OPPO小游戏说明更新一键转功能内容
3.3.91	2025.04.03	1.「渠道平台指引」新增小米小游戏
3.3.88	2025.02.26	1.「渠道平台指引」vivo小游戏更新调试说明
3.3.86	2025.02.12	1.「渠道平台指引」美团小游戏新增游戏行为数据上报接口
3.3.83	2025.01.16	1.「渠道平台指引」华为、vivo、OPPO小游戏新增创建桌面图标接口
3.3.82	2025.01.03	1.「渠道平台指引」新增美团小游戏角色上报、添加快捷方式、获取启动参数、一键订阅二楼任务等特殊接口和回调
3.3.78	2024.12.09	1.新增支付宝小游戏 2.新增特殊方法接口 3.「渠道平台指引」新增支付宝小游戏行为数据上报，设首、复访任务，游戏圈等特殊接口和回调
3.3.76	2024.11.28	1.接入华为快游戏、OPPO小游戏、vivo小游戏；2.新增「打开客服对话」接口
3.3.73	2024.11.08	1.聚合接口初版。2.接入支付宝小游戏

接入须知

1.各个渠道如何配置，请跳转到快游戏接入配置指引：

支付宝小游戏：点击跳转
华为小游戏：点击跳转
OPPO小游戏：点击跳转
vivo小游戏：点击跳转
美团小游戏：点击跳转

2.服务端验证接入，请查看快游戏服务端文档请查阅：点击跳转

接入准备

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

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

3.将你要对接的渠道资源NebulaQuick_xxx.unitypackage导入到您的Unity工程的Assets文件夹下，例如支付宝的渠道资源名称为NebulaQuick_alipay.unitypackage。注意：一个工程只能导入一种渠道资源，否则会造成不同渠道资源之间的冲突。

4.从星云开放平台下载目标渠道的 'fy-config.json' ，拷贝到Untiy工程的'Assets/Resources'目录下。下载路径：星云开放平台->对接中心->渠道打包->渠道配置->找到目标快游戏渠道->点击"下载配置文件"。注意：每个渠道要单独下载对应的配置文件，不可公用，否则无法正常使用。

接口

必接接口：游戏必须要接入
选接接口：按照游戏发行需求来接入
回调：某些接口有相应的回调游戏需要进行处理，具体请查看本文档的「回调」章节
案例：更详细案例可以参考对接资源中的范例'NBDemo/Assets/Scripts/SDKManager.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并返回用户信息

3.调用范例

Nebula.NebulaSDKBridge.Instance.Login();

4.参数说明
无

5.回调方法

// 登录回调
Nebula.NebulaSDKBridgeCallback.LoginCallback

支付`(必接)`

1.方法

/// <summary>
/// 支付
/// </summary>
/// <param name="goodsPrice">商品价格，单位：分</param>
/// <param name="tradeNo">游戏订单号</param>
/// <param name="goodsId">商品 ID</param>
/// <param name="goodsName">商品名称</param>
/// <param name="playerId">角色 ID</param>
/// <param name="playerName">玩家名称</param>
/// <param name="playerLevel">玩家等级</param>
/// <param name="vipLevel">VIP 等级</param>
/// <param name="serverId">服务器 ID</param>
/// <param name="zoneId">分区 ID</param>
/// <param name="sandbox">沙箱支付，0=正式支付、1=沙箱支付</param>
/// <param name="notifyURL">回调地址</param>
/// <param name="notifyExt">额外参数</param>
public void Pay(NebulaSDKPayParams payParams)

2.说明

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

3.调用范例

var payParams = new NebulaSDKPayParams();
payParams.goodsPrice = PayAmount;
payParams.tradeNo = GameOrderId;
payParams.goodsId = GoodsId;
payParams.goodsName = GoodsName;
payParams.playerId = PlayerID;
payParams.playerName = PlayerName;
payParams.playerLevel = PlayerLevel;
payParams.vipLevel = "1";
payParams.serverId = ServerID;
payParams.zoneId = "1";
payParams.sandbox = 0;
payParams.notifyURL = "";
payParams.notifyExt = "";

Nebula.NebulaSDKBridge.Instance.Pay(payParams);

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=沙箱支付	否
notifyUrl	string	-	1.通过该值能在客户端动态传递服务端支付回调地址；2.若您在客户端传递了该地址，则支付完成后会通过此地址回调支付结果；3.若您同时也在星云后台配置了支付回调地址，会优先回调客户端传递的地址；4.需要先配置支付回调可信域名，请前往"星云后台->对接中心->回调配置->支付回调可信域名"进行配置，否则无法回调成功；5.若您在客户端传递了该地址，在游戏包体发布之前，建议您仔细检查该参数是否配置正确，以防止包体发布后支付出现问题	否
notifyExt	string	-	额外参数，游戏的透传参数可通过此参数传递，支付完成后平台服务端会回调此参数给游戏服务端。对应服务端支付回调的notify_ext参数	否

5.回调方法

// 支付回调
Nebula.NebulaSDKBridgeCallback.PayCallback

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

1.方法

/// <summary>
/// 展示激励视频广告
/// </summary>
/// <param name="adUnitId">广告ID</param>
public void ShowRewardedVideoAd(string adUnitId)

2.说明

调用此接口将拉起展示激励视频广告
在激励视频广告回调中，判断是否下发观看广告奖励
在调用此接口之前请在第三方渠道后台先配置好广告，并获取到adUnitId，各个渠道的广告配置方法请查看接入须知"接入配置指引"

3.调用范例

Nebula.NebulaSDKBridge.Instance.ShowRewardedVideoAd("xxx");

4.回调方法

Nebula.NebulaSDKBridgeCallback.RewardedVideoAdCallback

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

1.方法

/// <summary>
/// 打开客服对话
/// </summary>
/// <param name="customerServiceParams"></param>
public void OpenCustomerServiceConversation(NebulaSDKCustomerServiceParams customerServiceParams)

2.说明

调用此接口将拉起客服对话页面

3.调用范例

var csParams = new NebulaSDKCustomerServiceParams();
csParams.source = 3;
csParams.serverId = ServerID;
csParams.serverName = ServerName;
csParams.playerId = PlayerID;
csParams.playerName = PlayerName;
csParams.playerLevel = PlayerLevel;
csParams.vipLevel = "1";
Nebula.NebulaSDKBridge.Instance.OpenCustomerServiceConversation(csParams);

4.参数说明

参数	类型	默认值	说明	必传
source	int	-	提交入口。2：SDK登录后进入游戏前； 3：进入游戏后	是
serverId	string	-	游戏服id	否
serverName	string	-	游戏服名称	否
playerId	string	-	角色id	否
playerName	string	-	角色名称	否
playerLevel	string	-	角色等级	否
vipLevel	string	-	角色vip等级	否

5.回调方法

Nebula.NebulaSDKBridgeCallback.CustomerServiceCallback

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

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;

3.参数说明

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

回调

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

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

code统一错误码：

错误码	说明
10001	网络请求失败
10002	初始化失败
10003	启动参数获取失败
10004	配置文件无法读取
10005	渠道类型无法获取
20001	登录失败
20002	登录取消
20003	第三方渠道登录失败
20004	服务端登录验证失败
30001	支付失败
30002	渠道支付配置关闭
30003	支付取消
30004	创建聚合订单失败
30005	支付配置获取失败
30006	第三方渠道支付失败
40001	广告播放未完成
40002	广告加载失败

初始化回调

1.方法

Nebula.NebulaSDKBridgeCallback.InitCallback

2.说明

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

3.参数

data参数：

无

4.使用方式

Nebula.NebulaSDKBridgeCallback.InitCallback = (initInfo) =>
{
    Debug.Log($"###InitCallback>>status:{initInfo.status}>>code:{initInfo.code}>>msg:{initInfo.msg}");

    if ("success".Equals(initInfo.status))
    {
        // 初始化成功

    }
    else
    {
        // 初始化失败

    }
}

登录回调

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参数：

属性	类型	说明
orderNo	string	星云订单号

4.使用方法

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

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

激励视频广告回调

1.方法

Nebula.NebulaSDKBridgeCallback.RewardedVideoAdCallback

2.说明

调用完成激励视频广告接口后回调，游戏在此处确定是否下发观看广告奖励

3.参数

data 参数：

属性	类型	说明
adUnitId	string	广告ID

4.使用方法

Nebula.NebulaSDKBridgeCallback.RewardedVideoAdCallback = (rewardedVideoAdInfo) =>
{
    Debug.Log("###RewardedVideoAdCallback>>status:" + rewardedVideoAdInfo.status + ">>code:" + rewardedVideoAdInfo.code + ">>msg:" + rewardedVideoAdInfo.msg + ">>adUnitId:" + rewardedVideoAdInfo.data.adUnitId);

    if ("success".Equals(rewardedVideoAdInfo.status))
    {
        // 广告播放完成
        Debug.Log("###广告播放完成");
    }
    else
    {
        // 广告播放失败
        Debug.Log("###广告播放失败");
    }
};

打开客服对话回调

1.方法

Nebula.NebulaSDKBridgeCallback.CustomerServiceCallback

2.说明

调用完成打开客服对话接口后回调，游戏在此处确定是否打开成功

3.参数

data 参数：无

4.使用方法

Nebula.NebulaSDKBridgeCallback.CustomerServiceCallback = (info) =>
{
    LogManager.Instance.Add("###CustomerServiceCallback>>status:" + info.status + ">>code:" + info.code + ">>msg:" + info.msg );

    if ("success".Equals(info.status))
    {
        LogManager.Instance.Add("###打开客服成功");
    }
    else
    {
        LogManager.Instance.Add("###打开客服失败");
    }
};

渠道平台指引

支付宝小游戏

特殊接口

回调

Nebula.NebulaSDKBridgeCallback.Callback = (method, result) =>
{
    LogManager.Instance.Add($"###Callback>>method:{method}>>result:{result}");
    // GetLaunchOptions：当调用GetLaunchOptions之后回调
    // OnShow：当从外部页面（如支付宝用户中心）返回游戏时回调
    if (method == "GetLaunchOptions" || method == "OnShow")
    {
        var jsonData = JsonMapper.ToObject(result);
        // 是否展示设首任务。true：是，false：否。如果为true，要显示设首和复访任务；如果为false，则要隐藏设首和复访任务。
        bool gameCenterBackflow = (bool)jsonData["gameCenterBackflow"];
        // 是否已设首成功，true：是，false：否。如果为true，未领取过奖励的用户可以领取奖励；如果为false，则要引导用户跳转设首
        bool addHomepageResult = (bool)jsonData["addHomepageResult"];
        // 启动小游戏的场景值
        int scene = (int)jsonData["scene"];
        // 来源渠道，游戏中心：gamecenter。如果 sourceChannel 为 gamecenter，则复访任务完成，给用户发放奖励；如果未获取到 sourceChannel 字段，则向用户提示领取失败
        string sourceChannel = (string)jsonData["sourceChannel"];
        // 支付宝返回的原始数据
        string originalData = (string)jsonData["originalData"];

    } 
    else if (method == "GameClubButtonOnTap") // GameClubButtonOnTap：点击游戏圈按钮之后回调
    {

    }
    else if (method == "GetGameClubData") // GetGameClubData：当调用GetGameClubData后回调
    {
        // result格式：[{"value":1734418420, "dataType":1},{"value":0,"dataType":3},{"value":0,"dataType":4},{"value":0,"dataType":5},{"value":0,"dataType":6},{"value":0,"dataType":7},{"value":0,"dataType":8},{"value":0,"dataType":9}]
        // result 说明：
        /// 1：⽤户最新加⼊游戏圈的时间，秒级Unix时间戳（有加入游戏圈value才有值）
        /// 3：⽤户禁⾔状态，0：正常 1：禁言
        /// 4：当天(⾃然⽇)点赞贴⼦数
        /// 5：当天(⾃然⽇)评论贴⼦数
        /// 6：当天(⾃然⽇)发表贴⼦数
        /// 7：当天(⾃然⽇)发表视频贴⼦数
        /// 8：当天(⾃然⽇)赞官⽅贴⼦数
        /// 9：当天(⾃然⽇)评论官⽅贴⼦数

    }

};

支付宝游戏上报：

var jsonData = new JsonData();
jsonData["action_code"] = "xxx";
var json = jsonData.ToJson();
Nebula.NebulaSDKBridge.Instance.Call("Report", json);

报告游戏加载完成：

Nebula.NebulaSDKBridge.Instance.Call("ReportLoadingCompleted", "");

默认授权或主动授权完成时进⾏上报

Nebula.NebulaSDKBridge.Instance.Call("ReportAuthorized", "");

报告游戏⻆⾊创建完成，initial：是否是第⼀次创建⻆⾊进⼊（新⽤户）

var jsonData1 = new JsonData();
jsonData1["initial"] = true;
var json1 = jsonData1.ToJson();
Nebula.NebulaSDKBridge.Instance.Call("ReportGameCharacterCreated", json1);

报告成功进⼊游戏游玩界⾯

Nebula.NebulaSDKBridge.Instance.Call("ReportGamePlay", "");

报告自定义事件接口，设首复访上报时使用。eventId：事件名称

var jsonData = new JsonData();
jsonData["eventId"] = "xxx";
var json = jsonData.ToJson();
Nebula.NebulaSDKBridge.Instance.Call("ReportCustomEvent", json);

获取启动参数，必须在登录成功回调后调用

Nebula.NebulaSDKBridge.Instance.Call("GetLaunchOptions", "");

跳转设首任务

Nebula.NebulaSDKBridge.Instance.Call("SetHomePage", "");

跳转复访任务

Nebula.NebulaSDKBridge.Instance.Call("SetReturnVistPage", "");

游戏圈按钮，有其他疑问请参考游戏圈按钮官方文档

var param = new JsonData();
// 操作游戏圈按钮的方法。Show：显示游戏圈按钮，Hide：隐藏游戏圈按钮，Destroy：销毁游戏圈按钮
param["method"] = "Show";
// 必填，按钮类型。0：text类型，可以设置背景⾊和⽂本的按钮；1：image类型，只能设置背景贴图的按钮，背景贴图会直接拉伸到按钮的宽⾼
param["type"] = 1;
// 按钮文案。注意：type=“text”时必填
param["text"] = "xxx";
// 按钮的背景图⽚，仅当 type 为 image 时有效
param["image"] = "https://mdn.alipayobjects.com/paladin_unity/afts/img/1e7STKNyP1cAAAAAAAAAAAAADkqsAQBr/original";
// 必填，游戏圈按钮的图标，仅当 type 参数为 image 时有效。0:blue, 1:white, 2:dark, 3:light
param["icon"] = 1;
// 传游戏圈的圈⼦ID，进⼊到指定圈⼦下
param["openlink"] = "xxx";
// 按钮离屏幕左边距
param["left"] = 0;
// 按钮离屏幕上边距
param["top"] = 200;
// 按钮宽度
param["width"] = 50;
// 按钮⾼度
param["height"] = 50;
// 按钮背景颜⾊，格式为 6 位 16 进制数
param["backgroundColor"] = "#000000";
// 按钮边框颜⾊，格式为 6 位 16 进制数
param["borderColor"] = "#ffffff";
// 按钮边框宽度
param["borderWidth"] = 2;
// 按钮圆⻆幅度
param["borderRadius"] = 5;
// ⽂案颜⾊
param["color"] = "#ffffff";
// ⽂案对⻬⽅式
param["textAlign"] = 1;
// ⽂案字体⼤⼩
param["fontSize"] = 18;
var paramJson = param.ToJson();
Nebula.NebulaSDKBridge.Instance.Call("GameClubButton", paramJson);

获取游戏圈相关数据，对应回调：GetGameClubData，有其他疑问请参考：获取游戏圈数据官方文档

/// 需要获取的数据指标的对象数组：
/// 1：⽤户最新加⼊游戏圈的时间
/// 3：⽤户禁⾔状态
/// 4：当天(⾃然⽇)点赞贴⼦数
/// 5：当天(⾃然⽇)评论贴⼦数
/// 6：当天(⾃然⽇)发表贴⼦数
/// 7：当天(⾃然⽇)发表视频贴⼦数
/// 8：当天(⾃然⽇)赞官⽅贴⼦数
/// 9：当天(⾃然⽇)评论官⽅贴⼦数
int[] intArray = new int[] { 1, 3, 4, 5, 6, 7, 8, 9 };
string paramJson = JsonMapper.ToJson(intArray);
Nebula.NebulaSDKBridge.Instance.Call("GetGameClubData", paramJson);

调试说明

安装支付宝小游戏开发工具：打开控制台输入以下命令
```
npm install -g minidev@latest
```
导出工程：Unity菜单栏->"支付宝小游戏"插件，设置好信息，点击"生成并转换"
生成预览版：控制台cd到刚刚导出的目录中的"alipay"文件夹，输入以下命令（-a为应用ID）
```
minidev preview -a 206017xxx
```
测试预览版：确保你有加入支付宝小游戏开发者，打开支付宝扫一扫刚才生成的二维码，可以拉起游戏进行测试
参考文档：支付宝小游戏Unity文档->游戏预览和上传

发布说明

上传：控制台cd到刚刚导出的目录中的"alipay"文件夹，输入以下命令（-a为应用ID，-v为版本号）
```
minidev upload -a 206017xxx -v 0.0.1 --game
```
参考文档：支付宝小游戏Unity文档->游戏预览和上传

注意事项

设置服务器域名白名单：
1. 需要将星云SDK用到的域名添加到白名单，否则无法正常使用

gate-nebula.737.com
api-combine.feiyu.com
feishu-develop-tracker.cn-shanghai.log.aliyuncs.com

2. 需要将游戏用到的域名添加到白名单，否则无法正常请求。
3. 添加路径：控制台-开发设置-服务器域名白名单设置。添加完要重新打包，否则刚刚添加的白名单不生效。

内购测试：
1. 如果要测试内购功能，需要先开通虚拟支付，并添加uid白名单。
2. 如果添加完白名单还是无法拉起支付，可能需要重新打包生效。
3. 参考文档：支付宝小游戏内购介绍
激励视频广告测试：
1. 调试广告接口的时候，广告页面显示空白，属于正常现象，弹出页面就可以了。
2. 游戏对接时使用到的adUnitId不是广告配置中的"广告位id"，而是"spaceCode"！"spaceCode"获取路径：广告位管理-编辑-spaceCode。

设首、复访任务说明

设首任务对接流程：

设首任务

复访任务对接流程：

复访任务

设首复访任务测试需要添加白名单：商家平台运营中心 >选择小游戏 > 进入小游戏详情页 > 设首复访
有其他疑问请参考：
1. 设首复访应用案例请查看设首复访官方文档
2. 设首复访测试问题请查看设首复访常见问题

官方文档

华为小游戏

特殊接口

回调

Nebula.NebulaSDKBridgeCallback.Callback = (method, result) =>
{
// 创建桌面图标回调
if (method == "InstallShortcut")
{
    var jsonData = JsonMapper.ToObject(result);
    string status = jsonData.OptGetString("status");
    if (status == "success")
    {
        Debug.Log("创建桌面图标成功");
    }
    else
    {
        string msg = jsonData.OptGetString("message");
        Debug.Log(msg);
    }
} 
};

创建桌面图标接口

Nebula.NebulaSDKBridge.Instance.Call("InstallShortcut", "");

调试说明

下载安装华为小游戏开发者工具
导出工程：使用Unity导出WebGL工程，导出前要根据此文档的提示进行设置
使用开发者工具转换工程，参考文档：华为快游戏转换文档
真机测试：
1. 使用数据线将华为手机连接到电脑设备
2. 华为手机和开发者工具需登录同一个开发者账号，否则无法运行
3. 点击开始运行，会自动在手机安装宿主App，然后拉起运行快游戏

发布说明

导出rpk：华为小游戏开发者工具->构建->打包正式版本
发布rpk：华为小游戏开发者后台->我的应用->Android->你的游戏->分发->版本信息

注意事项

证书文件和密钥文件：
1. 生成：开发者工具->工具栏->工具->生成证书
2. 配置：需在华为开发者中心配置SHA256证书指纹，需配置刚刚生成证书时生成的Fingerprint
3. 证书配置：开发者工具所配置的证书，需与开发者中心配置的证书指纹对应，否则无法登录
4. 发布证书要保管好，丢失的话没法更新游戏!!!
激励视频广告测试：
1. 使用华为提供的测试的广告ID进行测试：teste7hm5vx799
2. 华为运营验收通过后，将测试ID替换为正式ID，正式ID需联系运营配置广告。
3. 参考文档：华为广告测试验证及上线
支付测试：
1. 需要在华为开发后台配置好商品，并在支付接口goodsId传入配置好的商品ID
2. 华为小游戏有提供沙盒测试，将开发者账号加入沙盒测试白名单，测试时无需真实支付

官方文档

OPPO小游戏

特殊接口

回调

Nebula.NebulaSDKBridgeCallback.Callback = (method, result) =>
{
// 创建桌面图标回调
if (method == "InstallShortcut")
{
    var jsonData = JsonMapper.ToObject(result);
    string status = jsonData.OptGetString("status");
    if (status == "success")
    {
        Debug.Log("创建桌面图标成功");
    }
    else
    {
        string msg = jsonData.OptGetString("message");
        Debug.Log(msg);
    }
} 
};

创建桌面图标

Nebula.NebulaSDKBridge.Instance.Call("InstallShortcut", "");

额外接入准备

因为OPPO一键转能力要使用到WXSDK，所以要先在工程中安装WXSDK插件：

打开 Unity工程 -> Window 菜单栏 -> Package Manager -> 左上方 “+” -> Add package from git URL
添加地址：https://gitee.com/wechat-minigame/minigame-tuanjie-transform-sdk.git
点击Add完成WXSDK导入

调试说明

调试准备：
1.OPPO设备下载安装"快应用"：下载地址

2.安装OPPO小游戏打包工具，命令行执行：
```
npm install @oppo-minigame/cli -g
```
导出工程：
1.如果有分包需求的，先使用"微信小游戏"插件进行分包操作
2.使用"微信小游戏"插件导出小游戏工程
将OPPO设备连接到电脑
使用OPPO的一键转功能进行转换，控制台cd到导出的minigame目录下，命令行执行：
```
quickgame transfer
```

一键转命令使用心得：

1.首次使用一键转命令，参考以下操作方式，以成配置文件目录：

###  初始化环境 ### 
###  检查微信小游戏工程 ### /Users/huangsy/Documents/plat_mobile/sniper/unity_nbgame_minigame/oppo2/build/minigame
### 选择转化方式 ### 
? 是否自动一键转化？ 否
? 是否需要对开放能力进行配置？
(若未配置，广告、登录、支付等能力可能无法使用，配置完成再重新转换) 否

2.再次使用一键转命令，参考以下操作方式，以设置好游戏的参数：

###  初始化环境 ### 
###  检查微信小游戏工程 ### /Users/huangsy/Documents/plat_mobile/sniper/unity_nbgame_minigame/oppo2/build/minigame
### 选择转化方式 ### 
? 是否自动一键转化？ 否
? 是否需要对开放能力进行配置？
(若未配置，广告、登录、支付等能力可能无法使用，配置完成再重新转换) 否
###  清理转化工程 ### 
###  构建转化工程 ### /Users/huangsy/Documents/plat_mobile/sniper/unity_nbgame_minigame/oppo2/build/minigame-oppo-transfer
### 逐项填写项目配置，默认建议转化后的 oppo 配置，否则建议微信配置，都不存在建议缺省值 ### 
? 请输入项目名称: NBGameOppo2
? 请输入包名
以英文句号分隔，以 .nearme.gamecenter 结尾，不能包含下划线以外的特殊符号，不能出现oppo字样，英文句号分隔的每一段以字母开头且不能以下划线结尾
com.feiyu.stepbystep.nearme.gamecenter
? 请输入版本名称(1.0.0, x.x.x): 1.0.0
? 请输入版本号(1, 2, 3...): 1
? 请输入最小平台版本(不小于 1139): 1139
? 请输入 icon 相对路径(/logo.png, /xxx/logo.png): /logo.png
### 其他配置自动迁移至 oppo ### 
设备方向: landscape
开放数据域: 无
分包: [ 'wasmcode', 'data-package' ]
appid: wx29a74f5209ca5509
插件: 暂不支持
隐私政策: 不使用
###  适配游戏引擎 ### 
? 当前不支持 es6 及部分 js 新语法特性，是否进行兼容转化
此操作较耗时，unity 游戏建议进行，其他游戏根据实际情况选择 是
###  完成兼容转化 ### 
###  注入 UnityPlugin ### 版本配置过高，使用最新支持版本 1.2.57
? 是否打正式包 否
### 开始打包流程 ### 
###  检查分包配置 ### 
###  构建分包 [wasmcode]: 完成 ### 
###  构建分包 [data-package]: 完成 ### 
###  构建主包: 完成 ### 
###  构建整包: 完成 ### 
###  构建总包: 完成 ### 
###  配置实用工具 ### 
###  安装小游戏 ### 已安装至设备 BUNBVS9X75WO6HD6

3.后续再使用一键转命令，"是否自动一键转化"的选项就可以一直选"是"了

一键转命令执行后，会自动安装小游戏到OPPO设备的"快应用"，点击"秒开"即可打开小游戏游戏
更具体的说明请查看OPPO一键转文档
查看调试日志：电脑和手机同一局域网，chrome浏览器内输入下面的url，IP换成你的手机局域网ip，端口从12345~12348，例如：

devtools://devtools/bundled/inspector.html?v8only=true&ws=192.168.0.3:12345/00010002-0003-4004-8005-000600070008

广告映射配置

OPPO一键转功能需配置微信广告id和OPPO广告id的映射关系，才能正常拉起广告。

在运行一键转命令之后，打开minigame-oppo-config/ad-info.json，配置微信广告和OPPO广告的映射，例：
```
{
"微信广告id1": {
    "id": "OPPO广告1"
},
"微信广告id2": {
    "id": "OPPO广告2"
}
}
```
在激励视频广告接口ShowRewardedVideoAd应传入微信的广告id

发布说明

打开minigame-oppo-config，创建sign/release目录，将事先准备好的certificate.pem、private.pem拷贝进去。（如果不准备证书文件，则一键转的时候会帮忙生成证书。如果是已上线的游戏，切记要使用原有的证书，否则无法正常更新!!!）
运行一键转命令，"是否自动一键转化"选项选择：否，"是否打正式包命令"选择：是，即可生成正式版rpk，生成目录在minigame-oppo-transfer/dist
包体发布请查看OPPO小游戏发布说明

注意事项

若调试器一直无法加载小游戏，可以先清一下调试器的缓存，操作步骤：快应用-游戏测试-清除数据-存储占用-清除数据，包体有更新要清除一次
激励视频广告测试：需到OPPO商务后台创建广告，获取到广告ID，参考文档
发布证书要保管好，丢失的话没法更新游戏!!!

官方文档

vivo小游戏

特殊接口

回调

Nebula.NebulaSDKBridgeCallback.Callback = (method, result) =>
{
// 创建桌面图标回调
if (method == "InstallShortcut")
{
    var jsonData = JsonMapper.ToObject(result);
    string status = jsonData.OptGetString("status");
    if (status == "success")
    {
        Debug.Log("创建桌面图标成功");
    }
    else
    {
        string msg = jsonData.OptGetString("message");
        Debug.Log(msg);
    }
} 
};

创建桌面图标

Nebula.NebulaSDKBridge.Instance.Call("InstallShortcut", "");

调试说明

vivo手机安装2个应用：vivo小游戏引擎、vivo小游戏调试器
转换小游戏并导出工程：Unity菜单栏->vivo小游戏->转换小游戏，根据游戏情况填写导出参数，点击"生成并转换"
生成调试二维码：Unity菜单栏->vivo小游戏->转换小游戏，点击"运行"，生成二维码
调试小游戏：vivo手机连接电脑，打开手机的小游戏调试器，点击"扫码安装"，扫描刚刚生成的二维码，即可拉起小游戏界面。
注：如果小游戏调试器找不到"扫描安装"按钮，请在设备上清除一下小游戏调试器的缓存
详细内容参考文档：转换工具导出vivo小游戏

发布说明

请查看vivo小游戏发布与上传

注意

如果修改完代码要重新调试，不需要关闭正在运行npm run server的窗口，可以在转换小游戏后，重新执行npm run build，并在小游戏调试器点击"在线更新"即可
发布证书要保管好，丢失的话没法更新游戏!!!

官方文档

美团小游戏

特殊接口

回调

Nebula.NebulaSDKBridgeCallback.Callback = (method, result) =>
{
    Debug.Log($"###Callback>>method:{method}>>result:{result}");
    // GetLaunchOptions：当调用GetLaunchOptions之后回调
    // OnShow：当从外部页面返回游戏时回调
    if (method == "GetLaunchOptions" || method == "OnShow")
    {
        var jsonData = JsonMapper.ToObject(result);
        // 能否展示一键订阅二楼任务。true：能，false：否。如果为true，则展示一键订阅二楼按钮。如果为false，则不展示。
        bool showEnable = (bool)jsonData["showEnable"];
        // 是否已订阅二楼。true：是，false：否。如果为true，未领取过奖励的用户可以领取奖励；如果为false，引导用户订阅。
        bool isSubscribe = (bool)jsonData["isSubscribe"];
        // 启动小游戏的场景值
        int scene = (int)jsonData["scene"];
        // 来源渠道参数
        string innerSource = (string)jsonData["innerSource"];
        // 是否为二楼复访。true：是，false：否。如果为true，则表示从二楼复访进入小游戏；如果为false，则表示不是从二楼复访进入小游戏。
        string fromSecondFloor = (bool)jsonData["fromSecondFloor"];
    } 
    else if (method == "UpdateSecondFloorChannel") // 一键订阅二楼回调
    {
        var jsonData = JsonMapper.ToObject(result);
        var status = (string)jsonData["status"];
        var message = (string)jsonData["message"];
        if (status == "success")
        {
            // 一键订阅二楼成功
        } 
        else
        {
            // 一键订阅二楼失败
        }

    } 
    else if (method == "CreateShortcut") // 添加桌面快捷方式回调
    {
        var jsonData = JsonMapper.ToObject(result);
        var status = (string)jsonData["status"];
        var message = (string)jsonData["message"];
        if (status == "success")
        {
            // 添加桌面快捷方式成功
        } 
        else
        {
            // 添加桌面快捷方式失败
        }
    }

};

角色上报接口

说明：
1. 每次创角动作结束之后进行一次上报
2. 每次切换服务区时进行一次上报
3. 每次退出游戏时进行一次上报

var jsonData = new JsonData();
// 创建时间，时间戳，eg: Date.now()，当创角上报时必传
jsonData["createTime"] = "1735553976";
// 服务区id，非必传
jsonData["serviceId"] = "1";
// 角色 id，必传
jsonData["roleId"] = "roleId1";
// 角色等级，必传
jsonData["level"] = "1";
Nebula.NebulaSDKBridge.Instance.Call("ReportMV", jsonData.ToJson());

添加快捷方式

说明：
1. 不支持重复添加
2. 回调回调的 CreateShortcut

JsonData jsonData = new JsonData();
// 快捷方式显示的名称，必传
jsonData["label"] = "NBDemo";
// 快捷方式跳转目标页面，必传，需要与美团的运营人员索取，否则无法正常打开
jsonData["target"] = "imeituan://www.meituan.com/mgc?mgc_id=mgctedrrftskcype&inner_source=11181_desk&query=inner_source%3D11181_desk&lch=mhqN_TW-u0kBgiK_vBi78KQNw&_page_new=1";
Nebula.NebulaSDKBridge.Instance.Call("CreateShortcut", jsonData.ToJson());

获取启动参数

说明：
1. 调用后回调 GetLaunchOptions

Nebula.NebulaSDKBridge.Instance.Call("GetLaunchOptions", "");

一键订阅二楼任务

说明：
1. 调用后回调 UpdateSecondFloorChannel

 Nebula.NebulaSDKBridge.Instance.Call("UpdateSecondFloorChannel", "");

游戏行为数据上报：

var jsonData = new JsonData();
jsonData["action_code"] = "xxx";
var json = jsonData.ToJson();
Nebula.NebulaSDKBridge.Instance.Call("Report", json);

调试说明

导出工程：Unity菜单栏->美团小游戏转换插件，导出小游戏工程
控制台执行命令安装调试工具：
```
npm i -g mgc-cli-external@latest
```
控制台执行命令生成 mgc.config.js配置文件（在导出目录执行）：
```
mgc config
```
控制台执行命令生成Debug测试二维码（在 mgc.config.js 的同级目录执行）：
```
mgc debug
```
iOS调试：
1. 使用正式版美团App扫码测试，App版本号要大于等于11.2.200
2. iOS需要使用特殊的URL生成二维码再进行扫码测试：
  1. 使用 mgc debug 命令生成二维码时会同时给出测试URL，在URL后面串上： &manualHorn=%7B%22structure%22%3A2%2C%22enableUnityGame_mgctedrrftskcype%22%3A1%7D
  2. 最终URL范例如下：
```
imeituan://www.meituan.com/mgc?mgc_id=mgctedrrftskcype&mgc_debug_version=1.1.37&debug=1&manualHorn=%7B%22structure%22%3A2%2C%22enableUnityGame_mgctedrrftskcype%22%3A1%7D
```
  3. 使用二维码生成工具（比如草料二维码）将以上URL转为二维码
Android调试：
1. 需要使用专用的美团测试APK，安装后扫描测试二维码进行测试，
具体调试说明请查看：美团小游戏官方文档->开发调试

发布说明

请查看：美团小游戏官方文档->开发调试->发布说明

一键订阅二楼、二楼复访说明

一键订阅二楼流程图：

一键订阅二楼流程图

二楼复访流程图：

二楼复访流程图

还未上架的游戏，若要测试二楼复访，需使用特殊的URL生成二维码测试：
1. 使用 mgc debug 命令生成二维码时会同时给出测试URL，在URL后面串上：&inner_source=11181_syxlel&query=inner_source%3D11181_syxlel。(iOS测试可以在iOS特殊地址基础上串上以上字符串)
2. 使用二维码生成工具将以上URL生产二维码
3. 扫码此二维码相当于就是从二楼进入
4. 最终URL范例如下：
```
imeituan://www.meituan.com/mgc?mgc_id=mgctedrrftskcype&mgc_debug_version=1.1.37&debug=1&manualHorn=%7B%22structure%22%3A2%2C%22enableUnityGame_mgctedrrftskcype%22%3A1%7D&inner_source=11181_syxlel&query=inner_source%3D11181_syxlel
```
测试二楼复访需添加白名单，添加方式：联系美团技术人员添加

分包说明

请查看：Unity 小游戏 WASM 分包工具使用说明

注意事项

需要在美团开发者后台配置商品id，并在支付接口goodsId传入配置好的商品ID
判断是否从桌面图标进入，需使用特殊的URL生成二维码测试：
1. 使用 mgc debug 命令生成二维码时会同时给出测试URL，在URL后面串上：&inner_source=111181_desk&query=inner_source%3D11181_desk
2. iOS测试可以在iOS特殊地址基础上串上以上字符串
3. 使用二维码生成工具将以上URL生产二维码
4. 扫码此二维码相当于就是从桌面图标进入
5. 最终URL范例如下：
```
imeituan://www.meituan.com/mgc?mgc_id=mgctedrrftskcype&mgc_debug_version=1.1.37&debug=1&manualHorn=%7B%22structure%22%3A2%2C%22enableUnityGame_mgctedrrftskcype%22%3A1%7D&inner_source=111181_desk&query=inner_source%3D111181_desk
```

官方文档

小米小游戏

特殊接口

回调

Nebula.NebulaSDKBridgeCallback.Callback = (method, result) =>
{
    // 添加桌面快捷方式回调，当调用CreateShortcut之后回调
    if (method == "CreateShortcut")
    {
        var jsonData = JsonMapper.ToObject(result);
        string status = jsonData.OptGetString("status");
        if (status == "success")
        {
            Debug.Log("创建桌面图标成功"); 
        }
        else
        {
            string msg = jsonData.OptGetString("message");
            Debug.Log("创建桌面图标失败：" + msg);
        }
    } 
    else if (method == "GetLaunchOptions") // 获取启动参数回调，当调用GetLaunchOptions之后回调
    {
        var jsonData = JsonMapper.ToObject(result);
        bool success = jsonData.OptGetBoolean("success");
        string queryType = jsonData.OptGetString("queryType");
        string appId = jsonData.OptGetString("appId");
        string package = jsonData.OptGetString("package");
        string type = jsonData.OptGetString("type");
        string useAnalyzer = jsonData.OptGetString("useAnalyzer");
    }
};

创建桌面图标

var param = new JsonData();
param["message"] = "是否创建桌面图标？";
Nebula.NebulaSDKBridge.Instance.Call("CreateShortcut", param.ToJson());

获取启动参数

Nebula.NebulaSDKBridge.Instance.Call("CreateShortcut", "");

调试说明

小米设备安装专用调试APP：
- 快应用服务框架
- 快游戏调试器
设备设置Unity Runtime环境，如果这步没有设置，在拉起游戏时会出现闪退的情况：
- 手机设置中搜索"快应用服务框架"，点击进去，一直点击"关于"按钮，直到底下出现"游戏引擎模式"，勾选"Unity Runtime"
- 联系小米小游戏的运营，为游戏开通"Unity Runtime"的白名单权限
导出工程，Unity菜单栏->小米快游戏插件，填写游戏信息：
- 包类型勾选：Debug
- Debug签名文件目录：该目录下要放置1个certificate.pem文件和1个private.pem
- 填写build.data和build.wasmCDN地址
- 导出小游戏工程
将导出的MiQGameBuild/Build 目录中的 build.data和build.wasm放到CDN
打开命令行工具，CD到MiQGameBuild/MiQGame目录，执行：
- 安装快游戏依赖包：npm install
- ⽣成debug包：npm run build
- 启动调试服务器，并生成调试二维码：npm run server
打开手机中安装好的快应用调试器，进行调试，有2种方式：
- 点击"扫码安装"，扫描命令行工具生成的二维码
- 手机连接数据线，点击"在线更新"
具体调试说明请查看：Unity转快游戏使⽤说明⽂档

发布说明

导出工程，Unity菜单栏->小米快游戏插件，填写游戏信息：
- 包类型勾选：Release
- Release签名文件目录：该目录下放置1个certificate.pem文件和1个private.pem（密钥要妥善保管，否则会影响游戏更新）
- 填写build.data和build.wasm 的CDN地址
- 导出小游戏工程
将导出的MiQGameBuild/Build 目录中的 build.data和build.wasm放到CDN
命令行工具，CD到MiQGameBuild/MiQGame目录，执行：
- 命令安装快游戏依赖包：npm install
- ⽣成release包：npm run release
- 生成的正式版rpk在MiQGameBuild/Build/dist目录下

注意事项

当前小米小游戏的激励视频广告，暂只支持使用1个adUnitId，使用多个adUnitId无法正常拉起广告
使用未实名的账号登录，没有拉起实名认证，请检查一下在小米后台创建游戏的时候，应用类型应该选择"游戏"，否则是无法拉起实名认证的

小游戏聚合SDK-Unity(C#)

文档修订记录

接入须知

接入准备

接口

初始化(必接)

登录(必接)

支付(必接)

激励视频广告(选接)

打开客服对话(选接)

获取配置参数(选接)

回调

初始化回调

登录回调

支付回调

激励视频广告回调

打开客服对话回调

渠道平台指引

支付宝小游戏

特殊接口

调试说明

发布说明

注意事项

设首、复访任务说明

官方文档

华为小游戏

特殊接口

调试说明

发布说明

注意事项

官方文档

OPPO小游戏

特殊接口

额外接入准备

调试说明

广告映射配置

发布说明

注意事项

官方文档

vivo小游戏

特殊接口

调试说明

发布说明

注意

官方文档

美团小游戏

特殊接口

调试说明

发布说明

一键订阅二楼、二楼复访说明

分包说明

注意事项

官方文档

小米小游戏

特殊接口

调试说明

发布说明

注意事项

官方文档

FAQ

初始化`(必接)`

登录`(必接)`

支付`(必接)`

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

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

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