侧边栏调用

模块信息

• 模块名：GameHelper.Sidebar
• 支持渠道：抖音小游戏、哔哩哔哩小游戏、TikTok 小游戏

侧边栏用于引导玩家从平台首页的侧边栏再次进入游戏，以提升游戏复访和留存。游戏需要提供侧边栏任务入口；是否配置完成奖励，由游戏策划决定。

接入前检查

侧边栏依赖目标平台客户端，在普通 Web 浏览器或 Cocos Web 预览中无法完整验证。调用前应等待 GameHelper SDK 初始化完成，并通过 support 判断当前环境是否支持。

if (!GameHelper.Sidebar.support) {
  console.log("当前环境不支持侧边栏");
  return;
}

属性与方法

名称	类型	说明
support	boolean	当前环境是否支持侧边栏
enterBySiderbar	boolean	本次是否从侧边栏进入游戏
toSidebar	Function	跳转到侧边栏
getEntranceMissionReward	Function	判断是否可以领取侧边栏奖励，仅 TikTok 渠道可用

字段拼写

SDK 属性名为 enterBySiderbar，其中使用的是 Siderbar，请按此拼写调用。跳转方法则是 toSidebar。

跳转到侧边栏

GameHelper.Sidebar.toSidebar(opt)

参数	类型	是否必填	说明
opt	Object	否	跳转回调配置
opt.success	Function	否	跳转成功回调
opt.fail	Function	否	跳转失败回调

function openSidebar() {
  if (!GameHelper.Sidebar.support) {
    console.log("当前环境不支持侧边栏");
    return;
  }

  GameHelper.Sidebar.toSidebar({
    success: () => {
      console.log("跳转侧边栏成功");
    },
    fail: (err) => {
      console.error("跳转侧边栏失败", err);
    },
  });
}

跳转成功只表示平台接口调用成功，不代表玩家已经完成复访任务，不能在 success 中直接发奖。

判断是否从侧边栏进入

在 SDK 初始化完成后读取 enterBySiderbar。值为 true 时，表示本次由侧边栏入口进入游戏，可继续校验任务状态和奖励领取记录。

function checkSidebarEntry() {
  if (GameHelper.Sidebar.enterBySiderbar) {
    console.log("本次从侧边栏进入游戏");
    // 校验任务状态和领取记录后发奖
  }
}

TikTok 侧边栏奖励

getEntranceMissionReward 仅 TikTok 渠道可用。是否发奖以成功回调中的 canReceive 为准，不要根据跳转结果判断。

GameHelper.Sidebar.getEntranceMissionReward({
  success: (canReceive) => {
    if (canReceive) {
      console.log("可以领取侧边栏任务奖励");
      // 校验本地或服务器领取记录后发奖
    } else {
      console.log("当前不可领取侧边栏任务奖励");
    }
  },
  fail: (err) => {
    console.error("查询侧边栏奖励失败", err);
  },
  complete: () => {
    console.log("侧边栏奖励查询完成");
  },
});

引导任务设计

侧边栏入口应放在游戏主页，并始终保留。入口图标和弹窗样式由产品自行设计：

• 不配置奖励时，入口建议采用公告样式。
• 配置一次性奖励时，领取前可使用礼包样式，领取后切换为公告样式。
• 配置周期奖励时，可持续使用礼包样式。
• 侧边栏可用且奖励尚未领取时，可展示入口红点。

有奖励的弹窗按钮建议包含三种状态：

任务状态	按钮文案	行为
未完成	前往侧边栏	调用 toSidebar
已完成、未领奖	领取奖励	校验后发放奖励
已领奖	奖励已领取	按钮置灰且不可点击

不配置奖励时，只需展示操作步骤和“前往侧边栏”按钮。

奖励刷新周期

奖励刷新周期由在线参数控制：

配置项	值
参数名称	SidebarGuide
参数键	a
单位	天
默认值	7

参数小于 0 时，表示任务奖励没有周期刷新，玩家终生只能领取一次。游戏发奖逻辑应做好幂等校验，避免同一周期重复领取。

抖音渠道构建配置

抖音侧边栏启动状态需要在很早的生命周期中获取。构建抖音小游戏后，必须在产物的 game.js 中加入以下代码，否则 SDK 可能无法正确取得侧边栏启动状态：

(function () {
  window.__a = {};

  function handleFirstShow(res) {
    window.__a.ttOnShowParams = res;
    tt.offShow(handleFirstShow);
  }

  tt.onShow(handleFirstShow);
})();

建议将这段代码放在 game.js 的业务启动代码之前，并在每次重新构建后确认代码仍然存在。

完整调用流程

function initSidebarFeature() {
  if (!GameHelper.Sidebar.support) {
    hideSidebarEntry();
    return;
  }

  showSidebarEntry();

  if (GameHelper.Sidebar.enterBySiderbar) {
    checkAndGrantSidebarReward();
  }
}

function onSidebarButtonClick() {
  GameHelper.Sidebar.toSidebar({
    success: () => console.log("已调用侧边栏跳转"),
    fail: (err) => console.error("侧边栏跳转失败", err),
  });
}

哔哩哔哩的任务界面和素材建议可继续参考哔哩哔哩小游戏接入说明，TikTok 的地区限制与测试方法可参考TikTok 小游戏接入说明。