MG Ads Ad Integration Guide

Introduction

This document is intended for developers integrating the MG Ads SDK, describing how to correctly integrate various ad formats.

⚠️ Important：Before calling any ad functionality, you must complete both the CMP interface and the SDK initialization interface calls in order. Both are indispensable. For details, please refer to the "CMP and SDK Initialization Integration Guide".

MG Ads supports the following ad formats:

No.	Ad Format	Default Size	Supported media Type
1	Full-screen Ad	1920×1080	image, web, video
2	Exit Ad	-	-
3	Banner Ad	728×90	image, web
4	Interstitial Ad	1024×768	image, web, video
5	Couplet Ad	300×600	image, web
6	Rewarded Ad	1024×768	web, video
7	Feed	-	image, web, video
8	Embedded Ad	-	image、web、video

Ad Call Flow

App Launch
    ↓
Call SetAppId()
    ↓
Call OpenCmp()
    ↓
Wait for user to make selection
    ↓
Call Initialize()
    ↓
SDK initialization complete
    ↓
Call ad interface
    ↓
Ad displayed

⚠️ Mandatory Requirement: All ad interfaces must be called after Initialize() has successfully completed.

Pre-Integration Preparation

Step 1: Import Namespace

using MiracleGamesAd;
using MiracleGamesAd.Models;

Step 2: Complete CMP and SDK Initialization

Please refer to the "CMP and SDK Initialization Integration Guide" to ensure the following are completed:

OpenCmp()
Initialize()

Step 3: Create Ad Unit

Developers can refer to the ad unit creation instructions in the MG Ads Developer Documentation: MG Ads - Developer Documentation Center | Complete SDK Integration Guide and API Reference | MG Ads

Step 4: Call Ad Interfaces

Select the corresponding ad format based on your business scenario:

Usage Scenario	Recommended Ad Format
Game launch screen	Full-screen Ad
Game pause screen	Interstitial Ad
Game main interface	Banner Ad
Game settlement screen	Rewarded Ad
Game exit	Exit Ad
Custom UI area	Feed or Embedded Ad

Ad Material Type Description

Each ad type supports specifying the material type via the media parameter. This parameter is optional; if left empty, a random ad creative type enabled in the MG backend will be returned. Available values are:

media Value	Description	Ad Source
`image`	Image ad, supported by default	MG
`web`	Web ad, not open by default. To use, please contact the MG Product Manager to request permission after creating the ad unit.	Google
`video`	Video ad, supported by default (some ad formats)	MG

⚠️ Important: Web ads (MediaType set to "web") are not open by default. To use them, please contact the MG Product Manager to request permission after creating the ad unit.

Step 5: Handle Ad Result

Determine whether the ad was displayed successfully based on the returned result.

if (result.ReturnValue)
{
    // Ad displayed successfully
}
else
{
    // Ad display failed
}

Ad Integration

Full-screen Ad

Description: Full-screen ads cover the entire application interface, suitable for game launch screens, scene transition screens, before level start, etc.

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

Parameter Description

Parameter	Type	Required	Description
parentControl	Control	Required	Main form object
unitId	string	Required	unitId supports two input methods; you can choose the one that best suits your needs: Simple Mode: Directly enter the ad slot’s unique identifier—a 32-character combination of lowercase letters and numbers—which can be obtained by creating the ad slot in the MG ad backend. This is suitable for scenarios where you only need to load ads without additional control information. Extended Mode: Pass a string in JSON format. This is suitable for scenarios where you need to specify the ad creative type or add a custom identifier for later recognition.
adType	AdType	Required	Advert type, please use AdType.FullScreen

Description of the unitId Parameter Extension Fields

Parameter	Type	Description
unitId	string	Unique identifier for the ad unit, 32-character lowercase alphanumeric string, obtained from the MG Ad backend.
media	string	Supported ad media types. this field is optional. If left empty, the system will randomly return one of the ad types currently enabled in the MG backend. Available values: ● image: Image ad, supported by default ● web: Web ad, requires permission from MG Product Manager ● video: Video ad, supported by default
tag	string	Custom content used to identify the ad Control object

Return Value Description

