「必接」侧边栏复访能力技术指南

我的收藏

能力介绍

随着抖音小游戏复访能力的完善，抖音首页侧边栏日活持续增高，平台推荐开发者均接入抖音首页侧边栏复访教育，引导用户从首页侧边栏进入游戏，养成打开抖音->打开首页侧边栏->快速访问小游戏的心智，大幅提升次留、7留。

此能力将于「2023年11月24日」起开启「必接审核」，届时未接入该能力的小游戏在「新游首发」&「版本更新」环节会有「拒审」风险，为避免影响游戏上线&更新节奏，同时也为了提升小游戏留存，请尽快规划接入时间，感谢您的配合！

适配宿主：抖音、抖音极速版，其他宿主可『暂缓接入』此能力，开放后将及时通知。

适配游戏：普通小游戏、即玩unity&UE小游戏

应用实例

开发者在游戏内接入礼包引导复访的能力——>游戏版本发布——>用户在游戏主界面看到引导礼包——>用户根据指引，从侧边栏进入游戏——>进入礼包界面获取复访奖品

第一步	第二步	第三步	第四步

游戏主页设计并显示礼包ICON	点击礼包ICON后，引导用户「从抖音首页侧边栏进入游戏」	用户通过自动跳转进入首页侧边栏后，点击「游戏图标」回到游戏	奖励下发，用户成功领取奖励

方案示意

方案示意

技术方案流程：

通过引导玩家到侧边栏启动+监测启动参数，进行奖励发放。

参考流程图：

详细路径：

步骤	解释
步骤一：启动监听，判断是否展示奖励入口	1.游戏启动时通过tt.onShow监听启动信息；【请确保在游戏启动时机（game.js运行时机）同步监听tt.onShow，若时机太晚收不到回调，会导致用户按操作从侧边栏返回游戏后，无法领取到奖励，造成用户客诉！】 2.通过tt.checkScene判断当前宿主是否支持跳转侧边栏： ◦返回字段isExist=true时，展示奖励入口，进入步骤二 ◦返回字段isExist=false时，不展示奖励入口
步骤二：奖励展示	1.用户点击奖励入口时，通过获取tt.onShow的最新启动状态，判断当前用户是否从侧边栏启动： ◦侧边栏启动：奖励按钮显示「领取奖励」 ◦非侧边栏启动：奖励按钮显示未完成，进入第2步【判断是否从侧边栏启动时，应使用tt.onShow的最新返回值，否则用户从侧边栏热启动小游戏时，会由于返回值未更新而无法领取到奖励，造成用户客诉！】 2.自动跳转侧边栏：可增加一个跳转按钮，按钮点击回调事件设置为：关闭当前奖励界面并调用tt.navigateToScene（能力已全量开放，无需配置白名单）。用户点击按钮时会自动跳转到侧边栏。【平台强烈建议接入「自动跳转侧边栏」能力，可大幅度降低用户跳出小游戏后的流失率。】
步骤三：测试，上线	开发者需在测试环境下完整跑通从侧边栏启动后领取奖励的链路，详见下文「测试流程」，测试通过确认无误后发布上线。

重要注意事项：

请确保在游戏启动时机（game.js运行时机）同步监听tt.onShow，若时机太晚收不到回调，会导致用户按操作从侧边栏返回游戏后，无法领取到奖励，造成用户客诉！

判断是否从侧边栏启动时，应使用tt.onShow的最新返回值，否则用户从侧边栏热启动小游戏时，会由于返回值未更新而无法领取到奖励，造成用户客诉！

平台强烈建议接入「自动跳转侧边栏」能力，可大幅度降低用户跳出小游戏后的流失率。

测试流程：

平台为开发者提供了「3种」测试方法，开发者可以按需使用。对于新上线的unity游戏，直接看「方案3」。

方案1：通过抖音开发者工具模拟器进行模拟

该方案需要将抖音开发者工具升级至最新版本（大于等于4.1.7版本），暂不支持unity游戏

步骤

图示

调用tt.navigateToScene调起模拟器的侧边栏

tt.navigateToScene({
    scene: 'sidebar',
    fail: console.log,
    success: console.log
})

点击模拟器的侧边栏进入小游戏时，会触发tt.onShow事件，事件的回调参数中，scene值为021036，launch_from为homepage，location为sidebar_card

tt.onShow(op => {
    console.log(op);
});

{
  "scene": "021036",
  "query": {},
  "showFrom": 10,
  "launch_from": "homepage",
  "location": "sidebar_card",
  "refererInfo": { "appId": "xxxxxx", "extraData": {} }
}

方案2：抖音开发者工具修改启动参数，模拟侧边栏场景

暂不支持unity游戏

