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	ApplicationManager.SetAppId()	Configure App Parameters
2	ApplicationManager.OpenCmp()	Displays the CMP consent popup and waits for the user’s selection
3	ApplicationManager.Initialize()	Initializes the SDK. Advertising features can only be used after initialization is completed

📌 Additional Interface: ApplicationManager.UserRegionCmpRequirement 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(string appId, string 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)

Task<AsyncProcessResult> OpenCmp(CmpParameters options)

Parameter	Type	Description
options	CmpParameters	Popup configuration options

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:

• ReturnValue = true: Popup displayed successfully

• ReturnValue = false: Failed to display the popup

• When the popup is displayed successfully and the user makes a selection, the Data is an Object containing the user's consent result data.

Initialize (SDK Initialization)

Task<AsyncProcessResult> Initialize()

Return Value:

• ReturnValue = true: Initialization successful, advertising features are available

• ReturnValue = false: Initialization failed

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.

ApplicationManager.UserRegionCmpRequirement

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

using MiracleGamesAd;
using MiracleGamesAd.Models;

Call During Application Startup

It is recommended to place the CMP and initialization code inside the MainPage_Load method.

Complete Example Code

private async void MainPage_Loaded(object sender, RoutedEventArgs e)
{
    try
    {
        // ========= Step 1: Call SetAppId (set parameters) =========
        ApplicationManager.SetAppId(YourAppId, YourSecretKey);

        // ========= Step 2: Call OpenCmp (Core Interface) =========
        CmpParameters cmpOptions = new CmpParameters();
        // false (Recommended): Popup only appears once after the user's first selection, compliant with GDPR
        // true: Popup appears every time the app starts, suitable for testing environments
        cmpOptions.IgnoreExpiredCheck = false;
        var cmpresult = await ApplicationManager.OpenCmp(cmpOptions);
        if (cmpresult.ReturnValue)
        {
            // CMP popup displayed successfully
            ShowMessage($"CMP is required in this region, CMP result={cmpresult.Data?.ToString()}");
        }

        // ========= Optional: Get Region CMP Requirement (Additional Interface, Used in Specific Scenarios) =========
        //bool isUserRegionCmpRequired = ApplicationManager.UserRegionCmpRequirement;

        // ========= Step 3: Call Initialize (Core Interface) =========
        var result = await ApplicationManager.Initialize();
        if (result.ReturnValue)
        {
            // Initialization successful, advertising features are available
             
            AdvertManager.SetupExitAd(ExitAdUnitId); 

            //...

            AdvertManager.ShowAd(this, FullScreenAdUnitId, AdType.FullScreen); 
        }
        else
        {
            // Initialization failed, troubleshoot based on the error message
            // Common reasons: network failure, VPN conflict, invalid AppId/SecretKey, server exception
            ShowMessage("Initialization failed");
        }
    }
    catch (Exception)
    {
    }
}

---

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.