MG Ads 广告接入指南

简介

本文档面向接入 MG Ads SDK 的开发者，介绍如何正确接入各类广告功能。

⚠️ 重要提示：在调用广告功能之前，必须依次完成 CMP 接口和 SDK 初始化接口的调用。两者缺一不可。具体请参考CMP与SDK初始化接入指南。

MG Ads 支持以下广告类型：

序号	广告类型	默认尺寸	支持 media 类型
1	全屏广告	1920×1080	image、web、video
2	退屏广告	-	-
3	横幅广告	728×90	image、web
4	插屏广告	1024×768	image、web、video
5	对联广告	300×600	image、web
6	激励广告	1024×768	web、video
7	信息流广告	-	image、web、video
8	嵌入式广告	-	image、web、video

广告调用流程

应用启动
    ↓
调用 SetAppId()
    ↓
调用 OpenCmp()
    ↓
等待用户完成选择
    ↓
调用 Initialize()
    ↓
SDK 初始化完成
    ↓
调用广告接口
    ↓
广告展示

⚠️ 强制要求：所有广告接口必须在 Initialize() 成功完成之后调用。

接入前准备

步骤一：引入命名空间

using MiracleGamesAd;
using MiracleGamesAd.Models;

步骤二：完成 CMP 与 SDK 初始化

请参考CMP与SDK初始化接入指南，确保完成：

OpenCmp()
Initialize()

步骤三：创建广告位

开发者可参考 MG Ads 开发者文档中的广告位创建说明：MG Ads - 开发者文档中心 | 完整的SDK接入指南与API参考 | MG Ads

步骤四：调用广告接口

根据业务场景选择对应广告类型：

使用场景	推荐广告类型
游戏启动页	全屏广告
游戏暂停页	插屏广告
游戏主界面	横幅广告
游戏结算页	激励广告
游戏退出时	退屏广告
自定义 UI 区域	信息流或嵌入式广告

广告素材类型说明

每种广告类型均支持通过 media 参数指定素材类型，非必填，传空时随机返回MG后台已开启的素材类型。可选值如下：

media 值	说明	广告来源
`image`	图片广告，默认支持	MG
`web`	网页广告，默认不开放，如需使用请在创建广告位后联系 MG 产品经理申请开通权限	Google
`video`	视频广告，默认支持（部分广告类型支持）	MG

⚠️ 重要提示：Web 类型广告（media 设置为 "web"）默认不开放，如需使用，请在创建广告位后联系 MG 产品经理申请开通权限。

步骤五：处理广告结果

根据接口返回结果判断广告是否展示成功。

if (result.ReturnValue)
{
    // 广告展示成功
}
else
{
    // 广告展示失败
}

广告接入

全屏广告

说明：全屏广告会覆盖整个应用界面，适用于游戏启动页、场景切换页、关卡开始前等场景。

Task<AsyncProcessResult> ShowAd(Control parentControl, string unitId, AdType adType)

参数说明

参数	类型	必要性	说明
parentControl	Control	必填	主窗体对象
unitId	string	必填	unitId 支持两种传入方式，您可根据实际需求灵活选择：简捷模式：直接传入广告位唯一标识，32位小写字母数字组合，在 MG 广告后台创建获取。适用于仅加载广告，无需额外控制信息的场景。扩展模式：传入 JSON 格式的字符串。适用于需要指定素材类型、或添加自定义标识以便后续识别的场景。
adType	AdType	必填	广告类型，全屏广告请使用 AdType.FullScreen

unitId 参数扩展字段说明

参数	类型	说明
unitId	string	广告位唯一标识，32位小写字母数字组合，在 MG 广告后台创建获取
media	string	支持的素材类型，非必填，传空时随机返回MG后台已开启的素材类型。可用的值包括： ● image：图片广告，默认支持 ● web：网页广告，需联系 MG 产品经理申请开通权限 ● video：视频广告，默认支持
tag	string	自定义内容，用于识别广告Control对象

返回值说明

场景	说明
ReturnValue = true	广告展示成功
ReturnValue = false	广告展示失败

完整示例代码

