SDK对接文档

主题

前置准备 ​

1. 安装tiktok ​

43.1.0版本，如果谷歌商店版本高于此版本就使用谷歌商店版本

渠道官方文档的栏目2.1可能会更新调试APP，请先行查看

2. 注册tiktok账号 ​

  1. 拔掉手机的电话卡

  2. 开vpn,节点选择美国或者日本

  3. 进tiktok app注册账号

3. 安装命令行工具（仅用于本地调试） ​

打开终端，安装命令行工具（如果不进行本地调试可以不装） ​

  • 前置需求：nodeJs 20+

java
npm install @ttmg/cli@latest -g

4. TIKTOK扫码方式 ​

项目构建 ​

4.1 构建时发布平台选字节跳动小游戏 ​

4.2 填入appId ​

这里的appId与Client key一致。

tiktok开放平台获取client key

填入构建面板

必接功能 ​

::: waring

具体游戏内接入需求请咨询对接运营，交互逻辑实现可参考以下

:::

添加到桌面 ​

  1. 需求细节及交互参考官方文档 TikTok Mini Game All in One // TikTok小游戏一站式接入指南2.0

  2. 接口小游戏SDK进行了封装，主要使用两个接口addDesk(添加到桌面)和getShortcutMissionReward（是否可以领取添加桌面的奖励，添加桌面领奖只根据这个接口来，我们不需要关注是否添加成功或是否从桌面进入），详细使用见下面的接口说明

侧边栏 ​

  1. 需求细节及交互参考官方文档 TikTok Mini Game All in One // TikTok小游戏一站式接入指南2.0

  2. 接口也是进行了封装，提供两个主要接口toSidebar(跳转到侧边栏引导复访)和getEntranceMissionReward(是否可以领取侧边栏奖励，我们发奖只根据这个接口回调入参来就行)，详细使用见接口说明

广告说明 ​

目前渠道暂时支持激励视频，但可用激励视频接口来做插屏设计。具体变现方案请与对接运营对齐。

接口说明 ​

添加桌面相关 ​

GameHelper.AddDesk.addDesk ​

描述 ​

添加到桌面

参数 ​

属性名类型默认值是否必填说明
callback(isSuc:boolean)=>void/是回调，回调参数只能判断添加桌面接口调用是否成功，无法判断添加是否成功，我们也无需要关注

示例 ​

javascript
GameHelper.AddDesk.addDesk((res)=>{
            console.log("调用接口结果",res);
        })

GameHelper.AddDesk.getShortcutMissionReward ​

描述 ​

获取是否能发放添加桌面奖励结果

参数 ​

属性名类型默认值是否必填说明
success(canReceive:boolean)=>void/是调用成功回调，canReceive用来判断是否可以发放奖励
fail(err)=>void/否调用失败回调
complete()=>void/否接口调用完成回调

示例 ​

javascript
GameHelper.AddDesk.getShortcutMissionReward({
            success:(canReceive)=>{
                console.log("添加桌面奖励是否可领取",canReceive);
            },
            fail:()=>{  
                console.log("添加桌面接口调用失败")
            },
            complete:()=>{
                console.log("添加桌面接口调用完成")
            }
        })

侧边栏相关 ​

GameHelper.TKSidebar.toSidebar ​

描述 ​

跳转到侧边栏

参数 ​

属性名类型默认值是否必填说明
success()=>void/是调用成功回调
fail()=>void/否调用失败回调
complete()=>void/否调用完成回调

示例 ​

javascript
GameHelper.TKSidebar.toSidebar({
            success:()=>{
                console.log("跳转侧边栏成功");
            },
            fail:()=>{  
                console.log("跳转侧边栏失败")
            },
            complete:()=>{
                console.log("跳转侧边栏完成")
            }
        })
‼️ 特别提醒 ‼️若访问过小游戏但仍未出现该入口，通常是由于账号归属地不在目前小游戏功能已开放的地区（即US、JP、ID），可按以下思路自查：
  • 查询当前账号归属地：可以前往 profile-右上角-setting-account-account information 页面查看账号归属地，如果不显示归属地，大概率默认为最近一次登录的IP地址。
  • 创建目标地区账号：以US为例，若存在美国地区的app store账号建议直接使用对应账号登录，若需创建新账号需用美国地区SIM卡，且挂美国VPN节点完成账号注册。
  • 若上述方式均无法解决问题，请优先更换其他满足条件的设备登录。

GameHelper.TKSidebar.getEntranceMissionReward ​

描述 ​

获取是否能发放侧边栏奖励结果

参数 ​

属性名类型默认值是否必填说明
success(canReceive:boolean)=>void/是调用成功回调，canReceive用来判断是否可以发放奖励
fail()=>void/否调用失败回调
complete()=>void/否接口调用完成回调

示例 ​

javascript
GameHelper.TKSidebar.getEntranceMissionReward({
            success:(res)=>{
                console.log("侧边栏奖励是否可领取",res);
            },
            fail:()=>{  
                console.log("接口调用侧边栏失败")
            },
            complete:()=>{
                console.log("调用完成完成")
            }
        })

中间事件回传 ​

tiktok渠道专属的事件上报

枚举 ​

属性名说明类型枚举可选值
TKSectionType关卡类型枚举stringMain = “0”Events = “1”Challenge = “3”
TKSectionValue关卡价值枚举numberHIGH = 0LOW = 1
TKTokenType积分/货币类型枚举numberPremiumCurrency = 0SecondaryCurrency = 1

GameHelper.TKReportEvent.LoadingComplete ​

