广告接入指南

简介

在接入广告之前，首先需要完成SDK的初始化。

MG Ads 支持【开屏1920*1080】【退屏】【横幅728*90】【插屏1024*768】【对联300*600】【激励视频1024*768】【信息流】【嵌入式】

广告功能，需要开发者创建并管理显示广告的容器，将容器的句柄传递给SDK。

开屏广告

全局变量定义

const char* YourAppId = "692e5d6a207c9dd383ba56f7";
const char* YourSecretKey = "MIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQgiJm0JnjgpDjxEKKzH/7kc3N8r+nvmHko1EPV6My6WG6gCgYIKoZIzj0DAQehRANCAAR2z1Eih/EOFjBMbpgMdvfYjUqFEVaRbnEeYEYZrp4K3pGj1YoY0/dmRRQ58OaHfxKotbFDMwNDBpuHwtxTqGE6";
const char* SplashAdUnitId = "768338453d614f3aad85eea7e3916e7e";           //开屏:1920 x 1080
const char* ExitAdUnitId = "7cdc7614b69c4118933e2067e6e14d01";              //退屏:1920 x 1080
const char* BannerUnitId = "e9b34829a2ad4a959874f9a180278bfe";              //横幅:728 x 90
const char* InterstitialUnitId = "e333abaf22404c4a8d382c1e7ba42076";         //插屏:1024 x 768
const char* CoupletUnitId = "c68cd45e8e374ccd98a704887e5b3582";            //对联:300 x 600
const char* RewardedUnitId = "0f505442fac84f098e81d6f2ca04abe1";            //激励广告:1024x768
const char* FeedUnitId = "6fab0e0912db497cbf886c2c4a9b131c";                   //信息流，由开发者维护广告控件
const char* EmbeddedUnitId = "e065e44302314b888dcb6074fa6efd69";         //嵌入式，由开发者维护广告控件

开屏广告位一般在启动应用之后，在SDK初始化完成事件中实现。

//初始化完成的回调函数
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");

            //退屏广告；Step1.初始化成功之后，加载退屏广告资源
            setupExitAd(hDLL);

            //向UI线程发消息，使其调用开屏广告
            PostMessage(g_hwndMain, WM_SHOW_OPENSCREEN_ADVERT, 0, NULL);
        }
    }
    catch (const std::exception&)
    { 
    } 
}

//UI线程中创建显示广告的容器，调用SDK的广告接口
case WM_SHOW_OPENSCREEN_ADVERT:
{
    CreateSplashScreenAdPanel(g_hwndMain);//创建开屏广告容器
    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.应用类 2.游戏类
         {"adType", 1},//开屏广告
         {"handle", reinterpret_cast<int>(g_hPnlSplashScreen)},
         {"width", clientWidth},//开屏广告，需要传入程序的宽高
         {"height", clientHeight},
         {"parentWidth", clientWidth},
         {"parentHeight", clientHeight}
        };
        std::string jsonStr = json_obj.dump();
        showAd(jsonStr.c_str());
    }
    return 0;
}

//sdk的广告接口
void showAd(const char* json) {
    try
    { 
        // 确保在调用前COM已初始化
        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)
    {
    }
}

退屏广告

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

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

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

//Step1.初始化成功之后，加载退屏广告资源
void setupExitAd(HINSTANCE hdll) {
    if (auto func = (SetupExitAd)GetProcAddress(hdll, "SetupExitAd")) {
        func(ExitAdUnitId); 
        AppendLog(L"Load the resources for MG exit ad");
    }
}

// Step2.在程序关闭时，弹出展示退屏广告
void showExitAdBlocking(HINSTANCE hdll) {
    if (auto func = (ShowExitAdBlocking)GetProcAddress(hdll, "ShowExitAdBlocking")) {
        func();
        AppendLog(L"show fallback screen advert");
    }
}

横幅广告

case ID_BTN_AD3:
{
    CreateBannerAdPanel(hWnd);//创建广告容器 
    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;
} 

插屏广告

case ID_BTN_AD4:
{
    CreateInterstitialAdPannel(hWnd);//创建广告容器 
    nlohmann::json json_obj = {
       {"unitId", InterstitialUnitId},
       {"appType", 1},
       {"adType", 4},//插屏
       {"handle", reinterpret_cast<int>(g_hPnlInterstitial)}
    };
    std::string jsonStr = json_obj.dump();
    showAd(jsonStr.c_str()); 
    break;
} 

