跳到主要内容

CMP与SDK初始化接入指南

简介​

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

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

⚠️ 重要提示2：请确保您已在 MG 广告后台创建的应用通过 MG 产品经理的审核并发布。只有审核发布后的应用，才能使用其应用唯一标识和应用秘钥调用 CMP 接口及 SDK 初始化接口。

接口清单​

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

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

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

接口详细说明​

OpenCmp（CMP 弹窗）​

IAsyncOperation<AsyncProcessResult> OpenCmp(string appKey, string secretKey, PopupCmpSettingOptions options)
参数类型说明
appKeystring应用唯一标识，在 MG 广告后台申请获取
secretKeystring应用密钥，与 appKey 配对使用
optionsPopupCmpSettingOptions弹窗配置选项

PopupCmpSettingOptions 对象说明：

参数类型说明
IgnoreExpiredCheckboolfalse（推荐）：用户首次选择后不再弹出；true：每次启动都弹出（适合测试环境）

返回值：

  • ReturnValue = true：弹窗展示成功

  • ReturnValue = false：弹窗展示失败

  • 当弹窗展示成功且用户做出选择时，Tag 中包含 CmpResult 对象，其中 Payload 为用户选择结果数据

Initialize（SDK 初始化）​

IAsyncOperation<AsyncProcessResult> Initialize(string appKey, string secretKey)
参数类型说明
appKeystring应用唯一标识，与 OpenCmp 使用相同的 AppKey
secretKeystring应用密钥，与 OpenCmp 使用相同的 SecretKey

返回值：

  • ReturnValue = true：初始化成功，可正常使用广告功能

  • ReturnValue = false：初始化失败

初始化失败常见原因：

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

ApplicationManager.UserRegionCmpRequirement​

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

ApplicationManager.UserRegionCmpRequirement

返回值：

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

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

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

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

调用流程​

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

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

接入步骤​

引入命名空间​

using MiracleGamesAd;
using MiracleGamesAd.Models;

在程序启动位置调用​

建议将 CMP 和初始化的代码统一放在 MainPage_Loaded 方法中。

完整示例代码​

private async void MainPage_Loaded(object sender, RoutedEventArgs e)
{
    // ========= 第一步：调用 OpenCmp（核心接口） =========
    PopupCmpSettingOptions popupCmpSettingOptions = new PopupCmpSettingOptions();
    // false（推荐）：用户首次选择后不再弹出，符合 GDPR 规范
    // true：每次启动都弹出，适合测试环境
    popupCmpSettingOptions.IgnoreExpiredCheck = false;

    var cmpResult = await ApplicationManager.OpenCmp("YOUR_APP_KEY", "YOUR_Secret_Key", popupCmpSettingOptions);
    
    if (cmpResult.ReturnValue)
    {
        // CMP 窗口展示成功
        if (cmpResult.Tag is CmpResult cmpData)
        {
            if (cmpData.Success)
            {
                // 用户已做出选择，可获取选择结果（如需使用）
                string userChoiceData = cmpData.Payload;
            }
            // else: 用户未做出选择，继续执行后续流程即可
        }
    }
    else
    {
        // CMP 窗口展示失败，可记录日志，继续执行初始化
    }

    // ========= 可选：获取地区 CMP 要求（附加接口，特定场景使用） =========
    // bool isRequired = ApplicationManager.UserRegionCmpRequirement;

    // ========= 第二步：调用 Initialize（核心接口） =========
    var initResult = await ApplicationManager.Initialize("YOUR_APP_KEY", "YOUR_Secret_Key");
    
    if (initResult.ReturnValue)
    {
        // 初始化成功，可正常使用广告功能
    }
    else
    {
        // 初始化失败，根据错误信息排查
        // 常见原因：网络故障、VPN冲突、AppKey/Secret错误、服务器异常
    }
}

常见问题（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 次。

Q5：OpenCmp 和 Initialize 的 AppKey/SecretKey 是否相同？

A：是的，两个接口使用相同的 AppKey 和 SecretKey。

Q6：UserRegionCmpRequirement 什么时候用？

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