TT小游戏接入 | 微游H5出海开发者中心

logo横版.png

TTMinis游戏接入

前提

在接入此文档之前，必须已经对接完MiniGame.com的SDK。

一、调试环境准备

1、安装 TikTok

目前处于内测邀请阶段，仅向受邀开发者提供内部测试版 Android 安装包下载使用。通过 Google Play 或 App Store 安装的 TikTok 不支持本地开发与调试接入。
TikTok测试包下载：点击后会跳转到下载链接，不过无法下载，需要对跳转后的页面做下刷新处理，就可以下载

2、安装CLI

npm install @ttmg/cli -g
ttmg -v

环境	说明	示意
安装 Chrome	小游戏调试工具基于主流浏览器 Chrome 提供开发与调试环境。尚未安装 Chrome 的开发者，请先完成浏览器安装。	--
安装 NodeJS	小游戏开发者工具是基于 NodeJS 环境做的开发，因此对于一些还未安装 Node JS 的开发者，需要先安装 Node 环境DevTool 要求开发者的 Node 版本不能低于 20，推荐安装 20.19.5，否则在后续安装 DevTool 时会报错	https://nodejs.org/en/download
安装 DevTool	本地开发调试的命令行工具	npm install @ttmg/cli -g ttmg -v
添加 Test User	仅当在开发者平台的对应小游戏应用中添加了当前 TikTok 用户后，方可进行后续本地调试。否则扫码会出现报错。
电脑/手机同一 WIFI 环境	本地调试手机和电脑需要在同一局域网内才可顺利进行连接，如果不在，无法成功开启调试	--
导出原生游戏包	当开发者咨询游戏引擎应导出何种包体时，请引导其导出微信/微信小游戏类型的包。TikTok 原生小游戏已兼容这两类主流产物。	以下图为例：
配置请求域名	若游戏是联网游戏，需要提供域名，添加了域名白名单后，才能请求成功

注意：在进行本地调试前，请确保您的手机和电脑处于同一网络环境，且可正常访问外网环境

二、接口

快捷方式

用户路径演示

接口需要配合每日奖励活动，用户路径展示：

快捷方式按钮会一直存在，每天未领取快捷方式奖励时，按钮会显示红点。
领取奖励的前提：已经添加过快捷方式，并且从上面图中的step3进入游戏，这次每日奖励弹窗的按钮状态会可领取奖励的状态，领取完奖励后，快捷方式按钮的红点会消失，之后的每一天都会重置，重新显示红点，并且同样需要从step3进入游戏，才能领取奖励
通过minigame.getShortcutMissionReward ()来判定是否可以领取奖励

接口：

canCreateShortcutAsync(): Promise<boolean>;是否可以准备可以创建快捷方式
createShortcutAsync( ): Promise<void>; 创建快捷方式
getShortcutMissionReward (): Promise<boolean> ：判读用户是否可以领取添加到桌面奖励。

Example:

minigame.canCreateShortcutAsync()
  .then(function(canCreateShortcut) {
  	// 如果可以创建
    if (canCreateShortcut) {
      // 尝试创建快捷方式
      minigame.createShortcutAsync()
        .then(function() {
          // Shortcut created
        	console.info("call createShortcutAsync done");
        })
        .catch(function(error) {
          // Shortcut not created
	        console.info("call createShortcutAsync fail: ", error);
        });
    }
  })
  .catch(function(error) {
  	console.info("canCreateShortcut fail: ", error);
  });

当然如果是接入cocoscreator插件版SDK，创建快捷方式，也可以直接只用createShortcut(shortcutCallback: BoolCallback)

MiniGameSDK.createShortcut((isSuccess: boolean) => {
	  if (isSuccess) {
		// console.info("minigame createShortcut success");
	  } else {
		// console.error("minigame createShortcut failed");
	  }
});

判断是否可以领取到桌面奖励

try {
  const isCanGetReward = await minigame.getShortcutMissionReward();
  console.log("isCanGetReward: ", isCanGetReward);
} catch (error) {
  console.error(error);
}

注意：红点的显示只要判定每天是否已经领取过奖励，领取过奖励，需要CP自己做数据持久化

个人侧边栏

用户路径演示

同样，接口需要配合每日奖励活动，用户路径展示：

同上，侧边栏按钮会一直存在，每天未领取快捷方式奖励时，按钮会显示红点。
和快捷方式不同是的，不管之前有没有成功调用过侧边栏接口，每天都要重走一遍1-7的流程才能领取奖励，而快捷方式，只要创建过快捷方式后，之后的每一天只要走 step3 到 step4 两步就好，没有创建快捷方式，就需要走step1 到 step4

接口

startEntranceMission (): Promise<void>: 跳转个人主页侧边栏，引导复访。
getEntranceMissionReward (): Promise<boolean>：判断用户是否可以领取完成个人页侧边栏复访的奖励

Example:
拉起复访

try {
    await minigame.startEntranceMission();    
    console.log("startEntranceMission sucess"); &nbsp;
} catch (error) {
    console.error("startEntranceMission failed : ", error);
}

判断是否可以领取侧边栏奖励

try {
  const isCanGetReward = await minigame.getEntranceMissionReward();
  console.log("isCanGetReward: ", isCanGetReward);
} catch (error) {
  console.error(error);
}

