抖音小游戏SDK-Unity(C#)

文档修订记录

文档版本 文档更新日期 文档更新内容
3.3.82 2025.01.03 1.1.新增抖音公会群功能接口:「查询公会是否绑定公开群」、「绑定公会的公开群」、「解绑公会的公开群」、「加入公会的公开群」
3.3.80 2024.12.17 1.新增「直玩订阅」、「启动场景上报」接口,「进入前台事件」新增直玩相关参数
3.3.69 2024.10.09 1.新增「创建桌面快捷方式」接口
3.3.66 2024.09.14 1.新增「侧边栏复访」、「打开客服会话」接口
3.3.58 2024.06.19 1.集成抖音小游戏

接入准备

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

2.下载安装抖音的BGDT插件并更新到最新版:下载地址

3.通过BGDT插件,安装最新版"Stark SDK"、"StarkSDKUnityTools":安装文档

BGDT插件
StarkSDKUnityTools

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

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

接入须知

1.抖音小游戏支撑服务介绍, 点击进入

2.抖音小游戏渠道配置指引,点击进入

3.抖音小游戏服务端文档请查阅,点击进入

接口

  • 必接接口:游戏必须要接入
  • 选接接口:按照游戏发行需求来接入
  • 回调:某些接口有相应的回调游戏需要进行处理,具体请查看本文档的「回调」章节

初始化(必接)

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

5.回调方法

// 支付回调
Nebula.NebulaSDKBridgeCallback.PayCallback

侧边栏复访(必接)

1.方法

// <summary>
/// 打开侧边栏
/// 抖音侧边栏技术指南:https://developer.open-douyin.com/docs/resource/zh-CN/mini-game/develop/guide/open-ability/sidebar/Introduction-for-tech
/// 抖音侧边栏介绍:https://developer.open-douyin.com/docs/resource/zh-CN/mini-game/operation1/ability/-retention/sidebar
/// 抖音侧边栏SDK文档:https://developer.open-douyin.com/docs/resource/zh-CN/mini-game/develop/guide/game-engine/rd-to-SCgame/unity-game-access/sc_stark_sdk#215b9294
/// </summary>
/// <param name="success">打开成功回调</param>
/// <param name="fail">打开失败回调</param>
public void NavigateToSideBar(Action success = null, Action<int, string> fail = null)

2.说明

  • 作用:游戏需要引导用户从首页侧边栏进入游戏,养成首页侧边栏快速访问小游戏的心智,通过侧边栏留存的提升,带动小游戏大盘整体留存提升

  • 注意事项:​此能力是抖音的「必接审核」,未接入该能力的小游戏在「新游首发」&「版本更新」环节会有「拒审」风险

  • 接入介绍:

    • 游戏在调用初始化接口之前,要先监听OnShow回调,作用是监听小游戏回到前台的事件,例如游戏首次打开或者从侧边栏进入游戏,都会执行此回调;此回调会通过参数告知游戏:(1)宿主是否支持侧边栏,如果宿主支持侧边栏,游戏可通过NavigateToSideBar方法打开侧边栏 (2)是否从侧边栏启动,游戏根据这个参数确定是否发放奖励
    • 具体流程请参考如下流程图:
      侧边栏复访流程
    • 方案示意:
      侧边栏复方案示意
  • 测试介绍:

    • 根据抖音侧边栏技术指南的测试流程中的"方案3"提供的测试步骤进行测试(方案1、方案2不支持Unity游戏)
    • 注意:上线过的游戏侧边栏才会显示游戏图标,未上线的游戏侧边栏没有游戏图标,要按照方案3的提示,找客服开白名单
  • 更多介绍:

3.调用范例

Nebula.NebulaSDKBridge.Instance.NavigateToSideBar(() => {
    Debug.Log("###打开侧边栏成功");
}, (errCode, errMsg) => {
    Debug.Log("###打开侧边栏失败");
});

4.参数说明

5.回调方法

// 监听小游戏回到前台的事件
Nebula.NebulaSDKBridgeCallback.OnShow 

打开客服会话(选接)

1.方法

/// <summary>
/// 打开客服页​
/// 小6客服介绍文档:https://developer.open-douyin.com/docs/resource/zh-CN/mini-game/operation1/ability/user-service/customer-service-introduce
/// 抖音IM客服介绍文档:https://developer.open-douyin.com/docs/resource/zh-CN/mini-game/operation1/ability/user-service/douyinIM
/// 抖音客服SDK文档:https://developer.open-douyin.com/docs/resource/zh-CN/mini-game/develop/guide/game-engine/rd-to-SCgame/unity-game-access/sc_stark_sdk#d40c332e
/// </summary>
/// <param name="type">1:小6客服;2:抖音IM 客服(仅支持抖音)</param>
/// <param name="action">打开回调:true-打开成功;false-打开失败</param>
public void OpenCustomerServiceConversation(int type, Action<bool> action = null)

2.说明

3.调用范例

  • 打开小6客服
Nebula.NebulaSDKBridge.Instance.OpenCustomerServiceConversation(1, (success) => {
    Debug.Log($"###打开小6客服>>success:{success}");
});
  • 打开抖音IM客服
Nebula.NebulaSDKBridge.Instance.OpenCustomerServiceConversation(2, (success) => {
    Debug.Log($"###打开抖音IM客服>>success:{success}");
});

4.参数说明

5.回调方法

创建桌面快捷方式​(选接)

1.方法

/// <summary>
/// 创建桌面快捷方式​
/// </summary>
/// <param name="action">创建回调:true-成功;false-失败</param>
public void CreateShortcut(Action<bool> action = null)

2.说明

3.调用范例

Nebula.NebulaSDKBridge.Instance.CreateShortcut((isSuccess) => {
    Debug.Log($"###创建桌面快捷方式​>>isSuccess:{isSuccess}");
});

4.参数说明

5.回调方法

直玩订阅​(选接)

1.方法

/// <summary>
/// 直玩订阅
/// 向用户请求授权,允许游戏在满足一定的条件后出现在推荐流中
/// </summary>
/// <param name="scene">订阅的场景ID。1:离线收益场景​;2:体力恢复场景​;3:重要事件掉落​</param>
/// <param name="contentIDs">自定义文案ID</param>
/// <param name="action">isSuccess:用户的订阅结果(true为成功,false为订阅失败);message:回调信息 ​ ​</param>
public void RequestFeedSubscribe(int scene, string[] contentIDs, Action<bool, string> action = null)

2.说明

  • 作用:弹出直玩订阅弹窗,向用户请求授权直玩订阅
  • 直玩订阅流程:
    • 1.游戏客户端调用"直玩订阅接口(RequestFeedSubscribe)",完成订阅
    • 2.抖音服务端通过星云GM向游戏服务端请求用户就绪场景列表,以确认该用户已准备就绪
    • 3.抖音预加载游戏,并且游戏客户端收到"进入前台事件回调(OnShow)",游戏判断直出场景和对应场景值,并跳转到对应场景
    • 4.游戏客户端调用"启动场景上报接口(ReportScene)",通知抖音已经准备就绪,抖音推荐流中显示出游戏
      直玩订阅流程
  • 星云GM对接文档:获取抖音用户已就绪场景列表
  • 测试流程及注意点:
    • 扫码添加白名单,添加路径:抖音开放平台->运营->运营能力->推荐流直出游戏能力->联调测试->调试设备->添加设备
    • 开启调试模式,开启路径:抖音客户端->我->右上角"三"->更多功能->开发者模式->打开开发者模式。如果"更多功能"里找不到开发者模式,请重启一下抖音客户端
    • 调用直玩订阅接口,拉起直玩订阅授权弹窗,确保该用户已完成授权直玩订阅
    • 开始在抖音客户端刷推荐视频,这时要留意服务端有没有收到场景就绪的请求,如果服务端返回场景已就绪,则刷视频的时候会开始提示加载游戏,此时再继续刷若干个视频就会显示游戏页面
    • 如果一直刷不出游戏,排查以下几个点:
      • 确认该设备已加入白名单
      • 确认该用户是否完成直玩订阅
      • 确认服务端已返回该用户场景已就绪
      • 确认客户端场景加载完成后有调用ReportScene接口
      • 确认抖音客户端是否已更新到最新版(32.4.0以上)
      • 确认不是在太旧的手机设备上测试,最好是在较新款的设备上测试(例如iPhoneSE就刷不出游戏)
    • 注意"离线收益场景"和"重要事件掉落场景"一定要通过测试,包括取消订阅、订阅弹窗以及刷出来,否则无法通过抖音的测试报告检查。测试报告检查路径:抖音开放平台->运营->运营能力->推荐流直出游戏能力->测试报告检查
  • 如有其他疑问,请查看抖音小游戏官方文档:

3.调用范例

string[] contentIDs = new string[] { "CONTENT531151111" };
Nebula.NebulaSDKBridge.Instance.RequestFeedSubscribe(1, contentIDs, (isSuccess, message) => {
    Debug.Log($"###订阅直出结果>>isSuccess:{isSuccess}>>message:{message}");
});

4.参数说明

参数 类型 默认值 说明 必传
scene int - 订阅的场景ID。1:离线收益场景​;2:体力恢复场景​;3:重要事件掉落
contentIDs string - 自定义文案ID。配置路径:抖音开放平台->运营能力->推荐流直出游戏能力->接入申请->方案提报->content_id
action object - 回调订阅情况。isSuccess:用户的订阅结果(true为成功,false为订阅失败);message:回调信息 ​

5.回调方法

启动场景上报接口​(选接)

1.方法

/// <summary>
/// 启动场景上报接口
/// 向平台侧传达游戏场景加载完成、达到可交互状态的时机
/// </summary>
/// <param name="param">sceneId:场景ID,int类型(直玩场景传7001);costTime:场景耗时,单位 ms long类型</param>
/// <param name="action">isSuccess:上报结果(true为成功,false为失败);message:回调信息 ​ ​</param>
public void ReportScene(JsonData param, Action<bool, string> action = null)

2.说明

3.调用范例

var param = new TTSDK.UNBridgeLib.LitJson.JsonData();
param["sceneId"] = 7001; // 固定值,直玩场景必须传7001
param["costTime"] = 1000;
Nebula.NebulaSDKBridge.Instance.ReportScene(param, (isSuccess, message) => {
    Debug.Log($"###上报结果>>isSuccess:{isSuccess}>>message:{message}");
});

4.参数说明

参数 类型 默认值 说明 必传
sceneId int - 固定值,直玩场景必须传7001
costTime long - 场景耗时,单位 ms
action object - 回调上报情况。isSuccess:用户的订阅结果(true为成功,false为订阅失败);message:回调信息 ​

5.回调方法

查询公会是否绑定公开群​(选接)

1.方法

/// <summary>
/// 查询公会是否绑定公开群
/// </summary>
/// <param name="unionId">公会ID,格式限制为字母数字下划线,长度不超过 30</param>
/// <param name="action">
///     bindStatus:公会的绑定状态。true:公会已绑定,false:公会未绑定
///     message:回调信息
/// </param>
public void GetUnionGroupInfo(string unionId, Action<bool, string> action = null)

2.说明

3.调用范例

Nebula.NebulaSDKBridge.Instance.GetUnionGroupInfo(UnionId, (bindStatus, message) => {
    Debug.Log($"###公会绑定状态>>bindStatus:{bindStatus}>>message:{message}");
    if(!bindStatus)
    {
        Debug.Log($"###公会未绑定");
    } else
    {
        Debug.Log($"###公会已绑定");
    }
});

4.参数说明

参数 类型 默认值 说明 必传
unionId string - 公会ID,格式限制为字母数字下划线,长度不超过 30

绑定公会的公开群​(选接)

1.方法

/// <summary>
/// 绑定公会的公开群
/// </summary>
/// <param name="unionId">公会ID,格式限制为字母数字下划线,长度不超过 30</param>
/// <param name="action">
///     bindResult:绑定结果。true:完成绑定,false:未绑定
///     message:回调信息
/// </param>
public void BindUnionGroup(string unionId, Action<bool, string> action = null)

2.说明

3.调用范例

Nebula.NebulaSDKBridge.Instance.BindUnionGroup(UnionId, (bindResult, message) => {
    Debug.Log($"###公会绑定结果>>bindResult:{bindResult}>>message:{message}");
});

4.参数说明

参数 类型 默认值 说明 必传
unionId string - 公会ID,格式限制为字母数字下划线,长度不超过 30

解绑公会的公开群(选接)

1.方法

/// <summary>
/// 解绑公会的公开群
/// </summary>
/// <param name="unionId">公会ID,格式限制为字母数字下划线,长度不超过 30</param>
/// <param name="action">
///     unbindResult:解绑结果。true:完成解绑,false:解绑失败
///     message:回调信息
/// </param>
public void UnbindUnionGroup(string unionId, Action<bool, string> action = null)

2.说明

3.调用范例

Nebula.NebulaSDKBridge.Instance.UnbindUnionGroup(UnionId, (unbindResult, message) => {
    Debug.Log($"###公会解绑结果>>unbindResult:{unbindResult}>>message:{message}");
});

4.参数说明

参数 类型 默认值 说明 必传
unionId string - 公会ID,格式限制为字母数字下划线,长度不超过 30

加入公会的公开群(选接)

1.方法

/// <summary>
/// 加入公会的公开群
/// </summary>
/// <param name="unionId">公会ID,格式限制为字母数字下划线,长度不超过 30</param>
/// <param name="action">
///     joinResult:加入结果。true:加入成功,false:加入失败
///     message:回调信息
/// </param>
public void JoninUnionGroup(string unionId, Action<bool, string> action = null)

2.说明

3.调用范例

Nebula.NebulaSDKBridge.Instance.JoninUnionGroup(UnionId, (joinResult, message) => {
    Debug.Log($"###公会加入结果>>joinResult:{joinResult}>>message:{message}");
});

4.参数说明

参数 类型 默认值 说明 必传
unionId string - 公会ID,格式限制为字母数字下划线,长度不超过 30

获取配置参数(选接)

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;

回调

请在游戏代码中,设置好的相应的委托方法,并编写游戏的回调逻辑。

统一返回对象格式如下:

属性名 说明
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.InitCallback

2.说明

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

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

  • 收到此回调的「支付成功」通知时,不能马上发放道具,游戏需要根据服务端的支付回调作为支付是否成功的依据,具体的服务端回调请看服务端接入文档
  • 此回调只可以用来控制游戏界面显示,例如 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
    {
        // 支付失败
    }
};