private const string FullScreenAdUnitId = "b871f83c5e8845f1b43325561bcdd6c7"; 
private const string ExitAdUnitId = "5076eab6ae1042b6b92f73ea01981475"; 
private const string BannerUnitId = "cb7d9688a2d9499992febb6b642b3625";
private const string InterstitialUnitId = "2cb66a1301404561881a3f26b6ce5ba7";
private const string CoupletUnitId = "b502f6e6281c43e4b28ea22503471039";
private const string RewardedUnitId = "2ae60936ba664fbfb7d92ce3a19c2915";
private const string FeedUnitId = "f152f6caf7a8440f8510bc31534baf4e";
private const string EmbeddedUnitId = "4192966a9db343f48dd2f6308ea9ec30";


private async void btnAd1_Click(object sender, EventArgs e)
{
    try
    {
        AsyncProcessResult result = await AdvertManager.ShowAd(this, FullScreenAdUnitId, AdType.FullScreen);
        if (result.ReturnValue)
        {

        }
    }
    catch (Exception)
    {
    }
}

横幅广告

说明：横幅广告通常固定显示在界面底部，适用于游戏主界面等场景。

Task<AsyncProcessResult> ShowAd(Control parentControl, string unitId, AdType adType)

参数说明

参数	类型	必要性	说明
parentControl	Control	必填	主窗体对象
unitId	string	必填	unitId 支持两种传入方式，您可根据实际需求灵活选择：简捷模式：直接传入广告位唯一标识，32位小写字母数字组合，在 MG 广告后台创建获取。适用于仅加载广告，无需额外控制信息的场景。扩展模式：传入 JSON 格式的字符串。适用于需要指定素材类型、或添加自定义标识以便后续识别的场景。
adType	AdType	必填	广告类型，横幅广告请使用 AdType.Banner

unitId 参数扩展字段说明

参数	类型	说明
unitId	string	广告位唯一标识，32位小写字母数字组合，在 MG 广告后台创建获取
media	string	支持的素材类型，非必填，传空时随机返回MG后台已开启的素材类型。可用的值包括： ● image：图片广告，默认支持 ● web：网页广告，需联系 MG 产品经理申请开通权限 ● video：视频广告，默认支持
tag	string	自定义内容，用于识别广告Control对象

返回值说明

场景	说明
ReturnValue = true	广告展示成功
ReturnValue = false	广告展示失败

完整示例代码

private async void btnAd3_Click(object sender, EventArgs e)
{
    try
    {
        AsyncProcessResult result = await AdvertManager.ShowAd(this, BannerUnitId, AdType.Banner);
        if (result.ReturnValue)
        {
        }
    }
    catch (Exception)
    {
    }
}

插屏广告

说明：插屏广告会在应用流程节点弹出展示，适用于关卡结束、页面切换、游戏暂停等场景。

Task<AsyncProcessResult> ShowAd(Control parentControl, string unitId, AdType adType)

参数说明

参数	类型	必要性	说明
parentControl	Control	必填	主窗体对象
unitId	string	必填	unitId 支持两种传入方式，您可根据实际需求灵活选择：简捷模式：直接传入广告位唯一标识，32位小写字母数字组合，在 MG 广告后台创建获取。适用于仅加载广告，无需额外控制信息的场景。扩展模式：传入 JSON 格式的字符串。适用于需要指定素材类型、或添加自定义标识以便后续识别的场景。
adType	AdType	必填	广告类型，插屏广告请使用 AdType.Interstitial

unitId 参数扩展字段说明

参数	类型	说明
unitId	string	广告位唯一标识，32位小写字母数字组合，在 MG 广告后台创建获取
media	string	支持的素材类型，非必填，传空时随机返回MG后台已开启的素材类型。可用的值包括： ● image：图片广告，默认支持 ● web：网页广告，需联系 MG 产品经理申请开通权限 ● video：视频广告，默认支持
tag	string	自定义内容，用于识别广告Control对象

返回值说明

场景	说明
ReturnValue = true	广告展示成功
ReturnValue = false	广告展示失败

完整示例代码

private async void btnAd4_Click(object sender, EventArgs e)
{
    try
    {
        AsyncProcessResult result = await AdvertManager.ShowAd(this, InterstitialUnitId, AdType.Interstitial);
        if (result.ReturnValue)
        {
        }
    }
    catch (Exception)
    {
    }
}

对联广告

说明：对联广告会固定显示在界面左右两侧，适用于 PC 端网页游戏等场景。

Task<AsyncProcessResult> ShowAd(Control parentControl, string unitId, AdType adType)

参数说明

