聚合渠道SDK-Unity&Harmony

文档修订记录

文档版本	文档更新日期	文档更新内容
3.3.55	2024.04.28	初版
3.3.61	2024.07.26	新增页面生命周期接口和回调

接入准备

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

2.在团结引擎工程的Assets中导入UnityHarmonyFYSDK.package。

3.打开菜单栏的 HMSSeting - EditHMSSeting，修改配置参数

参数	类型	说明	是否必填
client_id	string	登录AppGallery Connect平台，我的项目>项目设置>常规>应用>APP ID	是
app_id	string	登录AppGallery Connect平台，我的项目>项目设置>常规>应用>Client ID	是
bundle_name	string	登录AppGallery Connect平台，我的项目>项目设置>常规>应用>包名	是
FY_GAME_APPID	string	星云开放平台>对接中心>SDK列表>App ID	是
FY_GAME_APPKEY	string	星云开放平台>对接中心>SDK列表>App Key	是
FY_GAME_CHANNELID	string	星云开放平台>对接中心>渠道打包>渠道配置>渠道ID	是
FY_GAME_ORIENTATION	string	横屏：0；竖屏：1	是
FY_GAME_COMPANYID	string	星云开放平台>对接中心>SDK列表>Company ID	是
FY_GAME_ENVIRONMENT	string	不填	否

接口

引入命名空间：

using FYSDK;

要调用星云的聚合渠道SDK接口，主要使用以下方法：

public void CallFunc(string funcName, string paramsJson)

参数	类型	说明	是否必填
funcName	string	SDK的接口名称	是
paramsJson	string	接口参数，JSON字符串	是

初始化`(必接)`

1.说明

游戏需要在刚启动游戏的时候调用。

2.调用范例

Dictionary<string, string> paramsDict = new Dictionary<string, string>();
paramsDict["gameVersion"] = "x.x.x";
string paramsJson = JsonMapper.ToJson(paramsDict);

FYCombine.Instance.CallFunc("doInit", paramsJson);

3.参数说明

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

4.回调方法

doInit

登录`(必接)`

1.说明

启动完游戏显示首页时调用。
玩家点击游戏界面的「进入游戏」时，需要判断是否有登录成功，如有则可以进入游戏；否则再次调用登录接口，让玩家重新登录，直到登录成功。

2.调用范例

FYCombine.Instance.CallFunc("doLogin", "");

3.参数说明
无

4.回调方法

doLogin

支付`(选接)`

1.说明

调用此接口将拉起支付界面
建议游戏制定的商品标识格式为：com.feiyu.app_id.xxxx，以保证商品 id 的唯一性
打开"星云平台->对接中心->SDK对接->SDK列表->基础接入参数->游戏支付回调地址"，配置游戏服务端的支付回调地址，支付完成后会通过此地址回调支付结果
客户端的支付回调不能作为支付成功的依据，不能在此处发放道具。判断支付是否成功要根据服务端的支付回调。具体的服务端回调请看服务端接入文档
客户端的支付回调只可以用来控制游戏界面显示，例如loading框的关闭、遮罩层的关闭
商品ID需要配置到华为后台，才能拉起支付

2.调用范例

Dictionary<string, string> paramsDict = new Dictionary<string, string>();
paramsDict["playerId"] = "xxx";
paramsDict["playerName"] = "xxx";
paramsDict["playerLevel"] = "1";
paramsDict["vipLevel"] = "1";
paramsDict["serverId"] = "1";
paramsDict["serverName"] = "xxx";
paramsDict["goodsId"] = "xxx.xxx.xxx";
paramsDict["goodsName"] = "xxx";
paramsDict["payAmount"] = "100";
paramsDict["gameOrderId"] = "xxx";
paramsDict["notifyExt"] = "";
paramsDict["paySignType"] = "md5";
paramsDict["notifyURL"] = "";
string paramsJson = JsonMapper.ToJson(paramsDict);

FYCombine.Instance.CallFunc("doPay", paramsJson);

3.参数说明

