文档修订记录
| 文档版本 | 文档更新日期 | 文档更新内容 |
|---|---|---|
| 3.3.58 | 2024.06.19 | 集成抖音小游戏 |
接入准备
1.下载对接资源：点我下载
2.将文件NebulaDouyin.unitypackage导入到您的Unity工程的Assets文件夹下。
3.从星云后台下载 'fy-config.json' ，拷贝到Untiy工程的'Assets/Resources'目录下。
4.下载安装抖音的BGDT插件并更新到最新版：下载地址。
5.通过BGDT插件，安装最新版"Stark SDK"、"StarkSDKUnityTools"插件：安装文档
接入须知
1.抖音小游戏支撑服务介绍， 点击进入
2.抖音小游戏渠道配置指引，点击进入
3.AccessToken 全局唯一处理，需要接入令牌服务，点击进入
4.服务端文档请查阅，点击进入
接口
初始化(必接)
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.说明
- 玩家需要登录时调用
- 登录后会回调登录回调，返回星云 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.说明
- 调用此接口将拉起支付界面，Android拉起内购界面，iOS拉起客服支付界面
- 支付后会回调客户端支付回调
- 服务端支付回调，需配置游戏服务端的支付回调地址，打开"星云平台->对接中心->SDK对接->SDK列表->基础接入参数->游戏支付回调地址"，支付完成后会通过此地址回调支付结果
- 支付流程请参考点我查看
- 可单独控制Android和iOS的支付模式，目前支持开启、关闭，配置路径：星云平台->对接中心->渠道打包->渠道配置->进入抖音小游戏渠道配置
3.调用范例
Nebula.NebulaSDKBridge.Instance.Pay(100, tradeNo, "1", "100钻石", "1", "1号玩家", "1", "1", "1", "1", 0, "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回调
请在游戏代码中，设置好的相应的委托方法，并编写游戏的回调逻辑。
统一返回对象格式如下：
| 属性名 | 说明 |
|---|---|
| status | 成功success、失败error |
| code | 响应状态码，根据不同状态进行处理和错误原因排查 |
| msg | 提示消息 |
| data | 返回值，响应结果不同请求数据格式参照方法说明文档 |
code统一错误码：
| 错误码 | 说明 |
|---|---|
| 10001 | 当前环境不支持 |
| 10002 | 未进行初始化调用 |
| 10003 | 未进行登录调用 |
| 10004 | 获取渠道配置 |
| 10005 | 创建聚合订单失败 |
| 10006 | 订单回调失败 |
| 10007 | 预创建订单失败 |
| 10008 | 创建扫码订单失败 |
| 10009 | 配置文件无法读取 |
| 20001 | 登录失败 |
| 30001 | 支付失败 |
| 30002 | 渠道支付配置关闭 |
| 30003 | 游戏币支付失败 |
| 30004 | 直购支付失败 |
| 30005 | 打开客服支付取消 |
| 30006 | 创建客服支付失败 |
| 30007 | 创建扫码支付失败 |
初始化回调
1.方法
Nebula.NebulaSDKBridgeCallback.InitCallback2.说明
- 初始化后会回调此方法，并返回配置参数
- 应在确保收到初始化成功回调后才能调用其他接口
3.参数
data参数：
| 参数 | 类型 | 说明 |
|---|---|---|
| nbAppId | string | 星云平台AppID |
| nbChannelId | string | 星云平台渠道ID |
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}");
if ("success".Equals(initInfo.status))
{
// 初始化成功
}
else
{
// 初始化失败
}
};登录回调
1.方法
Nebula.NebulaSDKBridgeCallback.LoginCallback2.说明
-
收到此回调的「登录成功」时，需将登录参数传到游戏服务器，再请求聚合服务端做登录校验，校验成功才算登录成功，具体校验方式请看服务端接入文档
-
游戏收到此回调的「登录失败」时，需向用户提供再次登录的按钮，以便用户能重新登录
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.PayCallback2.说明
- 收到此回调的「支付成功」通知时，不能马上发放道具，
游戏需要根据服务端的支付回调作为支付是否成功的依据，具体的服务端回调请看服务端接入文档 - 此回调只可以用来控制游戏界面显示，例如 loading 框的关闭、遮罩层的关闭
3.参数
data参数：
| 属性 | 类型 | 说明 |
|---|---|---|
| payType | int | 支付方式，1=原生支付、2=客服支付，支付成功状态success下，不同的支付方式最终结果都以服务端通知为基准由于客服支付模式已脱离了 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的接口和回调之后，打开"BuildTool"插件编译，然后使用"StartPublish"插件发布测试版本，最后使用抖音APP扫码进行测试,具体请参考抖音的构建文档和抖音的发布文档
FAQ
- 支付金额错误
支付金额单位是分，要进行转换