三、TT小游戏接入

接入完MiniGame SDK后，在此基础上有几个地方需要修改下：

分别下载minigame.js和minigame.json，并且放到打包后的游戏根目录
- minigame.js下载地址：https://sdk.minigame.vip/js/tk-rt/minigame.js
- minigame.json下载地址：https://sdk.minigame.vip/js/tk/minigame.json
- minitk-sdk.js下载地址：https://sdk.minigame.vip/js/tk/minitk-sdk.js
将minigame.js和minigame.json放入到构建包目录中，在game.js中加载 minigame.js
在游戏资源加载前，调用minigame.initializeAsync()，在异步成功返回后加载游戏资源
在游戏资源加载完毕，进入游戏场景前，调用minigame.startGameAsync()，在异步成功返回后，再进入游戏场景

minigame.json里面的tk下的相关字段，在接入前我们会给到，其中
adUnitId：激励广告ID；
adInterstitialId：插屏广告ID；
client_key：应用的秘钥；
name: 游戏名称，每个单词首字母大写，比如 Pop Stone；
game: 游戏名称，需要用小写，空格改成链接符，比如 pop-stone；
isProduction：是否为发布环境，本地测试需要为false，提正式包时，需设置为true；
fastLogin: 是否跳过TT登录，本地测试可以为false，提正式包时，需设置为true；

1、打包小游戏包

这里以cocoscreator游戏为例，打包出抖音小游戏包，TikTok 原生小游戏已兼容抖音小游戏包

2、完成本地登录

开发者工具所提供的“检查游戏 Client Key 是否有效”、“上传代码包到开发者平台”等功能，需要开发者在本地终端完成开发者平台账号登录后才能正常使用。为确保后续功能的顺利运行，建议您优先完成账号登录，再进行后续的调试操作。

ttmg login

Email和Password 单独联系对接人员获得

注意注意：如果在登录过程中出现网络超时情况，参考此文档进行自助处理 TikTok 小游戏命令行未走代理解决方案

3、启动游戏调试

进入游戏目录

cd path/to/your-game-project

启动调试环境

ttmg dev

输入开发者平台创建的小游戏 Client Key，之后本地命令行会记录上次调试的 Client Key，启动后如图：

在chromel浏览器上打开 http://localhost:3000?v=0.2.4-beta.4 ，链接中v的版本具体看命令行工具如何显示，即可打开调试工具页面，如下图：

4、调试模式选择

模式	客户端真机预览	浏览器远程调试
特点	游戏逻辑在客户端（真机）中运行通过 vConsole 查看运行日志在真机上真实还原并预览游戏效果	游戏逻辑在浏览器中运行可在浏览器环境查看日志、断点调试在客户端同步查看游戏画面效果
选择	如果你本地的网络状况不佳，当前调试模式会卡顿，建议走真机预览

💡 如果需要更灵活的配置，你还可以新建自定义启动模式，以满足特定的调试与预览需求。

客户端真机预览

浏览器远程调试

使用 TikTok 扫描网页上的二维码
扫码前确认当前客户端版本是否为支持原生小游戏的版本，如果不支持，扫码后会出现 404 页面导致
1. TikTok 需要挂 VPN 才可以正常访问
2. 扫码二维码前需要试用账号完成登录
等待客户端校验当前登录的 TikTok 用户是否有此应用的调试权限
1. 如果有权限，客户端会开启调试环境
2. 如果无权限，
  1. 打开 project.config.json 检查 appid 是否和开发者平台对应的游戏 ID 一致
  2. 检查 project.config.json 中的 appid 是否已经在平台添加测试用户
完成调试用户鉴权后，调试工具会开始上传游戏包到 TikTok 客户端，上传完成后开始加载游戏
1. 浏览器界面展示上传进度，上传完成后，客户端开始启动游戏
2. 客户端完成游戏启动后，在端内操作游戏，进入你想调试模块
3. 浏览器控制台来查看你打的日志或者 debugger 你的 JavaScrip
当你调试过程中需要修改代码，可在游戏引擎导出环节选择同样的导出路径
1. 本地的调试服务会监听游戏原始代码包的变化，会自动进行预编译
2. 调试页面在修改后的代码完成编译后会以弹窗的方式告知

5、设置启动模式

默认模式

新建启动模式

在本地测试调用拉起侧边栏接口后，可以新建一个模式，修改下启动模式名称，比如改为复访奖励-侧边栏，点击保存后，切换到扫码调试页面，选择刚刚创建好的复访奖励-侧边栏模式，然后扫码进入游戏，测试领取侧边栏复访奖励。同理其他功能也可以这么操作，可以在选择进入场景中选择要测试的功能，并创建对应的启动模式，

6、包体大小说明

类型	限制	说明
整个项目大小	源文件大小不超过 30MB（压缩前）	从游戏引擎中导出的游戏项目的大小
游戏主包大小	主包大小不超过 4MB（压缩前）	游戏项目中除了 subpackages/* 之外的所有文件都将被统计在游戏主包大小范围内
独立分包大小	主包大小不超过 4MB（压缩前）	游戏 subpackages 中定义为 `independent：true` 的包体大小

大纲