参数	类型	必要性	说明
parentControl	Control	必填	主窗体对象
unitId	string	必填	unitId 支持两种传入方式，您可根据实际需求灵活选择：简捷模式：直接传入广告位唯一标识，32位小写字母数字组合，在 MG 广告后台创建获取。适用于仅加载广告，无需额外控制信息的场景。扩展模式：传入 JSON 格式的字符串。适用于需要指定素材类型、或添加自定义标识以便后续识别的场景。
adType	AdType	必填	广告类型，对联广告请使用 AdType.Couplet

unitId 参数扩展字段说明

参数	类型	说明
unitId	string	广告位唯一标识，32位小写字母数字组合，在 MG 广告后台创建获取
media	string	支持的素材类型，非必填，传空时随机返回MG后台已开启的素材类型。可用的值包括： ● image：图片广告，默认支持 ● web：网页广告，需联系 MG 产品经理申请开通权限 ● video：视频广告，默认支持
tag	string	自定义内容，用于识别广告Control对象
tag2	string	自定义内容，用于识别广告Control对象

返回值说明

场景	说明
ReturnValue = true	广告展示成功
ReturnValue = false	广告展示失败

完整示例代码

private async void btnAd5_Click(object sender, EventArgs e)
{
    try
    {
        AsyncProcessResult result = await AdvertManager.ShowAd(this, "{\"unitId\": \"" + CoupletUnitId + "\",\"tag\":\"MGAD_COUPLET_LEFT\",\"tag2\":\"MGAD_COUPLET_RIGHT\"}", AdType.Couplet);
        if (result.ReturnValue)
        {
        }
    }
    catch (Exception)
    {
    }
}

激励广告

说明：激励视广告用于用户观看完整广告后获得奖励，适用于游戏结算页、复活、领取双倍奖励等场景。

Task<AsyncProcessResult> ShowAd(Control parentControl, string unitId, AdType adType)

参数说明

参数	类型	必要性	说明
parentControl	Control	必填	主窗体对象
unitId	string	必填	unitId 支持两种传入方式，您可根据实际需求灵活选择：简捷模式：直接传入广告位唯一标识，32位小写字母数字组合，在 MG 广告后台创建获取。适用于仅加载广告，无需额外控制信息的场景。扩展模式：传入 JSON 格式的字符串。适用于需要指定素材类型、或添加自定义标识以便后续识别的场景。
adType	AdType	必填	广告类型，激励广告请使用 AdType.Rewarded

unitId 参数扩展字段说明

参数	类型	说明
unitId	string	广告位唯一标识，32位小写字母数字组合，在 MG 广告后台创建获取
media	string	支持的素材类型，非必填，传空时随机返回MG后台已开启的素材类型。可用的值包括： ● image：图片广告，默认支持 ● web：网页广告，需联系 MG 产品经理申请开通权限 ● video：视频广告，默认支持
tag	string	自定义内容，用于识别广告Control对象
comment	string	开发者自定义参数（需 URL 编码）,非必填
isFullScreen	bool	是否全屏显示，非必填。默认 false (1024*768)，设为 true 则全屏。

返回值说明

场景	说明
ReturnValue = true	广告展示成功
ReturnValue = false	广告展示失败

奖励发放流程

┌─────────────────┐
│  调用 ShowAd()   │
│ (传入激励广告参数) │
└────────┬────────┘
         ↓
┌─────────────────┐
│  用户观看广告    │
└────────┬────────┘
         ↓
┌─────────────────────────────────────────┐
│ 广告播放完成，广告关闭回调事件返回 Json 格式参数 │
└────────┬────────────────────────────────┘
         ↓
┌─────────────────┐     ┌─────────────────┐
│ completeStatus=1 │     │ completeStatus=0│
│    (完整观看)     │     │   (未完整观看)    │
└────────┬────────┘     └────────┬────────┘
         ↓                       ↓
┌─────────────────┐     ┌─────────────────┐
│   发放游戏奖励   │     │   不发放奖励     │
└────────┬────────┘     └─────────────────┘
         ↓
┌─────────────────────────────┐
│ 调用 ReportAdRewardFulfillment() │
│      通知 MG 后台核销         │
└─────────────────────────────┘

完整示例代码

private async void btnAd6_Click(object sender, EventArgs e)
{
    try
    {
        string comment = "id123,abc,$9.99";
        comment = Uri.EscapeDataString(comment);
        AsyncProcessResult result = await AdvertManager.ShowAd(this, "{\"unitId\": \"" + RewardedUnitId + "\",\"comment\":\"" + comment + "\",\"isFullScreen\":false}", AdType.Rewarded);
        if (result.ReturnValue)
        {
        }
    }
    catch (Exception)
    {
    }
}

