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 MediaType
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

Ad Call Flow

App Launch
    ↓
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 namespace MiracleGamesAd;
using namespace 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

Ad Material Type Description

Each ad format supports specifying the material type via the MediaType parameter. Available values are:

MediaType 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)
{
    // 广告展示成功
}
else
{
    // 广告展示失败
}

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.

IAsyncOperation<AsyncProcessResult> ShowAd(string unitId, AdType adType, FullScreenAdSettingOptions options)

Parameter Description

Parameter	Type	Required	Description
adUnitId	string	Required	Unique identifier for the ad unit, 32-character lowercase alphanumeric string, obtained from the MG Ad backend.
adType	AdType	Required	Ad format. For full-screen ads, use AdType.FullScreen.
options	FullScreenAdSettingOptions	Optional	Ad configuration parameters. Uses defaults if not set.

FullScreenAdSettingOptions Object Description

Parameter	Type	Description
MediaType	string	Supported ad types. Available values: ● image: Image ad, supported by default ● web: Web ad, requires permission from MG Product Manager ● video: Video ad, supported by default

Return Value Description

Scenario	Description
ReturnValue = true	Ad displayed successfully and user has closed the ad.
ReturnValue = false	Ad display failed.

Complete Code Example

Platform::String^ MainPage::FullScreenAd()
{
  auto opt = ref new MiracleGamesAd::Models::FullScreenAdSettingOptions();
  opt->MediaType = "image";
  auto initTask = Concurrency::create_task(MiracleGamesAd::AdvertisingManager::ShowAd("0123456789abcdef0123456789abcdef", MiracleGamesAd::Models::AdType::FullScreen, opt));
  initTask.then([](MiracleGamesAd::Services::Core::Common::AsyncProcessResult^ result1)
  {
    if (result1->ReturnValue)
    {
      // Ad displayed successfully and user has closed the ad
    }
    else
    {
      // Ad display failed, continue original flow directly
      // Common reasons: incorrect ad unit configuration, network issues, no available ad materials
    }
  });;

	return "";
}

Banner Ad

Description: Banner ads are typically fixed at the top, bottom, or a specified area of the interface, suitable for game main interfaces, etc.

IAsyncOperation<AsyncProcessResult> ShowAd(string unitId, AdType adType, BannerAdSettingOptions options)

Parameter Description

Parameter	Type	Required	Description
adUnitId	string	Required	Unique identifier for the ad unit, 32-character lowercase alphanumeric string, obtained from the MG Ad backend.
adType	AdType	Required	Ad format. For banner ads, use AdType.Banner.
options	BannerAdSettingOptions	Optional	Ad configuration parameters. Uses defaults if not set.

BannerAdSettingOptions Object Description

Parameter	Type	Description
MediaType	string	Supported ad types. Available values: ● image: Image ad, supported by default ● web: Web ad, requires permission from MG Product Manager
VerticalAlignment	VerticalAlignment	Vertical alignment. Available values: ● Top: Top alignment ● Center: Center alignment ● Bottom: Bottom alignment (recommended and default)
HorizontalAlignment	HorizontalAlignment	Horizontal alignment. Available values: ● Left: Left alignment ● Center: Center alignment (recommended and default) ● Right: Right alignment

Return Value Description

Scenario	Description
ReturnValue = true	Ad displayed successfully, callback triggered when user clicks close button.
ReturnValue = false	Ad display failed.

Complete Code Example

Platform::String ^MainPage::MainScreen_BannerAd()
{
  auto opt = ref new MiracleGamesAd::Models::BannerAdSettingOptions();
  opt->MediaType = "image";
  opt->HorizontalAlignment = Windows::UI::Xaml::HorizontalAlignment::Center;
  opt->VerticalAlignment = Windows::UI::Xaml::VerticalAlignment::Bottom;
  auto initTask = Concurrency::create_task(MiracleGamesAd::AdvertisingManager::ShowAd("0123456789abcdef0123456789abcdef", MiracleGamesAd::Models::AdType::Banner, opt));
  initTask.then([](MiracleGamesAd::Services::Core::Common::AsyncProcessResult^ result)
  {
    if (result->ReturnValue)
    {
      // Ad displayed successfully, triggered when user closes the ad

    }
    else
    {
      // Ad display failed
    }
  });
	return "";
}