对联广告

case ID_BTN_AD5:
{
    CreateCoupletAdPannel(hWnd);//创建广告容器
    nlohmann::json json_obj = {
        {"unitId", CoupletUnitId},
        {"appType", 1},
        {"adType", 5},//对联
        {"handle", reinterpret_cast<int>(g_hPnlCoupletLeft)},
        {"handle2", reinterpret_cast<int>(g_hPnlCoupletRight)}
    };
    std::string jsonStr = json_obj.dump();
    showAd(jsonStr.c_str()); 
    break;
} 

激励视频

case ID_BTN_AD6:
{   
    CreateRewardAdPannel(hWnd);
    nlohmann::json json_obj = {
         {"unitId", RewardedUnitId},
         {"comment", "abc123"},//透传参数，前端需要进行urlEncode；在广告关闭回调事件中会原封不动的返回
         {"appType", 1},
         {"adType", 6},//激励视频
         {"handle", reinterpret_cast<int>(g_hPnlReward)},
         {"width", 1024},
         {"height", 768}
    };
    std::string jsonStr = json_obj.dump();
    showAd(jsonStr.c_str());
    break;
}

信息流

信息流广告需要开发者创建并维护控件，将控件实例传给SDK。

case ID_BTN_AD7:
{ 
    int containerHandle = reinterpret_cast<int>(g_hPnlInformationFlow);
    nlohmann::json json_obj = {
        {"unitId", FeedUnitId},
        {"media", "image"},
        {"appType", 1},
        {"adType", 7},//信息流
        {"width", 400},//信息流，需要传入容器的宽高
        {"height", 50},
        {"handle", containerHandle}
    };
    std::string jsonStr = json_obj.dump();
    showAd(jsonStr.c_str()); 
    break;
}

嵌入式

嵌入式广告需要开发者创建并维护控件，将控件实例传给SDK。

case ID_BTN_AD8:
{ 
    int containerHandle = reinterpret_cast<int>(g_hPnlEmbedded);
    nlohmann::json json_obj = {
        {"unitId", EmbeddedUnitId},
        {"media", "image"},
        {"appType", 1},
        {"adType", 8},//嵌入式
        {"width", 200},//嵌入式，需要传入容器的宽高
        {"height", 200},
        {"handle", containerHandle}
    };
    std::string jsonStr = json_obj.dump();
    showAd(jsonStr.c_str());
    break;
}

广告关闭事件

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

广告关闭事件参数说明

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

//广告关闭时的回调函数
void onAdCloseEvent(char* s) {
    AppendLog(L"onAdCloseEvent: %hs", s);
    //...
    // Destroy Ad pannel 
     
    // 发送到UI线程
    char* jsonCopy = _strdup(s);
    PostMessage(g_hwndMain, WM_DESTROY_ADVERT, 0, reinterpret_cast<LPARAM>(jsonCopy));
}

//激励视频广告，向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;
}

//在UI线程中删除对应的容器
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)
            {//删除开屏广告容器
                DestroyWindow(g_hPnlSplashScreen);
                g_hPnlSplashScreen = NULL;
            }
            else if (unitId == InterstitialUnitId)
            {//删除插屏广告容器
                DestroyWindow(g_hPnlInterstitial);
                g_hPnlInterstitial = NULL;
            }
            else if (unitId == BannerUnitId)
            {//删除Banner广告容器
                DestroyWindow(g_hPnlBanner);
                g_hPnlBanner = NULL;
            }
            else if (unitId == CoupletUnitId)
            {//删除对联广告容器
                int coupletType = json_obj["coupletType"];
                if (coupletType == 1)//删除左侧容器
                {
                    BOOL result = DestroyWindow(g_hPnlCoupletLeft);
                    g_hPnlCoupletLeft = NULL;
                }
                else
                {
                    BOOL result = DestroyWindow(g_hPnlCoupletRight);
                    g_hPnlCoupletRight = NULL;
                }
            }
            else if (unitId == RewardedUnitId)
            {//激励视频
                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"];

                    //视频播放完毕，下发奖励道具 
                    //... 

                    //向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;
}

简介​

开屏广告​

退屏广告​

横幅广告​

插屏广告​

对联广告​

激励视频​

信息流​

嵌入式​

广告关闭事件​

简介