参数	说明	是否必传
playerId	玩家ID。对应服务端支付回调的`player_id`参数	是
playerName	玩家名字	是
playerLevel	玩家等级，`数字格式`	是
serverId	服务器ID，`数字格式` 。对应服务端支付回调的`server_id`参数	是
serverName	服务器名字	是
goodsId	商品标识，建议格式：com.feiyu.app_id.xxxx，例：com.feiyu.20001.store1 。对应服务端支付回调的`goods_id`参数	是
goodsName	商品名称	是
payAmount	支付金额，单位：分（海外游戏传美分），`数字格式`。对应服务端支付回调的`total_amount`参数	是
gameOrderId	游戏订单号，由游戏生成并管理。服务端支付回调会回传，游戏需进行唯一性校验，防止重复下发商息给玩家。字符串类型，50个字符内。对应服务端支付回调的`out_trade_no`参数	是
paySignType	签名类型，游戏服务器接收回调通知签名方式，需要游戏传递:md5/rsa	是
vipLevel	vip等级，`数字格式`，如果游戏没有vip等级则传"0"	否
notifyExt	额外参数，游戏的透传参数可通过此参数传递，支付完成后平台服务端会回调此参数给游戏服务端。对应服务端支付回调的`notify_ext`参数	否
notifyURL	1.通过该值能在客户端动态传递服务端支付回调地址；2.若您在客户端传递了该地址，则支付完成后会通过此地址回调支付结果；3.若您同时也在星云后台配置了支付回调地址，会优先回调客户端传递的地址；4.需要先配置支付回调可信域名，请前往"星云后台->对接中心->回调配置->支付回调可信域名"进行配置，否则无法回调成功；5.若您在客户端传递了该地址，在游戏包体发布之前，建议您仔细检查该参数是否配置正确，以防止包体发布后支付出现问题	否

4.回调方法

doPay

切换账号`(必接)`

1.说明

在需要切换账号时调用，该接口会弹出登录窗口，让用户重新登录
与「登录接口」不同的是，「登录接口」非首次登录会自动登录，而此接口必定会弹出登录窗口

2.调用范例

FYCombine.Instance.CallFunc("doSwitchAccount", "");

3.参数说明
无

4.回调方法

doSwitchAccount

用户中心`(必接)`

1.说明

需在游戏内的设置界面，放置一个「用户中心」按钮，点击按钮调用此接口
调用此接口将弹出用户中心界面

2.调用范例

FYCombine.Instance.CallFunc("doUserCenter", "");

3.参数说明
无

4.回调方法
无

登出`(选接)`

1.说明

登出 SDK，并回调登出回调给游戏

2.调用范例

FYCombine.Instance.CallFunc("doLogout", "");

3.参数说明
无

4.回调方法

doLogout

第三方收集信息`(选接)`

1.说明

用于收集第三方SDK收集游戏数据。
如果有出"鸿蒙"渠道，请对接此接口，否则上架渠道会被拒。

2.调用范例

Dictionary<string, string> paramsDict = new Dictionary<string, string>();
paramsDict["method"] = "xxx"; //method （进入区服：enterServer，创建角色：createRole ，角色升级：levelUp）
paramsDict["playerId"] = "xxx"; //角色ID
paramsDict["playerName"] = "xxx"; //角色名称
paramsDict["playerLevel"] = "xxx"; //角色等级
paramsDict["serverId"] = "xxx"; //区服ID
paramsDict["serverName"] = "xxx"; //区服名称
paramsDict["playerTime"] = "xxx"; //角色创建时间，必须取服务端时间，必须为时间戳

string paramsJson = JsonMapper.ToJson(paramsDict);
FYCombine.Instance.CallFunc("doCollectInfo", paramsJson);

3.参数说明

参数	说明	是否必传
method	进入区服：enterServer，创建角色：createRole ，角色升级：levelUp	是
playerId	角色ID	是
playerName	角色名称	是
playerLevel	角色等级，`数字格式`	是
serverId	区服ID，`数字格式`	是
serverName	区服名称	是
playerTime	角色创建时间，必须取服务端时间，必须为时间戳	是

4.回调方法
无

回调

引入命名空间：

using FYSDK;

对接范例：