private void AdvertManager_AdCloseEvent(object sender, string e)
{
    ShowMessage("The ad has been disabled. " + e);

    JObject jsonObject = JObject.Parse(e);
    string unitId = (string)jsonObject["unitId"];
    if (unitId == RewardedUnitId)
    {
        int completeStatus = (int)jsonObject["completeStatus"];
        string resourceId = (string)jsonObject["resourceId"];
        string materialId = (string)jsonObject["materialId"];
        string rewardId = (string)jsonObject["rewardId"];
        if (completeStatus == 1)
        {
            //广告播放完成，发放奖励
            //...

            Task.Run(async () =>
            {
                _ = await AdvertManager.ReportAdRewardFulfillment(unitId, resourceId, materialId, rewardId);//向MG报告
            });
        }
    }
}

💡 提示：

激励广告需在广告关闭回调中根据 completeStatus 判断是否发奖，避免未完整观看即发放奖励。
comment 字段可用于传递游戏内参数（如奖励类型、数量等），请务必在传入时进行 URL 编码，解码后使用。
成功发奖后应调用 ReportAdRewardFulfillment 通知 MG 后台完成核销。

信息流广告

说明：信息流广告允许开发者指定广告展示容器，适用于信息流广告、列表内嵌广告等场景。开发者需要提前在 Form 中定义一个容器控件（如 Panel），然后将该容器传入 SDK。

Task<AsyncProcessResult> ShowAd(Control parentControl, string unitId, AdType adType)

参数说明

参数	类型	必要性	说明
parentControl	Control	必填	开发者创建的控件实例，支持 Panel等
unitId	string	必填	unitId 支持两种传入方式，您可根据实际需求灵活选择：简捷模式：直接传入广告位唯一标识，32位小写字母数字组合，在 MG 广告后台创建获取。适用于仅加载广告，无需额外控制信息的场景。扩展模式：传入 JSON 格式的字符串。适用于需要指定素材类型、或添加自定义标识以便后续识别的场景。
adType	AdType	必填	广告类型，信息流广告请使用 AdType.Feed

unitId 参数扩展字段说明

参数	类型	说明
unitId	string	广告位唯一标识，32位小写字母数字组合，在 MG 广告后台创建获取
media	string	支持的素材类型，非必填，传空时随机返回MG后台已开启的素材类型。可用的值包括： ● image：图片广告，默认支持 ● web：网页广告，需联系 MG 产品经理申请开通权限 ● video：视频广告，默认支持
width	int	容器宽
height	int	容器高
tag	string	自定义内容，用于识别广告Control对象

返回值说明

场景	说明
ReturnValue = true	广告内容已成功渲染到指定容器
ReturnValue = false	广告展示失败

完整示例代码

private async void btnAd7_Click(object sender, EventArgs e)
{
    try
    {
        dynamic jsonObj = new
        {
            unitId = FeedUnitId,
            width = panelAd6.Width,
            height = panelAd6.Height
        };
        string json = JsonConvert.SerializeObject(jsonObj);
        AsyncProcessResult result = await AdvertManager.ShowAd(this.panelAd6, json, AdType.Feed);
        if (result.ReturnValue)
        {
        }
    }
    catch (Exception)
    {
    }
}

嵌入式广告

说明：嵌入式广告允许开发者指定广告展示容器，适用于页面内嵌广告、自定义 UI 区域的广告展示等场景。开发者需要提前在 Form 中定义一个容器控件（如 Panel），然后将该容器传入 SDK。

Task<AsyncProcessResult> ShowAd(Control parentControl, string unitId, AdType adType)

参数说明

参数	类型	必要性	说明
parentControl	Control	必填	开发者创建的控件实例，支持 Panel等
unitId	string	必填	unitId 支持两种传入方式，您可根据实际需求灵活选择：简捷模式：直接传入广告位唯一标识，32位小写字母数字组合，在 MG 广告后台创建获取。适用于仅加载广告，无需额外控制信息的场景。扩展模式：传入 JSON 格式的字符串。适用于需要指定素材类型、或添加自定义标识以便后续识别的场景。
adType	AdType	必填	广告类型，嵌入式广告请使用 AdType.Embedded

