Ad Integration Guide

Introduction

Before integrating ads, the SDK initialization must be completed first.

MG Ads supports 【Splash Ad 19201080】【Exit Ad】【Banner 72890】【Interstitial 1024768】【Couplet 300600】【Rewarded 1024*768】【Feed】【Embedded】 ad functionalities. Developers need to create and manage the container that displays the ads and pass the container's handle to the SDK.

Splash Ad

Global Variable Definitions

const char* YourAppId = "692e5d6a207c9dd383ba56f7";
const char* YourSecretKey = "MIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQgiJm0JnjgpDjxEKKzH/7kc3N8r+nvmHko1EPV6My6WG6gCgYIKoZIzj0DAQehRANCAAR2z1Eih/EOFjBMbpgMdvfYjUqFEVaRbnEeYEYZrp4K3pGj1YoY0/dmRRQ58OaHfxKotbFDMwNDBpuHwtxTqGE6";
const char* SplashAdUnitId = "768338453d614f3aad85eea7e3916e7e";         //Splash Ad:1920 x 1080
const char* ExitAdUnitId = "7cdc7614b69c4118933e2067e6e14d01";           //Exit Ad:1920 x 1080
const char* BannerUnitId = "e9b34829a2ad4a959874f9a180278bfe";           //Banner:728 x 90
const char* InterstitialUnitId = "e333abaf22404c4a8d382c1e7ba42076";     //Interstitial:1024 x 768
const char* CoupletUnitId = "c68cd45e8e374ccd98a704887e5b3582";          //Couplet:300 x 600
const char* RewardedUnitId = "0f505442fac84f098e81d6f2ca04abe1";           //Rewarded Ad:1024x768
const char* FeedUnitId = "6fab0e0912db497cbf886c2c4a9b131c";             //Feed, the ad control is maintained by the developer
const char* EmbeddedUnitId = "e065e44302314b888dcb6074fa6efd69";         //Embedded, the ad control is maintained by the developer

The splash ad slot is typically implemented after the application starts, within the SDK initialization completion event.

//Callback function for initialization completion
void onInitCompleteEvent(char* s) {
    try
    {
        nlohmann::json json_obj = nlohmann::json::parse(s); //{"success":true,"data":""}
        bool success = json_obj["success"];
        if (success) {
            AppendLog(L"Initialization successful");

            //Exit Screen Ad; Step1. Load exit screen ad resources after successful initialization
            setupExitAd(hDLL);

            //Post a message to the UI thread to call the splash screen ad
            PostMessage(g_hwndMain, WM_SHOW_OPENSCREEN_ADVERT, 0, NULL);
        }
    }
    catch (const std::exception&)
    { 
    } 
}

//In the UI thread, create the container to display the ad and call the SDK's ad interface
case WM_SHOW_OPENSCREEN_ADVERT:
{
    CreateSplashScreenAdPanel(g_hwndMain);//Create splash screen ad container
    RECT clientRect;
    if (GetClientRect(g_hwndMain, &clientRect)) {
        int clientWidth = clientRect.right - clientRect.left;
        int clientHeight = clientRect.bottom - clientRect.top;
        nlohmann::json json_obj = {
         {"unitId", SplashAdUnitId},
         {"appType", 1},//1.App 2.Game
         {"adType", 1},//Splash Ad
         {"handle", reinterpret_cast<int>(g_hPnlSplashScreen)},
         {"width", clientWidth},//For splash ad, pass the program's width and height
         {"height", clientHeight},
         {"parentWidth", clientWidth},
         {"parentHeight", clientHeight}
        };
        std::string jsonStr = json_obj.dump();
        showAd(jsonStr.c_str());
    }
    return 0;
}

//SDK ad interface
void showAd(const char* json) {
    try
    { 
        // Ensure COM is initialized before calling
        if (!g_comInitialized) {
            HRESULT hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);
            if (SUCCEEDED(hr)) {
                g_comInitialized = true;
            }
        }

        ShowAd func = (ShowAd)GetProcAddress(hDLL, "ShowAd");
        if (func) {
            int result = func(json);
            if (result == 1) {
                // success 
            }
        } 
    }
    catch (const std::exception& ex)
    {
    }
}