Scenario	Description
ReturnValue = true	Ad displayed successfully.
ReturnValue = false	Ad display failed.

Complete Code Example

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)
    {
    }
}

Banner Ad

Description: Banner ads are typically fixed at the bottom, suitable for game main interfaces, etc.

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

Parameter Description

Parameter	Type	Required	Description
parentControl	Control	Required	Main form object
unitId	string	Required	unitId supports two input methods; you can choose the one that best suits your needs: Simple Mode: Directly enter the ad slot’s unique identifier—a 32-character combination of lowercase letters and numbers—which can be obtained by creating the ad slot in the MG ad backend. This is suitable for scenarios where you only need to load ads without additional control information. Extended Mode: Pass a string in JSON format. This is suitable for scenarios where you need to specify the ad creative type or add a custom identifier for later recognition.
adType	AdType	Required	Advert type, please use AdType.Banner

Description of the unitId Parameter Extension Fields

Parameter	Type	Description
unitId	string	Unique identifier for the ad unit, 32-character lowercase alphanumeric string, obtained from the MG Ad backend.
media	string	Supported ad media types. this field is optional. If left empty, the system will randomly return one of the ad types currently enabled in the MG backend. Available values: ● image: Image ad, supported by default ● web: Web ad, requires permission from MG Product Manager ● video: Video ad, supported by default
tag	string	Custom content used to identify the ad Control object

Return Value Description

Scenario	Description
ReturnValue = true	Ad displayed successfully.
ReturnValue = false	Ad display failed.

Complete Code Example

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

Interstitial Ad

Description: Interstitial ads pop up during application flow nodes, suitable for level end, page transitions, game pause, etc.

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

Parameter Description

Parameter	Type	Required	Description
parentControl	Control	Required	Main form object
unitId	string	Required	unitId supports two input methods; you can choose the one that best suits your needs: Simple Mode: Directly enter the ad slot’s unique identifier—a 32-character combination of lowercase letters and numbers—which can be obtained by creating the ad slot in the MG ad backend. This is suitable for scenarios where you only need to load ads without additional control information. Extended Mode: Pass a string in JSON format. This is suitable for scenarios where you need to specify the ad creative type or add a custom identifier for later recognition.
adType	AdType	Required	Advert type, please use AdType.Interstitial

Description of the unitId Parameter Extension Fields

Parameter	Type	Description
unitId	string	Unique identifier for the ad unit, 32-character lowercase alphanumeric string, obtained from the MG Ad backend.
media	string	Supported ad media types. this field is optional. If left empty, the system will randomly return one of the ad types currently enabled in the MG backend. Available values: ● image: Image ad, supported by default ● web: Web ad, requires permission from MG Product Manager ● video: Video ad, supported by default
tag	string	Custom content used to identify the ad Control object

Return Value Description

Scenario	Description
ReturnValue = true	Ad displayed successfully.
ReturnValue = false	Ad display failed.

Complete Code Example

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

Couplet Ad

Description: Couplet ads are fixed on the left and right sides of the interface, suitable for PC web games and similar scenarios.

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

Parameter Description

Parameter	Type	Required	Description
parentControl	Control	Required	Main form object
unitId	string	Required	unitId supports two input methods; you can choose the one that best suits your needs: Simple Mode: Directly enter the ad slot’s unique identifier—a 32-character combination of lowercase letters and numbers—which can be obtained by creating the ad slot in the MG ad backend. This is suitable for scenarios where you only need to load ads without additional control information. Extended Mode: Pass a string in JSON format. This is suitable for scenarios where you need to specify the ad creative type or add a custom identifier for later recognition.
adType	AdType	Required	Advert type, please use AdType.Couplet

Description of the unitId Parameter Extension Fields

Parameter	Type	Description
unitId	string	Unique identifier for the ad unit, 32-character lowercase alphanumeric string, obtained from the MG Ad backend.
media	string	Supported ad media types. this field is optional. If left empty, the system will randomly return one of the ad types currently enabled in the MG backend. Available values: ● image: Image ad, supported by default ● web: Web ad, requires permission from MG Product Manager ● video: Video ad, supported by default
tag	string	Custom content used to identify the ad Control object
tag2	string	Custom content used to identify the ad Control object

