小游戏侧边栏和复访

侧边栏复访用于引导玩家从平台侧边栏再次进入游戏，并领取游戏内的每日奖励。Unity 小游戏通过 XYX 接口统一检查支持情况、判断进入来源和跳转侧边栏。

接入要求

支持该能力的渠道需接入侧边栏复访。微信不支持本文这套侧边栏复访能力；其他渠道也需要通过 XYX.CheckSupportSide 判断当前宿主和版本是否支持，不能只根据渠道名称显示入口。

抖音侧边栏能力适用于抖音、抖音极速版。游戏应在 SDK 初始化完成后检查能力，并在首页展示入口。

接入方式

使用 UnityCowork

在 UnityCowork 的插件管理中安装“小游戏侧边栏”插件（插件展示名称为“XYX小游戏侧边栏奖励”），然后在会话中提出“接入侧边栏”。插件提供带 UI 的接入模板；完成接入后，仍需配置游戏自己的奖励、领取记录和每日刷新逻辑，并按本文自测。

自行接入

在游戏首页制作侧边栏礼包入口。当前环境不支持时隐藏入口；支持时保持常驻，可通过红点或动效提醒。
点击入口后打开复访引导 UI，展示前往平台侧边栏、点击游戏图标返回、领取奖励的步骤。除没有可发放奖励的游戏外，应使用带奖励的引导样式。
检查当前是否从侧边栏进入：普通进入时显示“前往侧边栏”，复访进入且今日未领取时显示“领取奖励”。
领取后将按钮改为“明日再来”，保留首页入口。奖励按日刷新，可结合每日任务或签到设计。

当前状态	首页入口	引导界面操作
不支持侧边栏	隐藏	不展示侧边栏任务
支持、今日未领取、普通进入	显示	前往侧边栏
支持、今日未领取、从侧边栏进入	显示	领取奖励
支持、今日已领取	保留	明日再来，禁止重复领取

接口与刷新时机

接口 / 事件	用途
`XYX.CheckSupportSide(Action<bool> callback)`	检查当前环境是否支持；在回调中决定是否显示入口
`XYX.CheckLaunchFormSide()`	判断当前进入场景是否为侧边栏，返回 `bool`
`XYX.JumpToSide()`	跳转到平台侧边栏
`GlobalMsgDefine.MiniGameOnShow`	游戏回到前台时重新判断进入来源并刷新 UI

复访完成与奖励发放

调用 XYX.JumpToSide() 不代表玩家已经完成复访。玩家需要在平台侧边栏点击游戏图标返回；收到 MiniGameOnShow 后重新调用 XYX.CheckLaunchFormSide()，再结合今日领取记录决定是否允许领奖。不要在点击跳转按钮时直接发奖。

首次进入游戏、打开引导界面和游戏回到前台时都应刷新状态。不要只在启动时缓存一次 CheckLaunchFormSide() 的结果，否则从侧边栏返回后界面可能仍停留在“前往侧边栏”。

逻辑示例

以下组件演示能力检查、跳转及前台事件处理。将它挂在常驻对象上，在 SDK 初始化完成后调用 InitializeAfterSdkReady()；入口和按钮可通过 Inspector 绑定。奖励系统通过 SetClaimedToday() 同步当日领取状态；本示例不代替游戏的发奖及存档逻辑。

csharp

using UnityEngine;
using XYXCommon;
using ZMYSDK.Util.Event;

public class SidebarRevisit : MonoBehaviour
{
    [SerializeField] private GameObject entry;
    [SerializeField] private GameObject goToSideButton;
    [SerializeField] private GameObject claimButton;
    [SerializeField] private GameObject claimedTodayTip;

    private bool supported;
    private bool claimedToday;
    private bool initialized;

    public void InitializeAfterSdkReady()
    {
        if (initialized) return;
        initialized = true;
        MsgDispatcher.AddEventListener(
            GlobalMsgDefine.MiniGameOnShow, OnMiniGameShow);
        RefreshUI();
        XYX.CheckSupportSide(value =>
        {
            if (this == null) return;
            supported = value;
            RefreshUI();
        });
    }

    // 初始化、领取成功及每日刷新后，由奖励系统同步状态。
    public void SetClaimedToday(bool value)
    {
        claimedToday = value;
        RefreshUI();
    }