Interstitial Ad

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

IAsyncOperation<AsyncProcessResult> ShowAd(string unitId, AdType adType, InterstitialAdSettingOptions options)

Parameter Description

Parameter	Type	Required	Description
adUnitId	string	Required	Unique identifier for the ad unit, 32-character lowercase alphanumeric string, obtained from the MG Ad backend.
adType	AdType	Required	Ad format. For interstitial ads, use AdType.Interstitial.
options	InterstitialAdSettingOptions	Optional	Ad configuration parameters. Uses defaults if not set.

InterstitialAdSettingOptions Object Description

Parameter	Type	Description
MediaType	string	Supported ad types. Available values: ● image: Image ad, supported by default ● web: Web ad, requires permission from MG Product Manager ● video: Video ad, supported by default

Return Value Description

Scenario	Description
ReturnValue = true	Ad displayed successfully and user has closed the ad.
ReturnValue = false	Ad display failed.

Complete Code Example

Platform::String^ MainPage::MainScreen_InterstitialAD()
{
  auto opt = ref new MiracleGamesAd::Models::InterstitialAdSettingOptions();
  opt->MediaType = "image";
  auto initTask = Concurrency::create_task(MiracleGamesAd::AdvertisingManager::ShowAd("0123456789abcdef0123456789abcdef", MiracleGamesAd::Models::AdType::Interstitial, opt));
  initTask.then([](MiracleGamesAd::Services::Core::Common::AsyncProcessResult^ result)
  {
    if (result->ReturnValue)
    {
        // Ad displayed successfully and user has closed the ad
        // Resume business logic interrupted by the ad here
    }
    else
    {
        // Ad display failed, continue original flow directly
    }
  });
	return "";
}

Couplet Ad

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

IAsyncOperation<AsyncProcessResult> ShowAd(string unitId, AdType adType, CoupletAdSettingOptions options)

Parameter Description

Parameter	Type	Required	Description
adUnitId	string	Required	Unique identifier for the ad unit, 32-character lowercase alphanumeric string, obtained from the MG Ad backend.
adType	AdType	Required	Ad format. For couplet ads, use AdType.Couplet.
options	CoupletAdSettingOptions	Optional	Ad configuration parameters. Uses defaults if not set.

CoupletAdSettingOptions Object Description

Parameter	Type	Description
MediaType	string	Supported ad types. Available values: ● image: Image ad, supported by default ● web: Web ad, requires permission from MG Product Manager

Return Value Description

Scenario	Description
ReturnValue = true	Ad displayed successfully and user has closed the ad.
ReturnValue = false	Ad display failed.

Complete Code Example

Platform::String ^ ::MainPage::MainScreen_CoupletAd()
{
  auto opt = ref new MiracleGamesAd::Models::CoupletAdSettingOptions();
  opt->MediaType = "image";
  auto initTask = Concurrency::create_task(MiracleGamesAd::AdvertisingManager::ShowAd("0123456789abcdef0123456789abcdef", MiracleGamesAd::Models::AdType::Couplet, opt));
  initTask.then([](MiracleGamesAd::Services::Core::Common::AsyncProcessResult^ result)
  {
    if (result->ReturnValue)
    {
        // Ad displayed successfully and user has closed the ad
    }
    else
    {
        // Ad display failed
    }
  });
	return "";
}

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.

IAsyncOperation<AsyncProcessResult> ShowAd(string unitId, AdType adType, RewardAdSettingOptions options)

Parameter Description

Parameter	Type	Required	Description
adUnitId	string	Required	Unique identifier for the ad unit, 32-character lowercase alphanumeric string, obtained from the MG Ad backend.
adType	AdType	Required	Ad format. For rewarded video, use AdType.Reward.
options	RewardAdSettingOptions	Required	Ad configuration parameters.