unitId 参数扩展字段说明

参数	类型	说明
unitId	string	广告位唯一标识，32位小写字母数字组合，在 MG 广告后台创建获取
media	string	支持的素材类型，非必填，传空时随机返回MG后台已开启的素材类型。可用的值包括： ● image：图片广告，默认支持 ● web：网页广告，需联系 MG 产品经理申请开通权限 ● video：视频广告，默认支持
width	int	容器宽
height	int	容器高
tag	string	自定义内容，用于识别广告Control对象

返回值说明

场景	说明
ReturnValue = true	广告内容已成功渲染到指定容器
ReturnValue = false	广告展示失败

完整示例代码

private async void btnAd8_Click(object sender, EventArgs e)
{
    try
    {
        dynamic jsonObj = new
        {
            unitId = EmbeddedUnitId,
            width = panelAd.Width,
            height = panelAd.Height
        };
        string json = JsonConvert.SerializeObject(jsonObj);
        AsyncProcessResult result = await AdvertManager.ShowAd(this.panelAd, json, AdType.Embedded);
        if (result.ReturnValue)
        {
        }
    }
    catch (Exception)
    {
    }
}

退屏广告

说明：退屏广告是在退出游戏时触发，为了保证退出游戏时广告的弹出率，MG会分两步完成退屏广告的实现

1.在初始化完成后，将退屏广告的信息加载到内存中

2.在退出游戏时，直接打开退屏广告

void SetupExitAd(string unitId)

参数说明

参数	类型	必要性	说明
unitId	string	必填	广告位唯一标识，32位小写字母数字组合，在 MG 广告后台创建获取

完整示例代码

//退屏广告
//Step1.初始化成功之后，加载退屏广告资源
private async void Form1_Load(object sender, EventArgs e)
{
    //...
    var result = await ApplicationManager.Initialize(YourAppId, YourSecretKey);
    if (result.ReturnValue)
    {
        //初始化成功... 
        ShowMessage("初始化完成");

        //退屏广告Step1.初始化成功之后，加载退屏广告资源
        AdvertManager.SetupExitAd("xxxxxxx");

        //...
    }
}

// 退屏广告
// Step2.在程序关闭时，弹出展示退屏广告
private void Form1_FormClosing(object sender, FormClosingEventArgs e)
{
    _ = AdvertManager.ShowExitAdBlocking();
}

广告关闭事件

说明：注册广告关闭的回调事件，一般在页面的构造函数中进行

事件返回参数说明

参数名	参数描述	示例
unitId	开发者传入的广告位ID	e333abaf22404c4a8d382c1e7ba42076
advertStatus	广告位状态	1:广告正常；2:广告被后台关闭；3:没有广告素材
以下是仅激励视频广告拥有的参数
completeStatus	广告的播放状态	1:广告播放完毕，可以发奖励；0:广告未播放完毕
comment	由开发者传入的透传参数，经过 url 编码	abc%2c123
rewardId	奖励的MG订单号，游戏发奖后向MG报告核销时使用	String
resourceId	资源Id	String
materialId	素材 Id	String

完整示例代码

public Form1()
{
    InitializeComponent();
    //...
    AdvertManager.AdClickEvent += AdvertManager_AdClickEvent;
    AdvertManager.AdCloseEvent += AdvertManager_AdCloseEvent;
}

private void AdvertManager_AdCloseEvent(object sender, string e)
{
    ShowMessage("广告被关闭 " + e);

    //普通广告 {"unitId":"6bf68881673540788d096b9ea4a3cedb","advertStatus":1,"resourceId":"68d20656bd9558abfdf43465","materialId":"d235efa86ccf44acbe7053af760031b6"}
    //激励视频广告 {"unitId":"0f505442fac84f098e81d6f2ca04abe1","advertStatus":1,"completeStatus":1,"resourceId":"68ecb9eb20f045c603867874","materialId":"b0817d87ee2544629bac1933a60238d2","comment":"id123%2Cabc%2C%249.99","rewardId":"D1E593C16BBD412CA880FD89F0450A14"}

    JObject jsonObject = JObject.Parse(e);
    string unitId = (string)jsonObject["unitId"];

    if (unitId == "0f505442fac84f098e81d6f2ca04abe1")//激励视频，根据返回结果发奖励道具
    {
        int completeStatus = (int)jsonObject["completeStatus"];
        string resourceId = (string)jsonObject["resourceId"];
        string materialId = (string)jsonObject["materialId"];
        string rewardId = (string)jsonObject["rewardId"];
        string comment = (string)jsonObject["comment"];//透传参数
        if (completeStatus == 1)
        {
            //视频播放完毕，下发奖励道具 
            //...

            Task.Run(async () =>
            {
                _ = await AdvertManager.ReportAdRewardFulfillment(unitId, resourceId, materialId, rewardId);//向MG报告
            });
        }
    }
}