步骤	图示
1.IDE中选中「添加编译模式」按钮
2.选中 021036 场景值进行侧边栏进入场景模拟
3.用手机端抖音进行扫码预览或者扫码调试，可以在真机上模拟侧边栏场景启动小游戏

方案3：（建议）通过真机测试完整链路

该方案同时也支持未上线抖音的小游戏，需要另外加白处理，请到抖音开放平台-控制台-我的应用「小游戏tab」-右下角「开发者助手」-「在线客服」联系客服处理。

步骤	图示
1.首先进入抖音开放平台。
2.点击右上角蓝色按钮「控制台」，非登录态会弹出登录弹窗，完成登录后会进入应用中心，这里展示的是当前开发者账号具备管理或协作权限的小游戏。
3.在应用中心界面点击选择想要进行测试的小游戏，进入具体的小游戏管理页。首先从侧边功能栏找到「开发设置」，在设置页找到「测试管理」Tab，然后在右上角找到「添加设备」，点击会弹出一个二维码。
4.用手机端抖音扫码，将其添加为测试设备。	邀请加入测试环境	已加入测试环境
5.在抖音中点击「我」- 右上角「更多」- 底部「更多功能」，找到「开发者模式」并点击进入开发者模式界面。	找到「开发者模式」入口	开发者模式界面
6.打开开发者模式开关，点击需要测试的小游戏进入二级详情页，打开「全入口打开指定版本小游戏」开关。	打开开发者模式开关，点击测试的小游戏	进入二级详情页，打开「全入口打开指定版本小游戏」开关
7.选择「IDE上传的测试版本」或「扫码选择指定版本」	a.如果选择的是「IDE上传的测试版本」，则所有入口（包括首页侧边栏入口）启动的都会是「开发者平台」-「管理」-「版本管理」中的测试版本；
	b.如果选择的是「扫码选择指定版本」，可以通过扫描IDE上的预览二维码，指定所有入口（包括首页侧边栏入口）启动的都是IDE中的开发版本。
8.完成以上设置后，从抖音首页侧边栏中启动小游戏，就可以打开上面指定的测试/预览版本小游戏了

设计物料参考：

游戏需要根据本游戏整体风格及定位，设计相关图片素材，包括不限于礼包领取入口、点击礼包后引导弹窗及内容，可根据基础版动图引导，替换成自己游戏的icon。

文案建议：

建议文案及内容
内容	建议文案	建议设计
1.任务入口	1.文案需直观，快速让用户理解，建议为「限定福利」「入口有奖」等	1.建议设计成动态图标，吸引用户点击 2.建议放置于小游戏主页面显眼位置
2.任务界面	建议包含以下内容 1.顶部标题：「抖音首页侧边栏入口奖励」 2.步骤文案： a.点击下方「去首页侧边栏」按钮按钮 b.在侧边栏，点击「XXXXX」（游戏名） c.返回游戏，领取奖励 3.按钮文案：去首页侧边栏（未完成态）/ 立即领奖（完成态） 4.需注意设计关闭弹窗的按钮	1.可使用平台提供的GIF动图，也可自行设计静态图可替换成本游戏名称+图标
3.任务频次	1.因复访习惯需要逐步养成，建议奖励设置为「每日」可领取，加强用户感知及留存

物料模板：

侧边栏复访动画LOTTIE.zip

侧边栏动画GIF图层.zip

侧边栏复访动画GIF.zip

Q&A：

Q：接入调用tt.navigateToScene时，出现错误码为"10101"、错误信息为"fail platform auth deny"的相关报错？

A：更新到最新版本抖音进行开发测试。

Q：为什么冷启动时监听不到tt.onShow的返回值？

A：需要尽可能提前tt.onShow的监听时机，保证在game.js运行时启动监听。

Q：测试阶段，为什么在侧边栏看不到自己的小游戏？

A：目前侧边栏仅支持展示已上线的小游戏，未上线的小游戏可通过上文「测试流程」中的方案1或方案2进行测试。后续平台侧也会针对侧边栏的可见性问题进行进一步的优化。

Q：接入侧边栏能力后，如何做非抖音系宿主的兼容？

A：目前有三种方式可以解决：1. 非抖音系宿主暂不上线侧边栏相关代码；2. 调用侧边栏api前先判断是否存在该接口；3. 通过tt.getSystemInfoSync获取宿主信息进行判断。

「必接」侧边栏复访能力技术指南

​能力介绍​

​应用实例​

​方案示意​

​技术方案流程：​

​参考流程图：​

​详细路径：​

​测试流程：​

​方案1：通过抖音开发者工具模拟器进行模拟​

​方案2：抖音开发者工具修改启动参数，模拟侧边栏场景​

​方案3：（建议）通过真机测试完整链路​

​设计物料参考：​

​文案建议：​

​物料模板：​

​Q&A：​