RewardAdSettingOptions Object Description

Parameter	Type	Description
MediaType	string	Supported ad types. Available values: ● web: Web ad, requires permission from MG Product Manager ● video: Video ad, supported by default
Comment	string	Developer-defined custom parameter (requires URL encoding).

Return Value Description

After ad playback completes, the Tag property in the returned result carries a RewardAdCompleteState object with the following fields:

Property	Type	Description
IsCompleted	bool	Whether the user watched the entire video and meets reward criteria.
Comment	string	Passthrough parameter: Developer-defined custom parameter (requires URL encoding). Passed in when calling the ad interface and returned unchanged in the ad completion callback. Developers can use this parameter to identify reward type, amount, etc., for rewarding.
RewardId	string	Unique reward identifier, used to verify the video reward with the MG service.

Reward Granting Flow

plaintext

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

Complete Code Example

Platform::String ^ ::MainPage::MainScreen_RewardAd()
{
auto opt = ref new MiracleGamesAd::Models::RewardAdSettingOptions();
opt->MediaType = "video";// web (requires permission), video
opt->Comment = "{\"coin\":100}";//Developer-defined custom parameter

auto initTask = Concurrency::create_task(MiracleGamesAd::AdvertisingManager::ShowAd("0123456789abcdef0123456789abcdef", MiracleGamesAd::Models::AdType::Reward, opt));
initTask.then([](MiracleGamesAd::Services::Core::Common::AsyncProcessResult^ result)
{
  if (result->ReturnValue) 
  {
    auto completeState = dynamic_cast<MiracleGamesAd::Models::RewardAdCompleteState^>(result->Tag);
    if (completeState != nullptr)
    {
      if (completeState->IsCompleted)
      {
      // User watched the entire video, execute reward logic
      auto comment = completeState->Comment;
      // Notify MG service to verify the rewarded video reward
      MiracleGamesAd::AdvertisingManager::ReportAdRewardFulfillment(completeState->RewardId);
      }
      else
      {
      // User did not watch the entire video, do not grant reward
      }
    }
  }
  else
  {
  // Ad display failed or playback error, do not grant reward
  }
});
return "";
}

💡 Tips:

For rewarded video ads, you must determine whether to grant the reward based on IsCompleted in the callback to avoid granting rewards for incomplete views.
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.

Exit Ad

Description: Exit ads are triggered when exiting the game. To ensure a high pop-up rate for exit ads, MG recommends preloading the exit ad information into memory immediately after initialization. When exiting the game, the SDK will automatically display the exit ad directly.

void SetupExitunitId(string adUnitId)

Parameter Description

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

Complete Code Example

// Call after SDK initialization is complete
MiracleGamesAd::AdvertisingManager::SetupExitunitId("0123456789abcdef0123456789abcdef");

UWP Project Configuration for Exit Ad

Exit ads require intercepting the system close event when the application exits and displaying the ad before closing. UWP applications do not allow intercepting exit events by default, so the following configuration is required:

Step	Description
1	Change the Target version in Properties → Application of the main project to 19041 (or higher).
2	Right-click Package.appxmanifest, select "XML Editor" to open and edit.
3	Add `xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"` to the Package tag, and add `rescap` to IgnorableNamespaces.
4	Add the following under the Capabilities node: `<rescap:Capability Name="confirmAppClose"/>`
5	Save.

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

IAsyncOperation<AsyncProcessResult> PreloadAd(string adUnitId, AdType adType, string mediaType)

Parameter Description

Parameter	Type	Required	Description
adUnitId	string	Required	Unique identifier for the ad unit, 32-character lowercase alphanumeric string.
adType	AdType	Required	Ad unit type.
mediaType	string	Optional	Ad material type. Available values: ● image: Image ad, supported by default ● web: Web ad, requires permission from MG Product Manager ● video: Video ad, supported by default

Return Value Description

Scenario	Description
ReturnValue = true	Preload successful, can call ShowPreloadAd to display the ad.
ReturnValue = false	Preload failed, need to retry PreloadAd.