Return Value Description

Scenario	Description
ReturnValue = true	Ad displayed successfully.
ReturnValue = false	Ad display failed.

Complete Code Example

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)
    {
    }
}

Rewarded Ad

Description: Rewarded video ads are used to grant rewards after users watch the entire ad, suitable for game settlement screens, revives, double reward claims, etc.

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

Parameter Description

Parameter	Type	Required	Description
parentControl	Control	Required	Main form object
unitId	string	Required	unitId supports two input methods; you can choose the one that best suits your needs: Simple Mode: Directly enter the ad slot’s unique identifier—a 32-character combination of lowercase letters and numbers—which can be obtained by creating the ad slot in the MG ad backend. This is suitable for scenarios where you only need to load ads without additional control information. Extended Mode: Pass a string in JSON format. This is suitable for scenarios where you need to specify the ad creative type or add a custom identifier for later recognition.
adType	AdType	Required	Advert type, please use AdType.Rewarded

Description of the unitId Parameter Extension Fields

Parameter	Type	Description
unitId	string	Unique identifier for the ad unit, 32-character lowercase alphanumeric string, obtained from the MG Ad backend.
mdeia	string	Supported ad types. this field is optional. If left empty, the system will randomly return one of the ad types currently enabled in the MG backend. Available values: ● web: Web ad, requires permission from MG Product Manager ● video: Video ad, supported by default
tag	string	Custom content used to identify the ad Control object
comment	string	Developer-defined custom parameter (requires URL encoding).
isFullScreen	bool	Whether to display in full screen. Optional; default is false (1024×768). Set to true for full screen.

Return Value Description

Scenario	Description
ReturnValue = true	Ad displayed successfully.
ReturnValue = false	Ad display failed.

Reward Granting Flow

plaintext

┌─────────────────┐
│   Call ShowAd()   │
│ (pass rewarded ad params) │
└────────┬────────┘
         ↓
┌─────────────────┐
│  User watches ad │
└────────┬────────┘
         ↓
┌─────────────────────────────────────────┐
│ Ad playback complete, callback returns Json data │
└────────┬────────────────────────────────┘
         ↓
┌─────────────────┐     ┌─────────────────┐
│ completeStatus=1 │     │ completeStatus=0│
│   (full watch)    │     │  (incomplete watch) │
└────────┬────────┘     └────────┬────────┘
         ↓                       ↓
┌─────────────────┐     ┌─────────────────┐
│  Grant in-game reward │     │   Do not grant reward   │
└────────┬────────┘     └─────────────────┘
         ↓
┌─────────────────────────────┐
│ Call ReportAdRewardFulfillment() │
│      Notify MG backend to verify     │
└─────────────────────────────┘

Complete Code Example

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)
        {
            // User watched the entire video, execute reward logic
            //...

            Task.Run(async () =>
            {
                // Notify MG service to verify the rewarded video reward
                _ = await AdvertManager.ReportAdRewardFulfillment(unitId, resourceId, materialId, rewardId);
            });
        }
    }
}

💡 Tips:

For rewarded video ads, the ad close callback must use completeStatus to determine whether to award a reward, to prevent rewards from being issued before the ad has been fully viewed.
The Comment field can be used to pass in-game parameters (e.g., reward type, amount). Be sure to URL-encode it when passing and decode it before use.
After successfully granting the reward, call ReportAdRewardFulfillment to notify the MG backend to complete verification.

Feed Ad

Description: Feed ads allow developers to specify an ad container, suitable for native ad feeds, in-list ads, etc. Developers need to define a container control (such as a Panel) in the Form in advance, and then pass that container to the SDK.

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

Parameter Description

Parameter	Type	Required	Description
parentControl	Control	Required	Control instances created by the developer
unitId	string	Required	unitId supports two input methods; you can choose the one that best suits your needs: Simple Mode: Directly enter the ad slot’s unique identifier—a 32-character combination of lowercase letters and numbers—which can be obtained by creating the ad slot in the MG ad backend. This is suitable for scenarios where you only need to load ads without additional control information. Extended Mode: Pass a string in JSON format. This is suitable for scenarios where you need to specify the ad creative type or add a custom identifier for later recognition.
adType	AdType	Required	Advert type, please use AdType.Feed

