CMP and SDK Initialization Integration Guide

Introduction

This document is intended for developers integrating the MG Ads SDK and explains how to properly complete the CMP (User Consent Request) and SDK Initialization processes.

⚠️ Important Notice1: Before calling any advertising features, you must complete both the CMP interface call and the SDK initialization interface call in sequence. Neither step can be omitted.

⚠️ Important Notice2: Please ensure that you have created an app in the MG Ads backend before using its unique appId and secretKey to call the CMP API and the SDK initialization API. Until the app passes review, the daily API call limit is 100 calls, and this limit applies only during the testing phase. Before going live, please contact your MG product manager to complete the review and release process to avoid any impact on live operations due to the call limit.

---

Interface List

The MG Ads SDK provides 3 interfaces, which must be called in order:

No.	Interface	Description
1	SetAppId()	Configure App Parameters
2	OpenCmp()	Displays the CMP consent popup and waits for the user’s selection
3	Initialize()	Initializes the SDK. Advertising features can only be used after initialization is completed

📌 Additional Interface: GetUserRegionCmpRequirement() is an optional interface used to determine whether the current user's region is required to comply with CMP. It is only used in specific scenarios (such as region-based logic handling).

---

Detailed Interface Description

SetAppId（Configure App Parameters）

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

Parameter	Type	Required	Description
appId	string	Required	Unique application identifier obtained from the MG Ads developer console
secretKey	string	Required	Application secret key paired with the appId

Return Value:

• No return value

OpenCmp (CMP Popup)

void OpenCmp(const char* options)

Parameter	Type	Description
options	string	Popup configuration options,CmpParameters object in JSON format

CmpParameters Object Description:

Parameter	Type	Required	Description
width	int	Optional	The width of the CMP window; the default value is 900
height	int	Optional	The height of the CMP window; the default value is 500
ignoreExpiredCheck	bool	Optional	false (Recommended): The popup will not appear again after the user makes a selection for the first time; true: The popup appears every time the app starts (recommended for testing environments)

Return Value:

• No return value. The result of the call is returned via an asynchronous callback event.

Initialize (SDK Initialization)

void Initialize()

Return Value:

• No return value. The result of the call is returned via an asynchronous callback event.

Common Reasons for Initialization Failure:

Error Type	Description	Solution
Network Failure	Device has no valid internet connection	Check network settings and ensure the device is connected to the internet
VPN Conflict	UWP applications do not support VPN environments	Disable VPN software and try again
Invalid appId/secretKey	Incorrect application credentials	Verify application settings in the developer console
Server Exception	Backend service response error	Check the error message in the return value and contact technical support

ApplicationManager.UserRegionCmpRequirement

This interface is optional and is used to obtain whether the current user's region requires compliance with CMP.

bool GetUserRegionCmpRequirement()

Return value：

• true：The user's region requires CMP (need to display compliance pop-up)

• false：The user's region does not require CMP (no pop-up)

Prerequisite for calling：Can only be called during app runtime, i.e., OpenCmp() must be executed first after app startup.

Usage scenario：Use when differential processing based on region is needed during app runtime. For example: show the pop-up entry only to users in regions that require CMP.

---

Call Flow

App Launch → Call SetAppId()→ Call OpenCmp() → Wait for User Selection → Call Initialize() → Use Advertising Features

⚠️ Mandatory Requirement1: Initialize() must be called after OpenCmp() has completed execution.

---

Integration Steps

Import Namespace

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

Call During Application Startup

It is recommended that the CMP and initialization code be consolidated within the WM_CREATE message in the WndProc method.

Complete Example Code

LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
{
    switch (message)
    {
    case WM_CREATE:
    {
        CreateControls(hWnd);
        InitMgAdSdk(hWnd); // SDK initialization
        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) {
        // Register CMP callback event
        if (auto func = (CmpClosedEvent)GetProcAddress(hDLL, "CmpClosedEvent"))
            func(onCmpClosedEvent);

        // Register initialization callback event
        if (auto func = (InitCompleteEvent)GetProcAddress(hDLL, "InitCompleteEvent"))
            func(onInitCompleteEvent);
        // Register ad close event
        if (auto func = (AdCloseEvent)GetProcAddress(hDLL, "AdCloseEvent"))
            func(onAdCloseEvent);
        // Register ad preload event, use as needed
        if (auto func = (AdPreloadEvent)GetProcAddress(hDLL, "AdPreloadEvent"))
            func(onAdPreloadEvent);
        // Register ad preload show event, use as needed
        if (auto func = (AdShowPreloadEvent)GetProcAddress(hDLL, "AdShowPreloadEvent"))
            func(onAdShowPreloadEvent);
        
        // 1. Set application parameters
        setAppId(hDLL, YourAppId, YourSecretKey);

        // 2. Call CMP
        nlohmann::json json_obj = {
        {"ignoreExpiredCheck",false},
        {"width", 900}, // Optional, default 900
        {"height", 500} // Optional, default 900 (note: original says 900, kept as is)
        };
        std::string jsonStr = json_obj.dump();
        openCmp(hDLL, jsonStr.c_str());

        // 3. Call initialization in CMP callback event
    }
}

// Call initialization in CMP callback event
void onCmpClosedEvent(char* s) {
    try
    { 
        Initialize func = (Initialize)GetProcAddress(hdll, "Initialize");
        func();
    }
    catch (...)
    {
    }
}

// Initialization callback event
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 ad; Step 1. After successful initialization, load exit ad resources
            setupExitAd(hDLL);

            // Send message to UI thread to call splash screen ad
            PostMessage(g_hwndMain, WM_SHOW_OPENSCREEN_ADVERT, 0, NULL);
        }
    }
    catch (...)
    { 
    } 
}

---

Frequently Asked Questions (FAQ)

Q1: Why must OpenCmp be called before Initialize?

A: The SDK needs to obtain the user’s consent status during initialization to determine whether advertising requests are allowed. Calling OpenCmp first ensures that the SDK has the necessary consent information during initialization.

Q2: Will OpenCmp block the application?

A: It will not freeze the application, but the CMP popup will wait for the user’s selection. After the user makes a selection, the popup closes automatically and the code continues executing Initialize.

Q3: How should IgnoreExpiredCheck be configured?

A:

• Set to false: The CMP interface only appears once after the App is first installed and launched (recommended for normal startup scenarios).

• Set to true: The CMP interface appears every time it is called, suitable for scenarios during App runtime. For example: after the game starts, the user manually opens the CMP popup again through a “Settings” or “User Center” button. It is also useful for testing and debugging.

Q4: Can Initialize be retried after failure?

A: Yes. It is recommended to retry up to 3 times.

Q6: When should UserRegionCmpRequirement be used?

A: This is an optional interface used only in specific scenarios where region-based logic handling is required. In most cases, you can directly call OpenCmp, and the SDK will automatically determine whether the popup is needed.