广告模块

核心代码位于 ZMYSDKManager 中

Banner 广告

展示 Banner 广告：pos: 1-Bottom 2-Top

ZMYSDKManager.I.Sdk.ShowBannerStatic(pos);

隐藏 Banenr 广告

ZMYSDKManager.I.Sdk.HideBannerStatic();

Banner 点击回调

ZMYSDKManager.I.Ads_BannerClick事件

微信的 Banner 广告大小可以手动设置，在微信小游戏工程的 GameConfig.json 中设置

{
    "DebugMode": 1,
    "banner_width":300,
    "banner_height":50
}

插屏

插屏是否准备好了

TIP

该接口仅用于查询插屏广告准备状态。业务侧展示插屏时，不需要主动调用该接口判断是否能展示广告，直接调用 ShowInterstitial 即可。

/// <param name="InterstType">0 游戏结束插屏，1 游戏内插屏</param>
ZMYSDKManager.I.IsInterstitialReadyStatic("0")

展示插屏

TIP

开始展示插屏广告时，暂停游戏背景音乐

/// <param name="insertName">插屏标记位</param>
/// <param name="insertType">0 游戏结束插屏，1 游戏内插屏</param>
ZMYSDKManager.I.ShowInterstitial(insertName, "0");

插屏展示回调

ZMYSDKManager.I.Ads_InterstitialShow

插屏关闭回调

ZMYSDKManager.I.Ads_InterstitialClose

激励视频

WARNING

💡 视频未填充时，提示文本为：视频未拉取到，请稍后再试

💡 视频中途退出 提示文本为：视频未完整播放

视频广告播放暂停界面

视频广告开始展示成功时，SDK 会派发 GlobalMsgDefine.VideoAdOnShowSuccess；视频关闭时会派发 GlobalMsgDefine.VideoAdOnClose。

如果当前是微信渠道，并且 XYXGlobalConfig.I.PlayAdDefaultPauseGame 为 true，AdsStatusPannel 会在视频广告播放期间自动执行以下逻辑：

1. 视频广告开始展示成功后，将 UnityEngine.Time.timeScale 设为 0f，暂停游戏逻辑。
2. 显示透明的 AdsStatusPannel 全屏点击层，避免玩家在广告播放期间继续操作游戏。
3. 视频广告关闭后，将 UnityEngine.Time.timeScale 恢复为 1f，并隐藏暂停界面。

默认会加载 Resources/AdsStatusPannel 预制体。如果需要自定义样式，可将默认预制体复制到 Resources 下并命名为 AdsStatusPannel_Custom，SDK 会优先使用该预制体。自定义预制体需要保留以下节点：

• bg：全屏点击层，需要挂载 Button，用于处理异常残留时的点击。
• btn：回到游戏按钮，需要挂载 Button，点击后会恢复 Time.timeScale = 1f 并关闭界面。

也可以在初始化时手动替换面板：

// 使用 Resources 下指定名称的预制体
AdsStatusPannel.ReloadPannel("AdsStatusPannel_Custom");

// 或直接传入场景中已经创建好的面板实例
AdsStatusPannel.ReloadPannel(panelInstance);

TIP

如果广告关闭事件未正常触发，暂停界面仍残留，玩家点击屏幕后会显示 btn 回到游戏按钮，用于手动恢复游戏，避免卡死。

组件式激励视频

激励视频由于涉及到的功能比较多，所以单独封装了激励视频模块：VideoButton

使用方法

1. 将 VideoButton 挂载到任意对象上

2. 设置按钮点击回调，触发 VideoButton.PlayVideo

3. 设置对应的 BtnShowType、VideFlag 和 Video_name；原有 Video_param1、Video_param2 按埋点需求选填，更多视频属性通过 VideoExtraProperties 设置

4. 设置对应的回调接受方法：m_btnOnClick 和 m_videoPlayCallBack

5. 完成以上设置即可使用激励视频功能，并且会自动进行激励视频相关上报

WARNING

💡 BtnShowType、VideFlag、Video_name 和 Video_param1/2 可以在 Inspector 面板配置或由代码赋值；VideoExtraProperties 为动态字典，只能由代码赋值。

WARNING

video_show 会在视频按钮展示到屏幕上时上报。VideoButton 默认会在 OnEnable 中调用 VideoBtnShow(true)，因此 Video_name、Video_param1、Video_param2 和 VideoExtraProperties 必须在按钮激活或显示前完成赋值。

如果按钮已经激活后才赋值，video_show 可能已经用空值或旧值上报。动态创建或动态赋值时，建议先保持按钮对象未激活，赋值完成后再显示；或者在 Inspector/Prefab 中关闭 AutoCallBtnShow，赋值完成后手动调用 VideoBtnShow(true)。

激励视频类型

    /// 视频显示类型
    public enum BtnShowType
    {
        /// 条件视频按钮，只有当条件准备好了后 才显示视频按钮
        Condition,
        /// 单次视频按钮。视频按钮创建后，只能播放单次视频
        SingleShow,
        /// 多次视频按钮 视频按钮创建后，能够重复点击播放
        MultipleShow,
    }