FYCombine.CallbackAction = (funcName, resultJson) =>
{
    Debug.Log($"###CallbackAction>>funcName:{funcName}>>resultJson:{resultJson}");
    if (funcName == "doInit")
    {
        Debug.Log("###初始化回调");

        // 初始化回调
        // 游戏应在确保收到此回调后才能调用聚合渠道模块的其他接口
        // 游戏不需管是否初始化成功，只要关心有没有收到初始化回调即可，也不需要重新调用初始化，SDK内部自己会处理初始化失败的情况
    }
    else if (funcName == "doLogin")
    {
        Debug.Log("###登录回调");

        // 收到此回调的「登录成功」时，需将登录参数传到游戏服务器，再请求聚合服务端做登录校验，校验成功才算登录成功，具体校验方式请看[服务端接入文档](https://help.737.com/archives/docs/detail/channel_combine/sdk/server)
        // 游戏收到此回调的「登录取消」或「登录失败」时，需向用户提供再次登录的按钮，以便用户能重新登录
        // 假如在游戏正在进行中，收到此回调的「登录成功」通知时，并且 open_id 变了，此时需要退出到登录首屏，切换成另外一个角色，并重新进入游戏
    }
    else if (funcName == "doPay")
    {
        Debug.Log("###支付回调");

        // 此回调不能作为支付成功的依据，故游戏不能在此处发放道具，游戏需要根据服务端的支付回调作为支付是否成功的依据，具体的服务端回调请看「服务端接入文档」https://help.737.com/archives/docs/detail/channel_combine/sdk/server
        // 此回调只可以用来控制游戏界面显示，例如 loading 框的关闭、遮罩层的关闭
    }
    else if (funcName == "doSwitchAccount")
    {
        Debug.Log("###切换账号回调");

        // 与登录回调的处理方式一致
    }
    else if (funcName == "doLogout")
    {
        Debug.Log("###退出回调");

        // 点击用户中心里面切换账号按钮主动触发
        // 游戏在此处判断是否在游戏内，如果在游戏内则退出到登录首页
        // 初始化后设置回调监听
    }
    else if (funcName == "onBackPress")
    {
        Debug.Log("###侧滑返回");

        // 在应用中侧滑返回时触发
    }
    else if (funcName == "onPageShow")
    {
        Debug.Log("###页面显示");

        // 应用页面显示时触发

    }else if (funcName == "onPageHide")
    {
        Debug.Log("###页面隐藏");

        // 应用页面隐藏时触发
        // 比如退到后台
    }
};

回调参数：

参数	说明
funcName	回调的方法名，通过此参数区分是哪个方法回调过来的
resultJson	回调的数据信息，为JSON格式，需要自行解析

resultJson 统一格式如下：

属性名	说明
status	状态码，Int格式
message	提示消息，String格式
dataMap	回调参数，字典格式

status 状态码说明(除以下给出的状态码之外，若有返回其他状态码均可以认为是失败状态)：

错误码	说明
0	成功
10002	登录取消
11003	取消支付
11005	第三方渠道没有给明确的客户端支付状态，建议游戏提示“如若购买成功，稍后即到账”类似的不是很明确的提示

各个回调方法的 dataMap 参数说明：

doInit：

参数	类型	说明
device_id	string	设备ID，此 ID 为 SDK 生成的标识设备的唯一ID，卸载重装后会重置
app_id	string	星云APP ID
channel_id	string	星云渠道ID，如果游戏要对渠道做差异化处理时，可以使用此ID作为区分；渠道ID列表，请查看星云平台->对接中心->渠道打包->渠道配置；
passport_code	string	通行证标识，用来标明该渠道用什么通行证进行登录，如果游戏要对不同通行证做差异化处理时，可以使用此标识作为区分，例如：feiyu3、uc、yingyongbao，所有渠道的通行证标识请看渠道版本信息
payment_code	string	支付标识，用来标明该渠道用什么支付方式，一般和通行证代号一致，有一些特殊的渠道登录和支付不一致，例如：苹果渠道，登录是飞鱼通行证(feiyu3)，支付则是苹果支付(apple)，所有渠道的支付标识请看渠道版本信息

doLogin：

参数	类型	说明
open_id	string	游戏维度唯一用户ID，一般游戏只用到openId即可
platform	string	星云APP ID
payment_code	string	支付标识
channel_id	string	渠道ID
token	string	登录校验码，有效时间 7天，请在有效时间内完成校验，如超出时间需重新调用登录接口获取新校验码
passport_code	string	通行证标识
union_id	string	全渠道唯一用户ID
identity_age	string	身份证年龄（有可能空）
identity_birthday	string	身份证生日，格式:"1991-12-31"（有可能空）
user_id	string	第三方用户ID

doPay：

参数	类型	说明
order_id	string	星云订单号
game_order_id	string	游戏订单号

doSwitchAccount：

与doLogin回调参数一致

doLogout：

无回调参数

导出测试

参考此文档，配置好团结引擎的鸿蒙环境
在Unity工程对接好SDK的接口和回调之后，打开菜单栏 File - Build Settings，切换 Platform 为 OpenHarmony，点击Export导出鸿蒙 DevEco Studio 工程
在 DevEco Studio 工程中配置好证书后，运行到纯血鸿蒙设备中进行测试

聚合渠道SDK-Unity&Harmony

文档修订记录

接入准备

接口

初始化(必接)

登录(必接)

支付(选接)

切换账号(必接)

用户中心(必接)

登出(选接)

第三方收集信息(选接)

回调

引入命名空间：

对接范例：

各个回调方法的 dataMap 参数说明：

导出测试

FAQ

初始化`(必接)`

登录`(必接)`

支付`(选接)`

切换账号`(必接)`

用户中心`(必接)`

登出`(选接)`

第三方收集信息`(选接)`