SDK Initialization

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	`MiracleGamesAd::ApplicationManager::OpenCmp`	Displays the CMP consent popup and waits for the user’s selection
2	`MiracleGamesAd::ApplicationManager::Initialize`	Initializes the SDK. Advertising features can only be used after initialization is completed

📌 Additional Interface: MiracleGamesAd::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 namespace MiracleGamesAd;
using namespace MiracleGamesAd::Models;

Call During Application Startup

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

Complete Example Code

MainPage::MainPage()
{
    InitializeComponent();   
		//...

    // ========= Step 1: Call OpenCmp (Core Interface) =========
    auto opt = ref new MiracleGamesAd::Models::PopupCmpSettingOptions();
    // false (recommended): Popup will not appear again after user's first choice, compliant with GDPR
    // true: Popup appears on every launch, suitable for test environment
    opt->IgnoreExpiredCheck = false; 

    auto initTask = Concurrency::create_task(MiracleGamesAd::ApplicationManager::OpenCmp("YOUR_APP_KEY", "YOUR_Secret_Key", opt));
    initTask.then([](MiracleGamesAd::Services::Core::Common::AsyncProcessResult^ result)
      {
        if (result->ReturnValue) // CMP window displayed successfully
        {
          auto completeState = dynamic_cast<MiracleGamesAd::Models::CmpResult^>(result->Tag);
          if (completeState != nullptr)
          {
            if (completeState->Success)
            {
              auto data = completeState->Payload; // User has made a choice, can retrieve the result (if needed)
            }
            else // User did not make a choice
            {

            }
          }
        }
        else
        {
           // CMP window failed to display, can log error and continue initialization
        }
        // ========= Optional: Get regional CMP requirement (Additional interface, for specific scenarios) =========
        // bool isRequired = ApplicationManager::UserRegionCmpRequirement;

        // ========= Step 2: Call Initialize (Core Interface) =========
        concurrency::create_task(MiracleGamesAd::ApplicationManager::Initialize("YOUR_APP_KEY", "YOUR_Secret_Key")).then([](MiracleGamesAd::Services::Core::Common::AsyncProcessResult^ result)
          {
            if (result->ReturnValue) // Initialization callback interface, checks if initialization is complete.
            {
              // Initialization successful, ad features can be used normally
            }
            else
            {
                // Initialization failed, troubleshoot based on error info
                // Common causes: network failure, VPN conflict, incorrect AppKey/Secret, server error
            }
          });
      });
}

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)​