跳到主要内容

CMP与SDK初始化接入指南

简介​

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

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

⚠️ 重要提示2：请确保您已在 MG 广告后台创建应用，才能使用其应用唯一标识和应用秘钥调用 CMP 接口及 SDK 初始化接口。应用未通过审核前，每日 API 调用限额为 100 次，仅适用于测试阶段。正式上线前，请联系 MG 产品经理完成审核发布，以免调用限额影响线上业务。

接口清单​

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

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

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

接口详细说明​

SetAppId（设置应用参数）​

void SetAppId(string appId, string secretKey)
参数类型必要性说明
appIdstring必填应用唯一标识，在 MG 广告后台申请获取
secretKeystring必填应用密钥，与 appId 配对使用

返回值：

  • 无返回值

OpenCmp（CMP 弹窗）​

Task<AsyncProcessResult> OpenCmp(CmpParameters options)
参数类型说明
optionsCmpParameters弹窗配置选项

CmpParameters 对象说明：

参数类型必要性说明
Widthint可选弹窗宽，默认值900
Heightint可选弹窗高，默认值500
IgnoreExpiredCheckbool可选false（默认）：用户首次选择后不再弹出；true：每次调用都弹出（适合测试或特殊场景）

返回值：

  • ReturnValue = true：弹窗展示成功

  • ReturnValue = false：弹窗展示失败

  • 当弹窗展示成功且用户做出选择时，Data 是 Object 对象，其为用户选择结果数据

Initialize（SDK 初始化）​

Task<AsyncProcessResult> Initialize()

返回值：

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

  • ReturnValue = false：初始化失败

初始化失败常见原因：

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

ApplicationManager.UserRegionCmpRequirement​

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

ApplicationManager.UserRegionCmpRequirement

返回值：

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

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

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

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

调用流程​

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

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

接入步骤​

引入命名空间​

using MiracleGamesAd;
using MiracleGamesAd.Models;

在程序启动位置调用​

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

完整示例代码​

private async void MainPage_Load(object sender, EventArgs e)
{
    try
    {
        // ========= 第一步：设置参数 =========
        ApplicationManager.SetAppId(YourAppId, YourSecretKey);

        // ========= 第二步：调用 OpenCmp（核心接口） =========
        CmpParameters cmpOptions = new CmpParameters();
        // false（推荐）：用户首次选择后不再弹出，符合 GDPR 规范
        // true：每次启动都弹出，适合测试环境
        cmpOptions.IgnoreExpiredCheck = false;
        var cmpresult = await ApplicationManager.OpenCmp(cmpOptions);
        if (cmpresult.ReturnValue)
        {
            // CMP 窗口展示成功 
            ShowMessage($"CMP is required in this region, CMP result={cmpresult.Data?.ToString()}");
        }

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

        // ========= 第三步：调用 Initialize（核心接口） =========
        var result = await ApplicationManager.Initialize();
        if (result.ReturnValue)
        {
            // 初始化成功，可正常使用广告功能
             
            AdvertManager.SetupExitAd(ExitAdUnitId);//退屏广告

            //...

            AdvertManager.ShowAd(this, FullScreenAdUnitId, AdType.FullScreen);//全屏广告
        }
        else
        {
            // 初始化失败，根据错误信息排查
            // 常见原因：网络故障、VPN冲突、AppId/SecretKey错误、服务器异常
            ShowMessage("Initialization failed");
        }
    }
    catch (Exception)
    {
    }
}

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

Q6：UserRegionCmpRequirement 什么时候用？

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