Complete Code Example (Interstitial Ad)

Platform::String^ MainPage::PreloadAd()
{
auto initTask = Concurrency::create_task(MiracleGamesAd::AdvertisingManager::PreloadAd("0123456789abcdef0123456789abcdef", MiracleGamesAd::Models::AdType::Interstitial, "image"));
initTask.then([](MiracleGamesAd::Services::Core::Common::AsyncProcessResult^ result)
{
  if (result->ReturnValue)
  {
	// Preload successful, can call ShowPreloadAd to display the ad
  }
  else
  {
  // Preload failed, recommend retrying PreloadAd
  }
});
return "";
}

Show Preloaded Ad Interface

IAsyncOperation<AsyncProcessResult> ShowPreloadAd(string unitId, AdType adType, IAdSettingOptions options)

Parameter Description

Parameter	Type	Required	Description
adUnitId	string	Required	Unique identifier for the ad unit, must match the ID used in preload.
adType	AdType	Required	Ad unit type, must match the type used in preload.
options	IAdSettingOptions	Optional	No configuration needed for standard ads (full-screen, interstitial, banner, couplet); for rewarded video or custom ads, pass the corresponding configuration object (e.g., RewardAdSettingOptions, CustomAdSettingOptions).

⚠️ 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

Platform::String^ MainPage::ShowPreloadFullScreenAd()
{
  auto initTask = Concurrency::create_task(MiracleGamesAd::AdvertisingManager::ShowPreloadAd("0123456789abcdef0123456789abcdef", MiracleGamesAd::Models::AdType::FullScreen));
  initTask.then([](MiracleGamesAd::Services::Core::Common::AsyncProcessResult^ result)
  {
    if (result->ReturnValue)
    {
       // Ad display complete
    }
    else
    {
        // Ad display failed. Possible reasons: ad unit not preloaded, preload expired, network issues, etc.
    }
  });
return "";
}

4.2.2 Display Preloaded Banner Ad

Platform::String^ MainPage::ShowPreloadBannerAd()
{
auto initTask = Concurrency::create_task(MiracleGamesAd::AdvertisingManager::ShowPreloadAd("0123456789abcdef0123456789abcdef", MiracleGamesAd::Models::AdType::Banner));
initTask.then([](MiracleGamesAd::Services::Core::Common::AsyncProcessResult^ result)
{
  if (result->ReturnValue)
  {
   // Ad display complete
  }
  else
  {
    // Ad display failed
  }
});
return "";
}

4.2.3 Display Preloaded Interstitial Ad

Platform::String^ MainPage::ShowPreloadInterstitialAd()
{
auto initTask = Concurrency::create_task(MiracleGamesAd::AdvertisingManager::ShowPreloadAd("0123456789abcdef0123456789abcdef", MiracleGamesAd::Models::AdType::Interstitial));
initTask.then([](MiracleGamesAd::Services::Core::Common::AsyncProcessResult^ result)
{
  if (result->ReturnValue)
  {
  //Ad display complete
  }
  else
  {
    // Ad display failed
  }
});
return "";
}

4.2.4 Display Preloaded Couplet Ad

Platform::String^ MainPage::ShowPreloadCoupletAd()
{
auto initTask = Concurrency::create_task(MiracleGamesAd::AdvertisingManager::ShowPreloadAd("0123456789abcdef0123456789abcdef", MiracleGamesAd::Models::AdType::Couplet));
initTask.then([](MiracleGamesAd::Services::Core::Common::AsyncProcessResult^ result)
{
  if (result->ReturnValue)
  {
    // Ad display complete
  }
  else
  {
     // Ad display failed
  }
});
return "";
}

4.2.5 Display Preloaded Rewarded Ad

📝 Note: Since the ad material type was already specified during preload (via the mediaType parameter in PreloadAd), the RewardAdSettingOptions object does not need to configure the MediaType parameter. Only passthrough parameters like Comment need to be passed.