激励视频标志位 Flag

    /// 激励视频标志位
    public enum VideFlag
    {
        /// 视频送道具
        Flag1 = 0,
        /// 视频复活
        Flag2 = 1,
        /// 视频解释玩法/功能
        Flag3 = 2,

    }

视频上报参数

Video_name：激励视频名称

Video_param1：自定义参数 1

Video_param2：自定义参数 2

VideoExtraProperties：动态扩展属性字典，支持字符串、数值、布尔值、集合以及 LitJson 可以序列化的对象

using System.Collections.Generic;

videoButton.VideoExtraProperties = new Dictionary<string, object>
{
    { "video_scene", "level_fail" },
    { "reward_count", 3 },
    { "is_first", true },
};

动态属性会附加到 video_unable、video_noAds、video_show、video_click、video_play、video_success 和 video_fail。属性名必须先在统计后台配置；空属性名会被忽略。同名动态属性会覆盖 SDK 自动生成的值，因此不要传 game_name、mode_name、mode_level 或 video_name。

激励视频回调

点击回调：m_btnOnClick

只要点击激励视频按钮就会触发，回调 bool 值表示当前激励视频能否播放

播放完成回调：`m_videoPlayCallBack

激励视频播放完成后回调，回调 bool 值表示激励视频是否完成播放，

true：完成播放，可以发放奖励 flase：未正常完成播放，不给予奖励

动态绑定 组件式激励视频

如果已经写了视频按钮组件，不方便替换成组件式视频按钮，也可以使用绑定的方式来实现

public void ShowRewardVideo_ByComponent(GameObject btn_go,Action<bool> callBack)
    {
        VideoButton videoButton = btn_go.GetComponent<VideoButton>();
        if (videoButton == null)
        {
            videoButton = btn_go.AddComponent<VideoButton>();
        }
        videoButton.Video_name = "test";
        videoButton.Video_param1 = "param1";
        videoButton.Video_param2 = "param2";
        videoButton.VideoExtraProperties = new Dictionary<string, object>
        {
            { "video_scene", "level_fail" },
            { "reward_count", 3 },
        };
        //添加视频的回调
        videoButton.m_videoPlayCallBack = new UnityEngine.Events.UnityEvent<bool>();
        videoButton.m_videoPlayCallBack.AddListener((bool success)=>
        {
            callBack(success);
        });
        bool IsReady = ZMYSDKManager.I.IsVideoReady();
        videoButton.SetButtonState(IsReady ? BtnState.Active : BtnState.ActiveNotClick);
        //播放视频
        videoButton.PlayVideo();
    }

调用

GameObject btn_go = GetComponent<Button>().gameObject;
ShowRewardVideo_ByComponent(btn_go,VideoCallBack);

API 接入激励视频

如果上述两种方式都不方便接入，我们也提供了单独接入各个功能的接口，只不过这种方式需要手动进行广告状态的上报

视频是否准备好

    /// 视频是否准备好了
  ZMYSDKManager.I.IsVideoReady();

显示激励视频

ZMYSDKManager.I.ShowVide(m_flag, VideoCallBack);

激励视频状态变化事件

status：0：不显示，1：显示，置灰，不可点 ，2：显示，点亮，可点击

MsgDispatcher.AddEventListener(GlobalEventType.VideoButtonStatus, VideoButtonStatus);

WARNING

💡 事件记得在合适的时机移除 MsgDispatcher.RemoveEventListener(GlobalEventType.VideoButtonStatus, VideoButtonStatus);

TrackVideo 上报

// 广告按钮展示出现时调用
ReportManager.I.TrackVideo(1);

// 广告按钮展示出现，且有填充(isReady)时调用
ReportManager.I.TrackVideo(2);

// 广告按钮被用户点击时调用
ReportManager.I.TrackVideo(3);

点击上报

using System.Collections.Generic;

var extra = new Dictionary<string, object>
{
    { "video_scene", "level_fail" },
    { "reward_count", 3 },
};

// 点击视频按钮时
ReportManager.I.NewReportVideoClick("double_reward", extra);

播放上报

ReportManager.I.NewReportVideoPlay("double_reward", extra);

播放成功上报

ReportManager.I.NewReportVideoSuccess("double_reward", extra);

播放失败上报

ReportManager.I.NewReportVideoFail("double_reward", extra);

原有 (video_name, video_param1, video_param2) 调用继续兼容；也可以同时保留两个旧参数并在最后追加动态属性：

ReportManager.I.NewReportVideoClick(
    "double_reward",
    "param1",
    "param2",
    extra
);

NewReportVideoUnable 和 NewReportVideoNoAds 原本没有 video_param1/2，支持 (video_name) 和 (video_name, extraProperties) 两种形式。动态属性序列化失败时，SDK 会打印错误日志，并回退为只上报基础视频属性。