private void AdvertManager_AdClickEvent(object sender, string e)
{
    ShowMessage("广告被点击 " + e);
}

广告预加载功能

⚠️ 适用场景说明：预加载功能仅适用于接入了多个广告平台（如同时接入了AppLovin、Vungle、优量汇、MG 等多套 SDK）的开发者。如果仅接入 MG Ads 单一平台，建议直接使用 ShowAd()，无需使用预加载模式。

预加载功能提供两个独立的接口，帮助您在广告展示前提前准备素材，提升展示成功率。

预加载接口（PreloadAd）：提前请求并缓存广告素材
展示预加载广告接口（ShowPreloadAd）：展示已预加载成功的广告

💡 提示：预加载功能适用于所有广告类型。您可以在需要展示广告之前，提前调用预加载接口，待广告准备就绪后再通过展示接口进行展示。

预加载核心规则

规则	说明
单条缓存	SDK 每个广告位仅缓存一条广告，在未播放完成前不能再次请求预加载
播放完成后再预加载下一条	广告展示完成后，才能再次调用 PreloadAd() 预加载下一条广告
ID 与类型必须一致	ShowPreloadAd() 的 unitId 和 adType 必须与 PreloadAd() 完全一致

最佳实践案例

场景：激励广告广告在关卡结束后用于领取双倍奖励

关卡开始前
    ↓
调用 PreloadAd() 预加载激励广告
    ↓
玩家通关
    ↓
调用 ShowPreloadAd() 展示广告
    ↓
广告播放完成
    ↓
开启下一关
    ↓
再次调用 PreloadAd() 预加载下一条

预加载接口

Task<AsyncProcessResult> PreloadAd(string unitId, AdType adType)

参数说明

参数	类型	必要性	说明
unitId	string	必填	unitId 支持两种传入方式，您可根据实际需求灵活选择：简捷模式：直接传入广告位唯一标识，32位小写字母数字组合，在 MG 广告后台创建获取。适用于仅加载广告，无需额外控制信息的场景。扩展模式：传入 JSON 格式的字符串。适用于需要指定素材类型、或添加自定义标识以便后续识别的场景。
adType	AdType	必填	广告类型

unitId 参数扩展字段说明

参数	类型	说明
unitId	string	广告位唯一标识，32位小写字母数字组合，在 MG 广告后台创建获取
media	string	支持的素材类型，非必填，传空时随机返回MG后台已开启的素材类型。可用的值包括： ● image：图片广告，默认支持 ● web：网页广告，需联系 MG 产品经理申请开通权限 ● video：视频广告，默认支持
tag	string	自定义内容，用于识别广告Control对象

返回值说明

场景	说明
ReturnValue = true	预加载成功，可调用 ShowPreloadAd 展示广告
ReturnValue = false	预加载失败，降级使用普通 ShowAd() 或放弃本次广告展示

完整示例代码（插屏广告）

private async void PreloadInterstitialAd()
{
    var result = await AdvertisingManager.PreloadAd("0123456789abcdef0123456789abcdef", AdType.Interstitial);
    if (result.ReturnValue)
    {
        // 预加载成功，可以调用 ShowPreloadAd 展示广告
    }
    else
    {
        // 预加载失败
    }
}

展示预加载广告接口

AsyncProcessResult ShowPreloadAd(Control parentControl, string unitId, AdType adType)

参数说明

参数	类型	必要性	说明
parentControl	Control	必填	主窗体对象，或开发者创建的容器控件对象
unitId	string	必填	unitId 支持两种传入方式，您可根据实际需求灵活选择：简捷模式：直接传入广告位唯一标识，32位小写字母数字组合，在 MG 广告后台创建获取。适用于仅加载广告，无需额外控制信息的场景。扩展模式：传入 JSON 格式的字符串。适用于需要指定素材类型、或添加自定义标识以便后续识别的场景。
adType	AdType	必填	广告类型

unitId 参数扩展字段说明