描述 ​

上报游戏加载完成

参数 ​

属性名类型默认值是否必填说明
optloadCompleteParams/是上报参数
loadCompleteParams ​
属性名类型默认值是否必填说明
complete_timenumber/是时间戳
success(res)=>void/是上报成功回调
fail(err)=>void/是调用失败回调

示例 ​

javascript
GameHelper.TKReportEvent.LoadingComplete({
            complete_time: Date.now(),
            success: (res) => {
                console.log("上报成功",res);
            },
            fail: (err) => {
                console.log("上报失败",err);
            }
        })

GameHelper.TKReportEvent.CompleteSection ​

描述 ​

上报完成关卡

参数 ​

属性名类型默认值是否必填说明
optCompleteSectionParams/是上报参数
CompleteSectionParams ​
属性名类型默认值是否必填说明
section_typestring/是关卡类型,必传string,0=主线关卡，1=活动关卡，2=挑战关卡 主线关卡最重要
main_section_nonumber/否主线关卡序号 例如主线关卡1，序号=1； 若关卡为主线关卡，则此为必传事件
section_namestring/是关卡名称
section_valuenumber/否关卡价值（可选）0=高价值；1=低价值
section_idnumber/是关卡id
section_sumnumber/是玩家已完成关卡总数
success(res)=>void/是上报成功回调
fail(err)=>void/是调用失败回调

示例 ​

javascript
GameHelper.TKReportEvent.CompleteSection({
                section_type: "0",
                main_section_no: 10,
                section_name: "mainsec",
                section_value: 1,
                section_id: 2,
                section_sum: 10,
                success: (res) => {
                    console.log("上报成功",res);
                },
                fail: (err) => {
                    console.log("上报失败",err);
                }

            })

GameHelper.TKReportEvent.GainCredits ​

描述 ​

上报获取奖励

参数 ​

属性名类型默认值是否必填说明
optGainCreditsParams/是上报参数
GainCreditsParams ​
属性名类型默认值是否必填说明
valuenumber/是数值
token_typenumber/是积分/货币类型， 0=必须付费获得的主要货币，一级货币；1=可以通过付费货币兑换或看广告等手段获得的二级货币
token_idstring/是货币/积分ID，例如：金子、银子、钻石、星琼等 只要求客户上报游戏内的一种最主要的货币即可，每个用户都有的。
success(res)=>void/是上报成功回调
fail(err)=>void/是调用失败回调

示例 ​

javascript
GameHelper.TKReportEvent.GainCredits({
                value: 3,
                token_type: 1,
                token_id: "gold",
                success: (res) => {
                    console.log("上报成功",res);
                },
                fail: (err) => {
                    console.log("上报失败",err);
                }
            })

GameHelper.TKReportEvent.UserLeave ​

描述 ​

上报玩家离开游戏，一般可以在onHide里进行判断

参数 ​

属性名类型默认值是否必填说明
optUserLeaveParams/是上报参数
UserLeaveParams ​
属性名类型默认值是否必填说明
leave_timenumber/是时间搓
Leave_reasonnumber/是玩家离开小游戏的原因/场景，如果统计不到，可以是NULL
success(res)=>void/是上报成功回调
fail(err)=>void/是调用失败回调

示例 ​

javascript
GameHelper.TKReportEvent.UserLeave({
                leave_time: Date.now(),
                Leave_reason: 1,
                success: (res) => {
                    console.log("上报成功",res);
                },
                fail: (err) => {
                    console.log("上报失败",err);
                }
            })

GameHelper.TKReportEvent.ReportEvent ​

描述 ​

中间事件上报的核心接口，前面的上报方法都基于该接口

参数 ​

属性名类型默认值是否必填说明
optReportEventParams/是上报参数
ReportEventParams ​
属性名类型默认值是否必填说明
eventNamestring/是事件名
paramsobject/是上报参数
success(res)=>void/是上报成功回调
fail(err)=>void/是调用失败回调

示例 ​

javascript
//上报获取奖励
GameHelper.TKReportEvent.ReportEvent({
                eventName: "gain_credits",
                params: {
                    value: 3,
                    token_type: 1,
                    token_id: "gold",
                },
                success: (res) => {
                    console.log("上报成功", res);
                },
                fail: (err) => {
                    console.log("上报失败", err);
                }
            })

测试说明 ​

1.本地调试游戏 ​

1. 找对接运营提供 ​

4.2.2 进入构建的字节跳动小游戏文件夹内开启终端，建议在VS Code内开启终端，后面需要在终端内设置代理 ​

4.2.3 在终端依次执行以下几个指令(需要开vpn) ​

4.2.3.1 设置代理 ​
javascript
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
4.2.3.2 登录 ​
  1. 先注册tiktok开发者账号

网址：https://developers.tiktok.com/

  • 输入email和password,就是刚才注册的开放平台账号

javascript
ttmg login
4.2.3.3 开启调试环境 ​

该指令会编译项目并生成二维码，用tiktok扫码就能调试了，也可以通过这个页面将本地的游戏代码包上传到平台进行测试或调试

javascript
ttmg dev

  • 如果一直打不开或者报错

    • 首先请使用本地调试工具进行debug，代码编译能不能通过？

    • 排查网络是不是能刷视频流畅（网络很好），账号注册地区是不是美国/日本/印尼？

    • 先排查扫码账号添加进了target user了吗？

2.非本地调试 ​

  1. 正式提测时按需按这种方式测试

  2. 将构建的字节小游戏包压缩成zip包给发布人员上传

点我快速对接
›