Exit Ad

The exit ad is triggered when exiting the game. To ensure the pop-up rate of the ad upon game exit, MG implements the exit screen ad in two steps:

1.After initialization is complete, load the exit screen ad information into memory.

2.When exiting the game, directly display the exit screen ad.

//Step1. After successful initialization, load exit screen ad resources
void setupExitAd(HINSTANCE hdll) {
    if (auto func = (SetupExitAd)GetProcAddress(hdll, "SetupExitAd")) {
        func(ExitAdUnitId); 
        AppendLog(L"Load the resources for MG exit ad");
    }
}

// Step2. When the program closes, pop up and display the exit ad
void showExitAdBlocking(HINSTANCE hdll) {
    if (auto func = (ShowExitAdBlocking)GetProcAddress(hdll, "ShowExitAdBlocking")) {
        func();
        AppendLog(L"show fallback screen advert");
    }
}

case ID_BTN_AD3:
{
    CreateBannerAdPanel(hWnd);//Create ad container 
    int containerHandle = reinterpret_cast<int>(g_hPnlBanner);
    nlohmann::json json_obj = {
        {"unitId", BannerUnitId},
        {"media", "image"},
        {"appType", 1},
        {"adType", 3},//Banner
        {"handle", containerHandle}
    };
    std::string jsonStr = json_obj.dump(); 
    showAd(jsonStr.c_str());
    break;
} 

Interstitial Ad

case ID_BTN_AD4:
{
    CreateInterstitialAdPannel(hWnd);//Create ad container 
    nlohmann::json json_obj = {
       {"unitId", InterstitialUnitId},
       {"appType", 1},
       {"adType", 4},//Interstitial
       {"handle", reinterpret_cast<int>(g_hPnlInterstitial)}
    };
    std::string jsonStr = json_obj.dump();
    showAd(jsonStr.c_str()); 
    break;
} 

Couplet Ad

case ID_BTN_AD5:
{
    CreateCoupletAdPannel(hWnd);//Create ad container
    nlohmann::json json_obj = {
        {"unitId", CoupletUnitId},
        {"appType", 1},
        {"adType", 5},//Couplet
        {"handle", reinterpret_cast<int>(g_hPnlCoupletLeft)},
        {"handle2", reinterpret_cast<int>(g_hPnlCoupletRight)}
    };
    std::string jsonStr = json_obj.dump();
    showAd(jsonStr.c_str()); 
    break;
} 

Rewarded

case ID_BTN_AD6:
{   
    CreateRewardAdPannel(hWnd);
    nlohmann::json json_obj = {
         {"unitId", RewardedUnitId},
         {"comment", "abc123"},//Passthrough parameter, frontend needs to perform urlEncode; it will be returned unchanged in the ad close callback event
         {"appType", 1},
         {"adType", 6},//Rewarded Video
         {"handle", reinterpret_cast<int>(g_hPnlReward)},
         {"width", 1024},
         {"height", 768}
    };
    std::string jsonStr = json_obj.dump();
    showAd(jsonStr.c_str());
    break;
}

Feed

Feed ad require the developer to create and maintain the control, and pass the control instance to the SDK.

case ID_BTN_AD7:
{ 
    int containerHandle = reinterpret_cast<int>(g_hPnlInformationFlow);
    nlohmann::json json_obj = {
        {"unitId", FeedUnitId},
        {"media", "image"},
        {"appType", 1},
        {"adType", 7},//Feed
        {"width", 400},//For Feed, pass the container's width and height
        {"height", 50},
        {"handle", containerHandle}
    };
    std::string jsonStr = json_obj.dump();
    showAd(jsonStr.c_str()); 
    break;
}

Embedded

Embedded ads require the developer to create and maintain the control, and pass the control instance to the SDK.

case ID_BTN_AD8:
{ 
    int containerHandle = reinterpret_cast<int>(g_hPnlEmbedded);
    nlohmann::json json_obj = {
        {"unitId", EmbeddedUnitId},
        {"media", "image"},
        {"appType", 1},
        {"adType", 8},//Embedded
        {"width", 200},//For embedded ads, pass the container's width and height
        {"height", 200},
        {"handle", containerHandle}
    };
    std::string jsonStr = json_obj.dump();
    showAd(jsonStr.c_str());
    break;
}