    // 打开引导界面时也调用此方法。
    public void RefreshUI()
    {
        bool fromSide = supported && XYX.CheckLaunchFormSide();
        entry.SetActive(supported);
        goToSideButton.SetActive(supported && !claimedToday && !fromSide);
        claimButton.SetActive(supported && !claimedToday && fromSide);
        claimedTodayTip.SetActive(supported && claimedToday);
    }

    public void GoToSide()
    {
        if (supported && !claimedToday)
            XYX.JumpToSide();
    }

    // 领奖按钮调用业务发奖流程前，再次检查资格。
    public bool CanClaim()
    {
        return supported && !claimedToday && XYX.CheckLaunchFormSide();
    }

    private void OnMiniGameShow(object[] args)
    {
        RefreshUI();
    }

    private void OnDestroy()
    {
        if (initialized)
            MsgDispatcher.RemoveEventListener(
                GlobalMsgDefine.MiniGameOnShow, OnMiniGameShow);
    }
}

游戏奖励系统需要持久化领取日期、避免重复点击发奖，并在领取成功后调用 SetClaimedToday(true)。跨日时按游戏统一的每日刷新规则更新状态；回到前台时也要检查是否跨日，再刷新界面。领取记录未加载完成前应禁用领奖按钮。

编辑器测试

在 Unity 菜单中打开 小游戏 → 渠道功能调试，选择 侧边栏模拟。这里使用的是小游戏渠道功能调试窗口。

冷启动

勾选“支持侧边栏入口”。
将“启动场景类型”设为 Side，进入 Play 模式。
检查首页入口是否显示；今日未领取时，打开引导界面应显示领奖按钮。
改用 None 重新测试普通进入，应显示前往侧边栏按钮。
取消“支持侧边栏入口”后重新测试，首页入口应隐藏。

跳转后复访

使用 None 场景进入 Play 模式，在游戏中点击前往侧边栏按钮。
在“侧边栏模拟”中将启动场景类型改为 Side。此选项支持运行时修改。
切换到“生命周期模拟”，先点击“模拟切到后台（MiniGameOnHide）”，再点击“模拟回到前台（MiniGameOnShow）”。
确认游戏收到前台事件后重新判断进入来源，界面从前往侧边栏变为可领奖。
领取后再次触发前台事件，仍应显示“明日再来”，不能重复领奖。

编辑器模拟用于验证游戏逻辑和 UI 状态；平台跳转及真实进入场景仍需真机验证。

真机测试

渠道	测试方法
抖音	在开发者工具中添加编译模式，进入场景选择 `021036`，点击调试预览并使用抖音扫码，验证侧边栏进入场景
快手	打包并上传后，在真机运行测试
B 站	打包后使用真机预览，Android 和 iOS 均需测试

抖音场景设置示例：

验收检查

支持环境显示首页入口，不支持环境隐藏入口。
普通进入时显示引导，点击按钮能跳转到侧边栏。
从侧边栏返回后，无需重启游戏即可刷新为可领奖状态。
发奖成功后显示“明日再来”，首页入口保持常驻。
重复打开界面、反复切换前后台、当天重启游戏均不能重复领奖。
跨日后按游戏每日刷新规则恢复任务和奖励状态。

常见问题

从侧边栏返回，按钮仍显示“前往侧边栏”：检查是否监听了 MiniGameOnShow，是否在事件中重新调用 CheckLaunchFormSide()，以及真机进入场景是否正确。

反复切换前后台导致重复领奖：前台事件仅用于刷新界面，发奖前还要检查并持久化当日领取记录，不能在前台事件里无条件发奖。

编辑器测试正常，真机不显示入口：先检查 CheckSupportSide 的实际回调结果，确认宿主、客户端版本和渠道能力；编辑器勾选支持不会改变真机平台的能力。

小游戏侧边栏和复访 ​

接入要求 ​

接入方式 ​

使用 UnityCowork ​

自行接入 ​

接口与刷新时机 ​

逻辑示例 ​

编辑器测试 ​

冷启动 ​

跳转后复访 ​

真机测试 ​

验收检查 ​

常见问题 ​