Description of the unitId Parameter Extension Fields

Parameter	Type	Description
unitId	string	Unique identifier for the ad unit, 32-character lowercase alphanumeric string, obtained from the MG Ad backend.
mdeia	string	Supported ad types. this field is optional. If left empty, the system will randomly return one of the ad types currently enabled in the MG backend. Available values: ● web: Web ad, requires permission from MG Product Manager ● video: Video ad, supported by default
width	int	Control width
height	int	Control height
tag	string	Custom content used to identify the ad Control object

Return Value Description

Scenario	Description
ReturnValue = true	Ad content successfully rendered into the specified container.
ReturnValue = false	Ad display failed.

Complete Code Example

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)
    {
    }
}

Embedded Ad

Description:Embedded ads allow developers to specify an ad container,For ads embedded within a page, custom UI area ad display, etc. Developers need to define a container control (such as a Panel) in the Form in advance, and then pass that container to the SDK.

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

Parameter Description

Parameter	Type	Required	Description
parentControl	Control	Required	Control instances created by the developer
unitId	string	Required	unitId supports two input methods; you can choose the one that best suits your needs: Simple Mode: Directly enter the ad slot’s unique identifier—a 32-character combination of lowercase letters and numbers—which can be obtained by creating the ad slot in the MG ad backend. This is suitable for scenarios where you only need to load ads without additional control information. Extended Mode: Pass a string in JSON format. This is suitable for scenarios where you need to specify the ad creative type or add a custom identifier for later recognition.
adType	AdType	Required	Advert type, please use AdType.Embedded

Description of the unitId Parameter Extension Fields

Parameter	Type	Description
unitId	string	Unique identifier for the ad unit, 32-character lowercase alphanumeric string, obtained from the MG Ad backend.
mdeia	string	Supported ad types. this field is optional. If left empty, the system will randomly return one of the ad types currently enabled in the MG backend. Available values: ● web: Web ad, requires permission from MG Product Manager ● video: Video ad, supported by default
width	int	Control width
height	int	Control height
tag	string	Custom content used to identify the ad Control object

Return Value Description

Scenario	Description
ReturnValue = true	Ad content successfully rendered into the specified container.
ReturnValue = false	Ad display failed.

Complete Code Example

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)
    {
    }
}

Exit Ad

Description: Exit-screen ads are triggered when exiting the game. To ensure a high ad display rate upon exiting the game, MG implements exit-screen ads in two steps:

After initialization is complete, load the exit-screen ad information into memory.
When exiting the game, directly display the exit-screen ad.

void SetupExitAd(string unitId)

Parameter Description

Parameter	Type	Required	Description
unitId	string	Required	Unique identifier for the ad unit, 32-character lowercase alphanumeric string, obtained from the MG Ad backend.

Complete Code Example

// exit ad
// Step 1. After initialization is successful, load the exit ad resource
private async void Form1_Load(object sender, EventArgs e)
{
    //...
    var result = await ApplicationManager.Initialize(YourAppId, YourSecretKey);
    if (result.ReturnValue)
    {
        // Initialization successful...
        
        // exit ad: load the exit ad resource
        AdvertManager.SetupExitAd("xxxxxxx");

        //...
    }
}

// exit ad
// Step 2. Display the exit ad when the application closes
private void Form1_FormClosing(object sender, FormClosingEventArgs e)
{
    _ = AdvertManager.ShowExitAdBlocking();
}

Ad Close Event

Note: The callback event for ad closure is typically registered in the page's constructor.

Event Return Parameter Description

Parameter Name	Parameter Description	Example
unitId	Ad unit ID provided by the developer	e333abaf22404c4a8d382c1e7ba42076
advertStatus	Ad unit status	1: Ad is playing normally; 2: Ad was closed by the backend; 3: No ad creative
The following parameters are specific to rewarded video ads
completeStatus	Ad playback status	1: Ad has finished playing; rewards can be issued; 0: Ad has not finished playing
comment	Pass-through parameter provided by the developer, URL-encoded	abc%2c123
rewardId	MG order number for the reward; used when the game reports redemption to MG after issuing the reward	String
resourceId	Resource ID	String
materialId	Ad creative ID	String