进入前台事件

1.方法

Nebula.NebulaSDKBridgeCallback.OnShow

2.说明

  • 作用:监听小游戏进入前台的事件,例如游戏首次打开或者从侧边栏进入游戏,都会执行此回调
  • 参数说明:(1)supportSideBar,宿主是否支持侧边栏,游戏根据此参数确定是否展示侧边栏 (2)fromSideBar,是否从侧边栏启动,游戏根据此参数确定是否发放奖励

3.参数

  • status:统一返回"success"

  • data参数:

属性 类型 说明
supportSideBar bool 宿主是否支持侧边栏,true:宿主支持侧边栏,false:宿主不支持侧边栏
fromSideBar bool 是否从侧边栏进入,true:是,false:否
isFeedGameScene bool 是否推荐流直出场景,true:是,false:否
feedGameScene int 推荐流直出的具体场景值。1:离线收益场景,2:体力恢复场景​,3:重要事件掉落​ ​
feedGameExtra string 推荐流直出的开发者自定义字段,对应游戏服务端回传的extra字段,请查看GM文档获取抖音用户已就绪场景列表

4.使用方法

Nebula.NebulaSDKBridgeCallback.OnShow = (info) =>
{
    LogManager.Instance.Add("###OnShow>>status:" + info.status + ">>code:" + info.code + ">>msg:" + info.msg + ">>supportSideBar:" + info.data.supportSideBar + ">>fromSideBar:" + info.
                        data.fromSideBar + ">>isFeedGameScene:" + info.data.isFeedGameScene + ">>feedGameScene:" + info.data.feedGameScene + ">>feedGameExtra:" + info.data.feedGameExtra);

};

导出测试

FAQ

  • 支付金额错误

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