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 Notice: 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.

Interface List

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

No.	Interface	Description
1	`ApplicationManager.OpenCmp()`	Displays the CMP consent popup and waits for the user’s selection
2	`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

IAsyncOperation<AsyncProcessResult> OpenCmp(string appKey, string secretKey, PopupCmpSettingOptions options)

Parameter	Type	Description
`appKey`	string	Unique application identifier obtained from the MG Ads developer console
`secretKey`	string	Application secret key paired with the appKey
`options`	PopupCmpSettingOptions	Popup configuration options

PopupCmpSettingOptions Object Description:

Parameter	Type	Description
`IgnoreExpiredCheck`	bool	`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 Tag contains a CmpResult object, where Payload contains the user’s consent result data

Initialize (SDK Initialization)

IAsyncOperation<AsyncProcessResult> Initialize(string appKey, string secretKey)

Parameter	Type	Description
`appKey`	string	Unique application identifier, using the same AppKey as OpenCmp
`secretKey`	string	Application secret key, using the same SecretKey as OpenCmp

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 AppKey/Secret	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 OpenCmp() → Wait for User Selection → Call Initialize() → Use Advertising Features

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

⚠️ Mandatory Requirement2: Please ensure that the app you created in the MG Ad Console has been reviewed and published by the MG product manager. Only after the app is reviewed and published can its App Unique Identifier and App Secret be used to call the OpenCmp() and the Initialize() .

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_Loaded method.

Complete Example Code

private async void MainPage_Loaded(object sender, RoutedEventArgs e)
{
    // ========= Step 1: Call OpenCmp (Core Interface) =========
    PopupCmpSettingOptions popupCmpSettingOptions = new PopupCmpSettingOptions();

    // 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
    popupCmpSettingOptions.IgnoreExpiredCheck = false;

    var cmpResult = await ApplicationManager.OpenCmp("YOUR_APP_KEY", "YOUR_Secret_Key", popupCmpSettingOptions);

    if (cmpResult.ReturnValue)
    {
        // CMP popup displayed successfully
        if (cmpResult.Tag is CmpResult cmpData)
        {
            if (cmpData.Success)
            {
                // User has made a selection, result data can be retrieved if needed
                string userChoiceData = cmpData.Payload;
            }
            // else: User did not make a selection, continue with the following process
        }
    }
    else
    {
        // Failed to display CMP popup, log the error if needed and continue initialization
    }

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

    // ========= Step 2: Call Initialize (Core Interface) =========
    var initResult = await ApplicationManager.Initialize("YOUR_APP_KEY", "YOUR_Secret_Key");

    if (initResult.ReturnValue)
    {
        // Initialization successful, advertising features are available
    }
    else
    {
        // Initialization failed, troubleshoot based on the error message
        // Common reasons: network failure, VPN conflict, invalid AppKey/Secret, server 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?

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.

Q5: Are the AppKey and SecretKey the same for OpenCmp and Initialize?

A: Yes, both interfaces use the same AppKey and SecretKey.

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. eGames/adwin-sdk-win32-example/blob/main/doc/contact.zh-CN.md).

Introduction​

Interface List​

Detailed Interface Description​

OpenCmp (CMP Popup)​

Initialize (SDK Initialization)​

ApplicationManager.UserRegionCmpRequirement​

Call Flow​

Integration Steps​

Import Namespace​

Call During Application Startup​

Complete Example Code​

Frequently Asked Questions (FAQ)​