Complete Sample Code

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

private void AdvertManager_AdCloseEvent(object sender, string e)
{
    ShowMessage("Ad closed " + e);

    // Regular ad {"unitId":"6bf68881673540788d096b9ea4a3cedb","advertStatus":1,"resourceId":‘68d20656bd9558abfdf43465’," materialId":"d235efa86ccf44acbe7053af760031b6"}
    // Rewarded video ad {"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") // Rewarded ad; distribute reward items based on the return result
    {
        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"]; // Pass parameters through
        if (completeStatus == 1)
        {
            // Video has finished playing; distribute reward items
            //...

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

private void AdvertManager_AdClickEvent(object sender, string e)
{
    ShowMessage("Ad clicked " + e);
}

Ad Preload Feature

⚠️ Applicable Scenario Description: The preload feature is only intended for developers who have integrated multiple ad platforms (e.g., integrating AppLovin, Vungle, YLH, MG, etc. simultaneously). If only integrating the MG Ads single platform, it is recommended to directly use ShowAd() without using the preload mode.

The preload feature provides two separate interfaces to help you prepare ad materials in advance before displaying ads, improving display success rates.

Preload Interface (PreloadAd): Requests and caches ad materials in advance.
Show Preloaded Ad Interface (ShowPreloadAd): Displays a successfully preloaded ad.

💡 Tip: The preload feature is available for all ad formats. You can call the preload interface before you need to display an ad, and then display it via the show interface once the ad is ready.

Core Preload Rules

Rule	Description
Single Cache	The SDK caches only one ad per ad unit; cannot request another preload until the current one has been played.
Preload Next After Playback	After an ad is displayed, you can call PreloadAd() again to preload the next ad.
ID and Type Must Match	The adUnitId and adType in ShowPreloadAd() must exactly match those in PreloadAd().

Best Practice Example

Scenario: Rewarded video ad used to claim double rewards after a level ends.

plaintext

Before level starts
    ↓
Call PreloadAd() to preload rewarded video
    ↓
Player completes level
    ↓
Call ShowPreloadAd() to display ad
    ↓
Ad playback complete
    ↓
Start next level
    ↓
Call PreloadAd() again to preload the next one

Preload Interface

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

Parameter Description

Parameter	Type	Required	Description
unitId	string	Required	unitId supports two input methods; you can choose the one that best suits your needs: Simple Mode: Directly enter the ad slot’s unique identifier—a 32-character combination of lowercase letters and numbers—which can be obtained by creating the ad slot in the MG ad backend. This is suitable for scenarios where you only need to load ads without additional control information. Extended Mode: Pass a string in JSON format. This is suitable for scenarios where you need to specify the ad creative type or add a custom identifier for later recognition.
adType	AdType	Required	Advert type, please use AdType.FullScreen

Description of the unitId Parameter Extension Fields

Parameter	Type	Description
unitId	string	Unique identifier for the ad unit, 32-character lowercase alphanumeric string, obtained from the MG Ad backend.
mdeia	string	Supported ad types. this field is optional. If left empty, the system will randomly return one of the ad types currently enabled in the MG backend. Available values: ● web: Web ad, requires permission from MG Product Manager ● video: Video ad, supported by default
tag	string	Custom content used to identify the ad Control object

Return Value Description

Scenario	Description
ReturnValue = true	Preload successful, can call ShowPreloadAd to display the ad.
ReturnValue = false	Preload failed, use the standard ShowAd() or skip this ad display.

Complete Code Example (Interstitial Ad)

private async void PreloadInterstitialAd()
{
    var result = await AdvertisingManager.PreloadAd("0123456789abcdef0123456789abcdef", AdType.Interstitial);
    if (result.ReturnValue)
    {
        // Preload successful, can call ShowPreloadAd to display the ad
    }
    else
    {
        // Preload failed
    }
}

Show Preloaded Ad Interface

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

Parameter Description

Parameter	Type	Required	Description
parentControl	Control	Required	Main form or Control instances created by the developer
unitId	string	Required	unitId supports two input methods; you can choose the one that best suits your needs: Simple Mode: Directly enter the ad slot’s unique identifier—a 32-character combination of lowercase letters and numbers—which can be obtained by creating the ad slot in the MG ad backend. This is suitable for scenarios where you only need to load ads without additional control information. Extended Mode: Pass a string in JSON format. This is suitable for scenarios where you need to specify the ad creative type or add a custom identifier for later recognition.
adType	AdType	Required	Advert type, please use AdType.FullScreen

Description of the unitId Parameter Extension Fields

Parameter	Type	Description
unitId	string	Unique identifier for the ad unit, 32-character lowercase alphanumeric string, obtained from the MG Ad backend.
mdeia	string	Supported ad types. this field is optional. If left empty, the system will randomly return one of the ad types currently enabled in the MG backend. Available values: ● web: Web ad, requires permission from MG Product Manager ● video: Video ad, supported by default
tag	string	Custom content used to identify the ad Control object

⚠️ Note: Before calling this interface, ensure that the corresponding ad unit has been successfully preloaded via PreloadAd.

Code Examples

4.2.1 Display Preloaded Full-screen Ad

public async void ShowPreloadFullScreenAd()
{
    var result = await AdvertManager.ShowPreloadAd(this, FullScreenAdUnitId, AdType.FullScreen);
    if (result.ReturnValue)
    {
        // Ad display complete
    }
    else
    {
        // Ad display failed. Possible reasons: ad unit not preloaded, preload expired, network issues, etc.
    }
}

4.2.2 Display Preloaded Banner Ad

public async void ShowPreloadBannerAd()
{
    var result = await AdvertManager.ShowPreloadAd(this, BannerUnitId, AdType.Banner);
    if (result.ReturnValue)
    {
        // Ad display complete
    }
    else
    {
        // Ad display failed
    }
}

4.2.3 Display Preloaded Interstitial Ad

public async void ShowPreloadInterstitialAd()
{
    var result = await AdvertManager.ShowPreloadAd(this, InterstitialUnitId, AdType.Interstitial);
    if (result.ReturnValue)
    {
        // Ad display complete
    }
    else
    {
        // Ad display failed
    }
}

4.2.4 Display Preloaded Couplet Ad

public async void ShowPreloadCoupletAd()
{
    var result = await AdvertManager.ShowPreloadAd(this, CoupletUnitId, AdType.Couplet);
    if (result.ReturnValue)
    {
        // Ad display complete
    }
    else
    {
        // Ad display failed
    }
}

4.2.5 Display Preloaded Rewarded Ad

public async void ShowPreloadRewardAd()
{
    dynamic jsonObj = new
    {
        unitId = RewardedUnitId,
        comment = Uri.EscapeDataString("id123,abc,$9.99"), // Transparent Parameters
        isFullScreen = false  // Whether to display in full screen; this is optional. The default is false (1024×768); set to true to display in full screen.
    };
    string json = JsonConvert.SerializeObject(jsonObj);
    var result = await AdvertManager.ShowPreloadAd(this, json,  AdType.Rewarded);
    if (result.ReturnValue)
    {
       // Ad display  
    }
    else
    {
       // Ad display failed
    }
}

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)
        {
            //Ad display completion; reward issued
            //...

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

4.2.6 Display Preloaded Feed Ad

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)
    {
        // Ad display complete
    }
    else
    {
        // Ad display failed
    }
}

4.2.7 Display Preloaded Embeded Ad

public async void ShowPreloadEmbededAd()
{
     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)
    {
        // Ad display complete
    }
    else
    {
        // Ad display failed
    }
}