参数	类型	说明
unitId	string	广告位唯一标识，32位小写字母数字组合，在 MG 广告后台创建获取
media	string	支持的素材类型，非必填，传空时随机返回MG后台已开启的素材类型。可用的值包括： ● image：图片广告，默认支持 ● web：网页广告，需联系 MG 产品经理申请开通权限 ● video：视频广告，默认支持
tag	string	自定义内容，用于识别广告Control对象

⚠️ 注意事项：调用本接口前，请确保对应广告位已通过 PreloadAd 预加载成功。

示例代码

2.1 展示预缓存成功的全屏广告

public async void ShowPreloadFullScreenAd()
{
    var result = await AdvertManager.ShowPreloadAd(this, FullScreenAdUnitId, AdType.FullScreen);
    if (result.ReturnValue)
    {
        // 广告展示完成
    }
    else
    {
        // 广告展示失败，可能原因：广告位未预加载、预加载过期、网络故障等
    }
}

2.2 展示预缓存成功的横幅广告

public async void ShowPreloadBannerAd()
{
    var result = await AdvertManager.ShowPreloadAd(this, BannerUnitId, AdType.Banner);
    if (result.ReturnValue)
    {
        // 广告展示完成
    }
    else
    {
        // 广告展示失败
    }
}

2.3 展示预缓存成功的插屏广告

public async void ShowPreloadInterstitialAd()
{
    var result = await AdvertManager.ShowPreloadAd(this, InterstitialUnitId, AdType.Interstitial);
    if (result.ReturnValue)
    {
        // 广告展示完成
    }
    else
    {
        // 广告展示失败
    }
}

2.4 展示预缓存成功的对联广告

public async void ShowPreloadCoupletAd()
{
    var result = await AdvertManager.ShowPreloadAd(this, CoupletUnitId, AdType.Couplet);
    if (result.ReturnValue)
    {
        // 广告展示完成
    }
    else
    {
        // 广告展示失败
    }
}

2.5 展示预缓存成功的激励广告

public async void ShowPreloadRewardAd()
{
    dynamic jsonObj = new
    {
        unitId = RewardedUnitId,
        comment = Uri.EscapeDataString("id123,abc,$9.99"), // 透传参数
        isFullScreen = false  // 是否全屏显示，非必填。默认 false (1024*768)，设为 true 则全屏。
    };
    string json = JsonConvert.SerializeObject(jsonObj);
    var result = await AdvertManager.ShowPreloadAd(this, json,  AdType.Rewarded);
    if (result.ReturnValue)
    {
       // 广告展示完成
    }
    else
    {
        // 广告展示失败
    }
}

private void AdvertManager_AdCloseEvent(object sender, string e)
{
    ShowMessage("The ad has been disabled. " + e);

    JObject jsonObject = JObject.Parse(e);
    string unitId = (string)jsonObject["unitId"];
    if (unitId == RewardedUnitId)
    {
        int completeStatus = (int)jsonObject["completeStatus"];
        string resourceId = (string)jsonObject["resourceId"];
        string materialId = (string)jsonObject["materialId"];
        string rewardId = (string)jsonObject["rewardId"];
        if (completeStatus == 1)
        {
            //广告播放完成，发放奖励
            //...

            Task.Run(async () =>
            {
                _ = await AdvertManager.ReportAdRewardFulfillment(unitId, resourceId, materialId, rewardId);//向MG报告
            });
        }
    }
}

2.6 展示预缓存成功的信息流广告

public async void ShowPreloadFeedAd()
{
    dynamic jsonObj = new
    {
        unitId = FeedUnitId,
        width = panelAd6.Width,
        height = panelAd6.Height
    };
    string json = JsonConvert.SerializeObject(jsonObj);
    var result = await AdvertManager.ShowPreloadAd(this.panelAd6,json, AdType.Feed);
    if (result.ReturnValue)
    {
        // 广告展示完成
    }
    else
    {
        // 广告展示失败
    }
}

2.7 展示预缓存成功的嵌入式广告

public async void ShowPreloadEmbedAd()
{
    dynamic jsonObj = new
    {
        unitId = EmbeddedUnitId,
        width = panelAd7.Width,
        height = panelAd7.Height
    };
    string json = JsonConvert.SerializeObject(jsonObj);
    var result = await AdvertManager.ShowAd(this.panelAd7, json, AdType.Embedded);
    if (result.ReturnValue)
    {
        // 广告展示完成
    }
    else
    {
        // 广告展示失败
    }
}