Platform::String^ MainPage::ShowPreloadRewardAd()
{
auto opt = ref new MiracleGamesAd::Models::RewardAdSettingOptions();
opt->Comment = "{\"coin\":100}";

auto initTask = Concurrency::create_task(MiracleGamesAd::AdvertisingManager::ShowPreloadAd("0123456789abcdef0123456789abcdef", MiracleGamesAd::Models::AdType::Reward, opt));
initTask.then([](MiracleGamesAd::Services::Core::Common::AsyncProcessResult^ result)
{
  if (result->ReturnValue) 
  {
  auto completeState = dynamic_cast<MiracleGamesAd::Models::RewardAdCompleteState^>(result->Tag);
    if (completeState != nullptr)
    {
      if (completeState->IsCompleted)
      {
	      // User watched the entire video, execute reward logic
	      auto comment = completeState->Comment;
	      MiracleGamesAd::AdvertisingManager::ReportAdRewardFulfillment(completeState->RewardId);
      }
    }
  }
  else
  {
   //  Ad display failed
  }
});
return "";
}

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 │       │ Retry PreloadAd() or       │
│ (e.g., after player clears level) │       │ fallback to normal ShowAd() │
└─────────────┬───────────┘       └─────────────────────────────┘
              ↓
┌─────────────────────────────────────────────────────────────────┐
│           Call ShowPreloadAd() to display the preloaded ad      │
└─────────────────────────────┬───────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                         Ad display complete                     │
└─────────────────────────────┬───────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│            Call PreloadAd() again to preload the next ad        │
│                 (prepare for the next display)                  │
└─────────────────────────────────────────────────────────────────┘

Close Ad Interface

Description: Used to actively close the currently displayed ad. Suitable for scenarios where developers need to actively end ad display due to specific business logic, such as page transitions, game exit, scene destruction, etc.

void CloseAd(string adUnitId)

Parameter Description

Parameter	Type	Required	Description
adUnitId	string	Required	Unique identifier of the ad unit to close, 32-character lowercase alphanumeric string.

Return Value Description

No return value. After calling, the SDK will attempt to close the ad content currently being displayed for the specified ad unit. If no ad is currently being displayed, the call has no effect.

Complete Code Example

public void CloseBannerAd()
{
    MiracleGamesAd::AdvertisingManager::CloseAd("0123456789abcdef0123456789abcdef");
}

Notes

Only affects ads currently being displayed.
If no ad is currently being displayed for the specified ad unit, the call has no effect.
Recommended to call when destroying a page, switching scenes, or exiting the game.

Frequently Asked Questions (FAQ)

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

A: The ad unit ID 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: Why does the exit ad require modifying the manifest file?

A: Exit ads need to intercept the exit event when the application closes and display an ad, which requires the confirmAppClose permission. Modifying the manifest file declares this permission. For details, see the configuration explanation in Section 3.7.

Q7: 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.

Q8: 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.

Q9: 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.
Retry PreloadAd().
Fall back to the normal ShowAd() mode.

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

A: Supports Panel, ContentControl, UserControl, and their derived classes, such as Border, StackPanel, Grid, ContentControl, etc.

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

A: Call the CloseAd(string adUnitId) interface, passing the ad unit ID you wish to close. This interface is suitable for removing persistent ads like banners and custom ads in advance.

Introduction​

Pre-Integration Preparation​

Ad Integration​

Full-screen Ad​

Banner Ad​

Interstitial Ad​

Couplet Ad​

Rewarded Ad​

Exit Ad​

Ad Preload Feature​

Preload Interface​

Show Preloaded Ad Interface​

Preload Feature Call Flow​

Close Ad Interface​

Frequently Asked Questions (FAQ)​

Introduction

Pre-Integration Preparation

Ad Integration

Full-screen Ad

Banner Ad

Interstitial Ad

Couplet Ad

Rewarded Ad

Exit Ad

Ad Preload Feature

Preload Interface

Show Preloaded Ad Interface

Preload Feature Call Flow

Close Ad Interface

Frequently Asked Questions (FAQ)