SDK初始化

简介

本文档面向接入 MG Ads SDK 的开发者，介绍如何正确完成 CMP（用户意见征求） 和 SDK 初始化 的调用。

⚠️ 重要提示1：在调用广告功能之前，必须依次完成 CMP 接口和 SDK 初始化接口的调用。两者缺一不可。

⚠️ 重要提示2：请确保您已在 MG 广告后台创建应用，才能使用其应用唯一标识和应用秘钥调用 CMP 接口及 SDK 初始化接口。应用未通过审核前，每日 API 调用限额为 100 次，仅适用于测试阶段。正式上线前，请联系 MG 产品经理完成审核发布，以免调用限额影响线上业务。

---

接口清单

MG Ads SDK 提供 3 个接口，必须按顺序调用：

序号	接口	说明
1	SetAppId()	设置应用参数
2	OpenCmp()	弹出 CMP 征得用户同意弹窗，等待用户选择
3	Initialize()	初始化 SDK，完成后方可调用广告功能

📌 附加接口：GetUserRegionCmpRequirement() 是一个可选接口，用于获取当前用户所在地区是否需要遵守 CMP，仅在特定场景下使用（如需要根据地区做差异化处理时）。

---

接口详细说明

SetAppId（设置应用参数）

void SetAppId(const char* appId, const char* secretKey)

参数	类型	必要性	说明
appId	string	必填	应用唯一标识，在 MG 广告后台申请获取
secretKey	string	必填	应用密钥，与 appId 配对使用

返回值：

• 无返回值

OpenCmp（CMP 弹窗）

void OpenCmp(const char* options)

参数	类型	说明
options	string	弹窗配置选项，Json格式的CmpParameters对象

CmpParameters 对象说明：

参数	类型	必要性	说明
width	int	可选	弹窗宽，默认值900
height	int	可选	弹窗高，默认值500
ignoreExpiredCheck	bool	可选	false（默认）：用户首次选择后不再弹出；true：每次调用都弹出（适合测试或特殊场景）

返回值：

• 无返回值。调用结果通过异步回调事件返回。

Initialize（SDK 初始化）

void Initialize()

返回值：

• 无返回值。调用结果通过异步回调事件返回。

初始化失败常见原因：

错误类型	说明	解决方法
网络故障	设备无有效网络连接	检查网络设置，确保设备已联网
VPN 冲突	UWP 应用不支持 VPN 环境	关闭本机 VPN 软件后重试
appId/secretKey 错误	应用凭证不正确	登录开发者后台核对应用配置
服务器异常	后台服务响应异常	检查返回值中的错误信息，联系技术支持

GetUserRegionCmpRequirement()

该接口是一个可选接口，用于获取当前用户所在地区是否需要遵守 CMP。

bool GetUserRegionCmpRequirement()

返回值：

• true：用户所在区域需要 CMP（需展示合规弹窗）

• false：用户所在区域无需 CMP（不展示弹窗）

调用前提：仅可在 App 运行过程中调用，即 App启动后必须先执行 OpenCmp()。

使用场景：在 App 运行中，需要根据地区做差异化处理时使用。例如：仅对需要 CMP 地区的用户展示弹窗入口。

---

调用流程

应用启动 → 调用 SetAppId() → 调用 OpenCmp() → 等待用户选择 → 调用 Initialize() → 使用广告功能

⚠️ 强制要求：Initialize() 必须在 OpenCmp() 执行完成之后调用。

---

接入步骤

引入SDK

hDLL = LoadLibrary(L"MgAdSDKCSharpDLL.dll");

在程序启动位置调用

建议将 CMP 和初始化的代码统一放在 WndProc 方法 的 WM_CREATE 消息中。

完整示例代码

LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
{
    switch (message)
    {
    case WM_CREATE:
    {
        CreateControls(hWnd);
        InitMgAdSdk(hWnd);//SDK initialize
        break;
    }
    case WM_DESTROY:
        PostQuitMessage(0);
        break;
    default:
        return DefWindowProc(hWnd, message, wParam, lParam);
    }
    return 0;
}

void InitMgAdSdk(HWND hWnd) {
    if (hDLL) return;

    hDLL = LoadLibrary(L"MgAdSDKCSharpDLL.dll");
    if (hDLL) {
        // 注册CMP回调事件
        if (auto func = (CmpClosedEvent)GetProcAddress(hDLL, "CmpClosedEvent"))
            func(onCmpClosedEvent);

        // 注册初始化回调事件
        if (auto func = (InitCompleteEvent)GetProcAddress(hDLL, "InitCompleteEvent"))
            func(onInitCompleteEvent);
        // 注册广告关闭事件
        if (auto func = (AdCloseEvent)GetProcAddress(hDLL, "AdCloseEvent"))
            func(onAdCloseEvent);
        // 注册广告预加载事件，按需使用
        if (auto func = (AdPreloadEvent)GetProcAddress(hDLL, "AdPreloadEvent")) //Callback function for ad preload event
            func(onAdPreloadEvent);
        // 注册广告预加载展示事件，按需使用
        if (auto func = (AdShowPreloadEvent)GetProcAddress(hDLL, "AdShowPreloadEvent")) //Callback function for show ad preload event
            func(onAdShowPreloadEvent);
        
        //1.设置应用参数
        setAppId(hDLL, YourAppId, YourSecretKey);

        //2.调用CMP
        nlohmann::json json_obj = {
        {"ignoreExpiredCheck",false},
        {"width", 900},//可空，默认值 900
        {"height", 500}//可空，默认值 900
        };
        std::string jsonStr = json_obj.dump();
        openCmp(hDLL, jsonStr.c_str());

        //3.在CMP回调事件中调用初始化
    }
}

//在CMP回调事件中调用初始化
void onCmpClosedEvent(char* s) {
    try
    { 
        Initialize func = (Initialize)GetProcAddress(hdll, "Initialize");
        func();
    }
    catch (...)
    {
    }
}

//初始化回调事件
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 (...)
    { 
    } 
}

---

常见问题（FAQ）

Q1：为什么必须先调用 OpenCmp 再调用 Initialize？

A：SDK 初始化时需要获取用户的同意状态，以确定是否可以请求广告。先调用 OpenCmp 可以确保 SDK 初始化时已有用户同意信息。

Q2：OpenCmp 会卡住应用吗？

A：不会卡死应用，但 CMP 窗口会等待用户选择。用户选择后窗口自动关闭，代码继续执行到 Initialize。

Q3：ignoreExpiredCheck 应该怎么设置？

A：

• 设为 false：仅在 App 首次安装后启动时弹出一次 CMP 界面（适用于常规启动场景）。

• 设为 true：每次调用均可弹出 CMP 界面，适用于 App 运行中的场景。例如：游戏运行后，用户在“设置”或“用户中心”点击按钮，主动再次调起 CMP 弹窗。也便于测试调试。

Q4：Initialize 失败可以重试吗

A：可以。建议重试最多 3 次。

Q6：GetUserRegionCmpRequirement() 什么时候用？

A：这是一个可选接口，仅在需要根据地区做差异化处理的特定场景下使用。一般情况下无需调用，直接调用 OpenCmp 即可，SDK 内部会自动判断是否需要弹窗。