SDK初始化
简介
本文档面向接入 MG Ads SDK 的开发者，介绍如何正确完成 CMP（用户意见征求） 和 SDK 初始化 的调用。
⚠️ 重要提示1：在调用广告功能之前，必须依次完成 CMP 接口和 SDK 初始化接口的调用。两者缺一不可。
⚠️ 重要提示2：请确保您已在 MG 广告后台创建的应用通过 MG 产品经理的审核并发布。只有审核发布后的应用，才能使用其应用唯一标识和应用秘钥调用 CMP 接口及 SDK 初始化接口。
接口清单
MG Ads SDK 提供 2 个接口，必须按顺序调用：
| 序号 | 接口 | 说明 |
|---|---|---|
| 1 | MiracleGamesAd::ApplicationManager::OpenCmp | 弹出 CMP 征得用户同意弹窗，等待用户选择 |
| 2 | MiracleGamesAd::ApplicationManager::Initialize | 初始化 SDK，完成后方可调用广告功能 |
📌 附加接口：
MiracleGamesAd::ApplicationManager::UserRegionCmpRequirement是一个可选接口，用于获取当前用户所在地区是否需要遵守 CMP，仅在特定场景下使用（如需要根据地区做差异化处理时）。
接口详细说明
OpenCmp（CMP 弹窗）
IAsyncOperation<AsyncProcessResult> OpenCmp(string appKey, string secretKey, PopupCmpSettingOptions options)
| 参数 | 类型 | 说明 |
|---|---|---|
appKey | string | 应用唯一标识，在 MG 广告后台申请获取 |
secretKey | string | 应用密钥，与 appKey 配对使用 |
options | PopupCmpSettingOptions | 弹窗配置选项 |
PopupCmpSettingOptions 对象说明：
| 参数 | 类型 | 说明 |
|---|---|---|
IgnoreExpiredCheck | bool | false（推荐）：用户首次选择后不再弹出；true：每次启动都弹出（适合测试环境） |
返回值：
-
ReturnValue = true：弹窗展示成功 -
ReturnValue = false：弹窗展示失败 -
当弹窗展示成功且用户做出选择时，
Tag中包含CmpResult对象，其中Payload为用户选择结果数据
Initialize（SDK 初始化）
IAsyncOperation<AsyncProcessResult> Initialize(string appKey, string secretKey)
| 参数 | 类型 | 说明 |
|---|---|---|
appKey | string | 应用唯一标识，与 OpenCmp 使用相同的 AppKey |
secretKey | string | 应用密钥，与 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 namespace MiracleGamesAd;
using namespace MiracleGamesAd::Models;
在程序启动位置调用
建议将 CMP 和初始化的代码统一放在 MainPage 方法中。
完整示例代码
MainPage :: MainPage（）
{
InitializeComponent（）;
//...
// ========= 第一步：调用 OpenCmp（核心接口） =========
auto opt = ref new MiracleGamesAd::Models::PopupCmpSettingOptions();
// false（推荐）：用户首次选择后不再弹出，符合 GDPR 规范
// true：每次启动都弹出，适合测试环境
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窗口展示成功
{
auto completeState = dynamic_cast<MiracleGamesAd::Models::CmpResult^>(result->Tag);
if (completeState != nullptr)
{
if (completeState->Success)
{
auto data = completeState->Payload;// 用户已做出选择，可获取选择结果（如需使用）
}
else//用户未作出选择
{
}
}
}
else
{
// CMP 窗口展示失败，可记录日志，继续执行初始化
}
// ========= 可选：获取地区 CMP 要求（附加接口，特定场景使用） =========
// bool isRequired = ApplicationManager::UserRegionCmpRequirement;
// ========= 第二步：调用 Initialize（核心接口） =========
concurrency::create_task(MiracleGamesAd::ApplicationManager::Initialize("YOUR_APP_KEY", "YOUR_Secret_Key")).then([](MiracleGamesAd::Services::Core::Common::AsyncProcessResult^ result)
{
if (result->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 内部会自动判断是否需要弹窗。