Preload Feature Call Flow

plaintext

┌─────────────────────────────────────────────────────────────────┐
│                        App Launch                               │
└─────────────────────────────┬───────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                     Call OpenCmp() and Initialize()             │
└─────────────────────────────┬───────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      SDK Initialization Complete                │
└─────────────────────────────┬───────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│            【Preload Mode】Call PreloadAd() to preload ad       │
│                     (e.g., preload before level start)          │
└─────────────────────────────┬───────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                    Check if preload succeeded                   │
└─────────────┬───────────────────────────────┬───────────────────┘
              ↓                               ↓
      ┌──────────────┐                ┌──────────────┐
      │ Success(true)│                │Failure(false)│
      └───────┬──────┘                └───────┬──────┘
              ↓                               ↓
┌─────────────────────────┐       ┌─────────────────────────────┐
│Wait for ad display trigger│     │ use the standard ShowAd()   │
│(e.g., after player clears level)│ or skip this ad display     │
└─────────────┬───────────┘       └─────────────────────────────┘
              ↓
┌─────────────────────────────────────────────────────────────────┐
│           Call ShowPreloadAd() to display the preloaded ad      │
└─────────────────────────────┬───────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                         Ad display complete                     │
└─────────────────────────────┬───────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│            Call PreloadAd() again to preload the next ad        │
│                 (prepare for the next display)                  │
└─────────────────────────────────────────────────────────────────┘