Ad Close Event

Ad close event parameter description

Parameter Name	Description	Example
unitId	The ad slot ID passed by the developer	e333abaf22404c4a8d382c1e7ba42076
advertStatus	Ad slot status	1: Ad normal; 2: Ad closed by backend; 3: No ad creative
The following parameters are only available for rewarded video ads
completeStatus	Ad playback status	1: Ad playback finished, reward can be issued; 0: Ad playback not finished
comment	Passthrough parameter passed by the developer, URL encoded	abc%2c123
rewardId	MG order number for the reward, used when the game reports fulfillment to MG after issuing the reward	String
resourceId	Resource Id	String
materialId	material Id	String

//Callback function when ad closes
void onAdCloseEvent(char* s) {
    AppendLog(L"onAdCloseEvent: %hs", s);
    //...
    // Destroy Ad pannel 
     
    // Send to UI thread
    char* jsonCopy = _strdup(s);
    PostMessage(g_hwndMain, WM_DESTROY_ADVERT, 0, reinterpret_cast<LPARAM>(jsonCopy));
}

//For rewarded video ads, report order fulfillment to MG
bool reportAdRewardFulfillment(const char* unitId, const char* resourceId, const char* materialId, const char* rewardId) {
    ReportAdRewardFulfillment func = (ReportAdRewardFulfillment)GetProcAddress(hDLL, "ReportAdRewardFulfillment");
    if (func) {
        return func(unitId, resourceId, materialId, rewardId);
    }
    return false;
}

//In the UI thread, delete the corresponding container
case WM_DESTROY_ADVERT: {
    const char* json = reinterpret_cast<const char*>(lParam);
    if (json) {
        try
        {
            nlohmann::json json_obj = nlohmann::json::parse(json);
            std::string unitId = json_obj["unitId"];
            if (unitId == SplashAdUnitId)
            {//Delete splash screen ad container
                DestroyWindow(g_hPnlSplashScreen);
                g_hPnlSplashScreen = NULL;
            }
            else if (unitId == InterstitialUnitId)
            {//Delete interstitial ad container
                DestroyWindow(g_hPnlInterstitial);
                g_hPnlInterstitial = NULL;
            }
            else if (unitId == BannerUnitId)
            {//Delete Banner ad container
                DestroyWindow(g_hPnlBanner);
                g_hPnlBanner = NULL;
            }
            else if (unitId == CoupletUnitId)
            {//Delete couplet ad container
                int coupletType = json_obj["coupletType"];
                if (coupletType == 1)//Delete left container
                {
                    BOOL result = DestroyWindow(g_hPnlCoupletLeft);
                    g_hPnlCoupletLeft = NULL;
                }
                else
                {
                    BOOL result = DestroyWindow(g_hPnlCoupletRight);
                    g_hPnlCoupletRight = NULL;
                }
            }
            else if (unitId == RewardedUnitId)
            {//Rewarded
                DestroyWindow(g_hPnlReward);
                g_hPnlReward = NULL;

                int completeStatus = json_obj["completeStatus"]; 
                if (completeStatus == 1)
                {
                    std::string resourceId = json_obj["resourceId"];
                    std::string materialId = json_obj["materialId"];
                    std::string rewardId = json_obj["rewardId"];

                    //Video playback finished, issue reward items 
                    //... 

                    //Report order fulfillment to MG
                    reportAdRewardFulfillment(unitId.c_str(), resourceId.c_str(), materialId.c_str(), rewardId.c_str());
                    AppendLog(L"reportAdRewardFulfillment Async: %hs", rewardId.c_str());
                }
            }
        }
        catch (const std::exception& ex)
        { 
        }
        free((void*)json);
    }
    return 0;
}

Introduction​

Splash Ad​

Exit Ad​

Banner Ad​

Interstitial Ad​

Couplet Ad​

Rewarded​

Feed​

Embedded​

Ad Close Event​