预加载功能调用流程

┌─────────────────────────────────────────────────────────────────┐
│                        应用启动                                 │
└─────────────────────────────┬───────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                    调用 OpenCmp() 和 Initialize()               │
└─────────────────────────────┬───────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      SDK 初始化完成                             │
└─────────────────────────────┬───────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│            【预加载模式】调用 PreloadAd() 预加载广告素材         │
│                     （如：关卡开始前预加载）                     │
└─────────────────────────────┬───────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                   判断预加载是否成功                            │
└─────────────┬───────────────────────────────┬───────────────────┘
              ↓                               ↓
        ┌───────────┐                   ┌───────────┐
        │ 成功(true)│                   │ 失败(false)│
        └─────┬─────┘                   └─────┬─────┘
              ↓                               ↓
┌─────────────────────────┐       ┌─────────────────────────────┐
│ 等待用户触发广告展示时机 │       │ 降级使用普通 ShowAd()        │
│ （如：玩家通关后）       │       │ 或 放弃本次广告展示           │
└─────────────┬───────────┘       └─────────────────────────────┘
              ↓
┌─────────────────────────────────────────────────────────────────┐
│          调用 ShowPreloadAd() 展示已预加载成功的广告             │
└─────────────────────────────┬───────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                        广告展示完成                             │
└─────────────────────────────┬───────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│           再次调用 PreloadAd() 预加载下一条广告                  │
│                 （为下一次展示做准备）                           │
└─────────────────────────────────────────────────────────────────┘

常见问题（FAQ）

Q1：为什么必须先在后台创建广告位？

A：unitId 是广告请求的唯一标识，需要在 MG 广告后台预先创建并配置广告素材，才能正常请求和展示广告。

Q2：广告展示失败怎么办？

A：常见原因及解决方法：

错误类型	解决方法
广告位 ID 错误	核对后台配置的32位小写字母数字组合ID
网络故障	检查设备网络连接
无可用广告素材	联系MG产品经理补充对应尺寸和格式的广告素材
预加载未完成	调用 ShowPreloadAd 前确保 PreloadAd 已成功

Q3：激励广告如何发放奖励？

A：在广告关闭的回调中判断 completeStatus：

为 1 时，表示用户完整观看视频，可发放奖励
发放奖励后必须调用 ReportAdRewardFulfillment() 通知 MG 后台核销

Q4：预加载功能的好处是什么？

A：

提前加载广告素材，减少用户等待时间
提高广告展示成功率
适用于需要精准控制广告展示时机的场景

Q5：OpenCmp 和 Initialize 未完成时能否调用广告？

A：不能。必须先完成 CMP 和 SDK 初始化，才能正常调用广告功能。否则可能导致广告请求失败或合规问题。

Q6：预加载功能应该在什么情况下使用？

A：仅当您的应用接入了多个广告平台（如同时使用Google、优量汇、MG 等多套 SDK）时，才建议使用预加载模式。单一平台场景直接使用 ShowAd() 即可。

Q7：预加载可以同时缓存多条广告吗？

A：不可以。每个广告位仅缓存一条广告，在未播放完成前不能再次请求预加载。广告展示完成后，应再次调用 PreloadAd() 预加载下一条。

Q8：ShowPreloadAd() 失败怎么办？

A：建议按以下顺序处理：

检查对应广告位是否预加载成功
检查广告位 ID 是否一致
检查广告类型是否一致
降级为 ShowAd() 普通广告展示模式
放弃本次广告展示

Q9：自定义广告的容器可以是什么类型的控件？

A：支持 Panel、ContentControl、UserControl 及其派生类。

Q10：如何主动关闭正在展示的广告？

A：移除对应的容器控件即可。

简介​

接入前准备​

广告接入​

全屏广告​

横幅广告​

插屏广告​

对联广告​

激励广告​

信息流广告​

嵌入式广告​

退屏广告​

广告关闭事件​

广告预加载功能​

预加载接口​

展示预加载广告接口​

预加载功能调用流程​

常见问题（FAQ）​

简介

接入前准备

广告接入

全屏广告

横幅广告

插屏广告

对联广告

激励广告

信息流广告

嵌入式广告

退屏广告

广告关闭事件

广告预加载功能

预加载接口

展示预加载广告接口

预加载功能调用流程

常见问题（FAQ）