Frequently Asked Questions (FAQ)

Q1: Why must I create an ad unit in the backend first?

A: The ad unitID is the unique identifier for ad requests. It must be pre-created and configured with ad materials in the MG Ad backend to successfully request and display ads.

Q2: What should I do if ad display fails?

A: Common causes and solutions:

Error Type	Solution
Incorrect ad unit ID	Verify the 32-character lowercase alphanumeric ID in the backend.
Network issues	Check device network connection.
No available ad materials	Contact MG Product Manager to add ad materials of the appropriate size and format.
Preload not completed	Ensure PreloadAd succeeded before calling ShowPreloadAd.

Q3: How to grant rewards for rewarded video?

A: Check completeState.IsCompleted in the ShowRewardAd callback:

If true, the user watched the entire video and reward can be granted.
After granting the reward, you must call ReportAdRewardFulfillment() to notify the MG backend for verification.

Q4: What are the benefits of the preload feature?

Loads ad materials in advance, reducing user wait time.
Improves ad display success rate.
Suitable for scenarios requiring precise control over ad display timing.

Q5: Can I call ads before OpenCmp and Initialize are complete?

A: No. You must complete CMP and SDK initialization first to properly call ad functionality. Otherwise, ad requests may fail or cause compliance issues.

Q6: When should I use the preload feature?

A: Only when your app has integrated multiple ad platforms (e.g., using Pangle, YLH, MG, etc. simultaneously) is it recommended to use preload mode. For single-platform scenarios, directly using ShowAd() is sufficient.

Q7: Can preload cache multiple ads simultaneously?

A: No. Each ad unit caches only one ad; you cannot request another preload until the current one has been played. After an ad is displayed, call PreloadAd() again to preload the next one.

Q8: What if ShowPreloadAd() fails?

A: Suggested handling order:

Check whether the corresponding ad unit was preloaded successfully.
Check whether the ad unit ID matches.
Check whether the ad type matches.
Fall back to the normal ShowAd() mode.
Abandon this advertising display

Q9: What types of controls can be used as the Container for custom ads?

A: Supports Panel, ContentControl, UserControl, etc.

Q10: How do I actively close a currently displayed ad?

A: Simply remove the corresponding container control.

Introduction​

Pre-Integration Preparation​

Ad Integration​

Full-screen Ad​

Banner Ad​

Interstitial Ad​

Couplet Ad​

Rewarded Ad​

Feed Ad​

Embedded Ad​

Exit Ad​

Ad Close Event​

Ad Preload Feature​

Preload Interface​

Show Preloaded Ad Interface​

Preload Feature Call Flow​

Frequently Asked Questions (FAQ)​

Introduction

Pre-Integration Preparation

Ad Integration

Full-screen Ad

Banner Ad

Interstitial Ad

Couplet Ad

Rewarded Ad

Feed Ad

Embedded Ad

Exit Ad

Ad Close Event

Ad Preload Feature

Preload Interface

Show Preloaded Ad Interface

Preload Feature Call Flow

Frequently Asked Questions (FAQ)