间隙广告

项目
03/18/2023

警告

自 2020 年 6 月 1 日起，适用于 Windows UWP 应用的 Microsoft 广告盈利平台将关闭。了解详细信息

本演练演示如何在通用 Windows 平台 (UWP) 应用和游戏中包含间隙广告，以便Windows 10和Windows 11。有关演示如何使用 C# 和 C++ 向 JavaScript/HTML 应用和 XAML 应用添加间隙广告的完整示例项目，请参阅 GitHub 上的广告示例。

什么是间隙广告？

与局限于应用或游戏中的部分 UI 的标准横幅广告不同的是，间隙广告是在整个屏幕上显示。游戏中经常会使用两种基本形式。

通过 Paywall 广告，用户必须在某段固定间隔时间后观看广告。例如在转换游戏关卡之间：
通过基于奖励的广告，用户显式寻找某些好处（例如完成关卡的提示或额外时间），并通过应用的用户界面来初始化广告。

我们提供两种可在应用和游戏中使用的间隙广告：间隙视频广告和间隙横幅广告。

注意

间隙广告的 API 不会处理任何用户界面，播放视频时除外。在考虑如何在应用中集成间隙广告时，可就有关处理方法、避免内容的指南参考间隙最佳做法。

先决条件

使用 Visual Studio 2015 或更高版本的 Visual Studio 安装 Microsoft 广告 SDK。有关安装说明，请参阅此文章。

在应用中集成间隙广告

若要在应用中显示间隙广告，请遵循针对项目类型的说明：

XAML/.NET
HTML/JavaScript
C++（DirectX 互操作）

XAML/.NET

本部分提供 C# 示例，但 Visual Basic 和 C++ 也受 XAML/.NET 项目支持。有关完整的 C# 代码示例，请参阅 C# 中的间隙广告示例代码。

在 Visual Studio 中打开项目。

注意

如果你使用现有项目，请打开项目中的 Package.appxmanifest 文件并确保已选择 Internet（客户端）功能。应用需要使用此功能接收测试广告和实时广告。
如果你的项目面向任何 CPU，请更新你的项目以使用特定于体系结构的生成输出（例如，x86）。如果你的项目面向任何 CPU，你将无法在以下步骤中成功添加对 Microsoft Advertising 库的引用。有关详细信息，请参阅项目中由面向任何 CPU 引起的引用错误。
在你的项目中添加对 Microsoft 广告 SDK 的引用：
1. 在解决方案资源管理器窗口中，右键单击引用，然后选择添加引用...
2. 在引用管理器中，展开通用 Windows、单击扩展，然后选中适用于 XAML 的 Microsoft 广告 SDK（版本 10.0）旁边的复选框。
3. 在引用管理器中，单击“确定”。
在应用的相应代码文件中（例如，在 MainPage.xaml.cs 或部分其他页面的代码文件中）添加以下命名空间引用。
```
using Microsoft.Advertising.WinRT.UI;
```
在应用 (的适当位置（例如，在 MainPage 或其他页面) ）中，声明一个 InterstitialAd 对象和几个表示间隙广告的应用程序 ID 和广告单元 ID 的字符串字段。下面的代码示例将 myAppId 和 myAdUnitId 字段分配给间隙广告的测试值。

注意

每个 InterstitialAd 都有一个对应的广告单元，我们的服务使用该广告单元来为控件提供广告，每个广告单元都包含单元 ID 和应用程序 ID。在这些步骤中，你将为控件分配测试广告单元 ID 和应用程序 ID 值。这些测试值只能在应用的测试版本中使用。在将应用发布到 Microsoft Store 之前，必须在合作伙伴中心将这些测试值替换为实时值。
```
InterstitialAd myInterstitialAd = null;
string myAppId = "d25517cb-12d4-4699-8bdc-52040c712cab";
string myAdUnitId = "test";
```

在启动时运行的代码中（例如，在页面的构造函数中）实例化 InterstitialAd 对象，并安装对象事件的事件处理程序。

myInterstitialAd = new InterstitialAd();
myInterstitialAd.AdReady += MyInterstitialAd_AdReady;
myInterstitialAd.ErrorOccurred += MyInterstitialAd_ErrorOccurred;
myInterstitialAd.Completed += MyInterstitialAd_Completed;
myInterstitialAd.Cancelled += MyInterstitialAd_Cancelled;

如果你需要显示间隙视频广告：在需要广告之前大约 30-60 秒，请使用 RequestAd 方法预取广告。这样就允许在应该显示广告之前有足够的时间请求和准备广告。请务必将广告类型指定为 AdType.Video。
```
myInterstitialAd.RequestAd(AdType.Video, myAppId, myAdUnitId);
```
如果你需要显示间隙横幅广告：在需要广告之前大约 5-8 秒，请使用 RequestAd 方法预取广告。这样就允许在应该显示广告之前有足够的时间请求和准备广告。请务必将广告类型指定为 AdType.Video。
```
myInterstitialAd.RequestAd(AdType.Display, myAppId, myAdUnitId);
```
此时在你想要显示间隙视频或间隙横幅广告的代码中，确认是否已准备好显示 InterstitialAd，然后使用 Show 方法显示它。
```
if (InterstitialAdState.Ready == myInterstitialAd.State)
{
    myInterstitialAd.Show();
}
```

定义 InterstitialAd 对象的事件处理程序。

void MyInterstitialAd_AdReady(object sender, object e)
{
    // Your code goes here.
}

void MyInterstitialAd_ErrorOccurred(object sender, AdErrorEventArgs e)
{
    // Your code goes here.
}

void MyInterstitialAd_Completed(object sender, object e)
{
    // Your code goes here.
}

void MyInterstitialAd_Cancelled(object sender, object e)
{
    // Your code goes here.
}

生成并测试你的应用，以确认它会显示测试广告。

HTML/JavaScript

以下说明假设你已在 Visual Studio 中为 JavaScript 创建了通用 Windows 项目，并且面向特定的 CPU。有关完整的代码示例，请参阅 JavaScript 中的间隙广告示例代码。

在 Visual Studio 中打开项目。
如果你的项目面向任何 CPU，请更新你的项目以使用特定于体系结构的生成输出（例如，x86）。如果你的项目面向任何 CPU，你将无法在以下步骤中成功添加对 Microsoft Advertising 库的引用。有关详细信息，请参阅项目中由面向任何 CPU 引起的引用错误。
在你的项目中添加对 Microsoft 广告 SDK 的引用：
1. 在解决方案资源管理器窗口中，右键单击引用，然后选择添加引用...
2. 在引用管理器中，展开通用 Windows、单击扩展，然后选中适用于 JavaScript 的 Microsoft 广告 SDK（版本 10.0）旁边的复选框。
3. 在引用管理器中，单击“确定”。
在项目的 HTML 文件的<标题>部分中，在项目的 JavaScript 引用 default.css 和 default.js 之后，添加对 ad.js 的引用。
```
<script src="//Microsoft.Advertising.JavaScript/ad.js"></script>
```
在项目的 .js 文件中声明 InterstitialAd 对象和几个字段，这些字段包含间隙广告的应用程序 ID 和广告单元 ID。下面的代码示例将 applicationId 和 adUnitId 字段分配给间隙广告的测试值。

注意

每个 InterstitialAd 都有一个对应的广告单元，我们的服务使用该广告单元来为控件提供广告，每个广告单元都包含单元 ID 和应用程序 ID。在这些步骤中，你将为控件分配测试广告单元 ID 和应用程序 ID 值。这些测试值只能在应用的测试版本中使用。在将应用发布到 Microsoft Store 之前，必须在合作伙伴中心将这些测试值替换为实时值。
```
var interstitialAd = null;
var applicationId = "d25517cb-12d4-4699-8bdc-52040c712cab";
var adUnitId = "test";
```

在启动时运行的代码中（例如，在页面的构造函数中）实例化 InterstitialAd 对象，并安装对象的事件处理程序。

interstitialAd = new MicrosoftNSJS.Advertising.InterstitialAd();
interstitialAd.onErrorOccurred = errorOccurredHandler;
interstitialAd.onAdReady = adReadyHandler;
interstitialAd.onCancelled = cancelledHandler;
interstitialAd.onCompleted = completedHandler;

如果你需要显示间隙视频广告：在需要广告之前大约 30-60 秒，请使用 RequestAd 方法预取广告。这样就允许在应该显示广告之前有足够的时间请求和准备广告。请务必将广告类型指定为 InterstitialAdType.video。
```
if (interstitialAd) {
    interstitialAd.requestAd(MicrosoftNSJS.Advertising.InterstitialAdType.video, applicationId, adUnitId);
}
```
如果你需要显示间隙横幅广告：在需要广告之前大约 5-8 秒，请使用 RequestAd 方法预取广告。这样就允许在应该显示广告之前有足够的时间请求和准备广告。请务必将广告类型指定为 InterstitialAdType.display。
```
if (interstitialAd) {
    interstitialAd.requestAd(MicrosoftNSJS.Advertising.InterstitialAdType.display, applicationId, adUnitId);
}
```

此时在你想要显示广告的代码中，确认是否已准备好显示 InterstitialAd，然后使用 Show 方法显示它。

if (interstitialAd && interstitialAd.state === MicrosoftNSJS.Advertising.InterstitialAdState.ready) {
    interstitialAd.show();
}

定义 InterstitialAd 对象的事件处理程序。

function adReadyHandler(sender) {
  // Your code goes here.
}

function errorOccurredHandler(sender, args) {
  // Your code goes here.
}

function completedHandler(sender) {
  // Your code goes here.
}

function cancelledHandler(sender) {
  // Your code goes here.
}

生成并测试你的应用，以确认它会显示测试广告。

C++（DirectX 互操作）

此示例假设你已在 Visual Studio 中创建了 C++ DirectX 和 XAML 应用（通用 Windows）项目，并且面向特定的 CPU 体系结构。

在 Visual Studio 中打开项目。
在你的项目中添加对 Microsoft 广告 SDK 的引用：
1. 在解决方案资源管理器窗口中，右键单击引用，然后选择添加引用...
2. 在引用管理器中，展开通用 Windows、单击扩展，然后选中适用于 XAML 的 Microsoft 广告 SDK（版本 10.0）旁边的复选框。
3. 在引用管理器中，单击“确定”。

在应用的相应头文件（例如，DirectXPage.xaml.h）中，声明 InterstitialAd 对象和相关的事件处理程序方法。

Microsoft::Advertising::WinRT::UI::InterstitialAd^ m_interstitialAd;
void OnAdReady(Object^ sender, Object^ args);
void OnAdCompleted(Object^ sender, Object^ args);
void OnAdCancelled(Object^ sender, Object^ args);
void OnAdError(Object^ sender, Microsoft::Advertising::WinRT::UI::AdErrorEventArgs^ args);

在相同的头文件中声明几个字符串字段，这些字段代表间隙广告的应用程序 ID 和广告单元 ID。下面的代码示例将 myAppId 和 myAdUnitId 字段分配给间隙广告的测试值。

注意

每个 InterstitialAd 都有一个对应的广告单元，我们的服务使用该广告单元来为控件提供广告，每个广告单元都包含单元 ID 和应用程序 ID。在这些步骤中，你将为控件分配测试广告单元 ID 和应用程序 ID 值。这些测试值只能在应用的测试版本中使用。在将应用发布到 Microsoft Store 之前，必须在合作伙伴中心将这些测试值替换为实时值。
```
Platform::String^ myAppId = L"d25517cb-12d4-4699-8bdc-52040c712cab";
Platform::String^ myAdUnitId = L"test";
```
在要添加代码以显示间隙广告的 .cpp 文件中，添加以下命名空间引用。以下示例假设你要将代码添加到应用的 DirectXPage.xaml.cpp 文件中。
```
using namespace Microsoft::Advertising::WinRT::UI;
```

在启动时运行的代码中（例如，在页面的构造函数中）实例化 InterstitialAd 对象，并安装对象事件的事件处理程序。在以下示例中，InterstitialAdSamplesCpp 是项目的命名空间；请根据需要针对代码更改此名称。

m_interstitialAd = ref new InterstitialAd();         
m_interstitialAd->AdReady += ref new Windows::Foundation::EventHandler<Platform::Object ^>
    (this, &InterstitialAdSamplesCpp::DirectXPage::OnAdReady);
m_interstitialAd->Completed += ref new Windows::Foundation::EventHandler<Platform::Object ^>
    (this, &InterstitialAdSamplesCpp::DirectXPage::OnAdCompleted);
m_interstitialAd->Cancelled += ref new Windows::Foundation::EventHandler<Platform::Object ^>
    (this, &InterstitialAdSamplesCpp::DirectXPage::OnAdCancelled);
m_interstitialAd->ErrorOccurred += ref new
    Windows::Foundation::EventHandler<Microsoft::Advertising::WinRT::UI::AdErrorEventArgs ^>
    (this, &InterstitialAdSamplesCpp::DirectXPage::OnAdError);

如果你需要显示间隙视频广告：在需要间隙广告之前大约 30-60 秒，请使用 RequestAd 方法预取广告。这样就允许在应该显示广告之前有足够的时间请求和准备广告。请务必将广告类型指定为 AdType::Video。
```
m_interstitialAd->RequestAd(AdType::Video, myAppId, myAdUnitId);
```
如果你需要显示间隙横幅广告：在需要广告之前大约 5-8 秒，请使用 RequestAd 方法预取广告。这样就允许在应该显示广告之前有足够的时间请求和准备广告。请务必将广告类型指定为 AdType::Display。
```
m_interstitialAd->RequestAd(AdType::Display, myAppId, myAdUnitId);
```
此时在你想要显示广告的代码中，确认是否已准备好显示 InterstitialAd，然后使用 Show 方法显示它。
```
if ((InterstitialAdState::Ready == m_interstitialAd->State))
{
    m_interstitialAd->Show();
}
```

定义 InterstitialAd 对象的事件处理程序。

void DirectXPage::OnAdReady(Object^ sender, Object^ args)
{
    // Your code goes here.
}


void DirectXPage::OnAdCompleted(Object^ sender, Object^ args)
{
    // Your code goes here.
}

void DirectXPage::OnAdCancelled(Object^ sender, Object^ args)
{
    // Your code goes here.
}

void DirectXPage::OnAdError(Object^ sender, Microsoft::Advertising::WinRT::UI::AdErrorEventArgs^ args)
{
    // Your code goes here.
}

生成并测试你的应用，以确认它会显示测试广告。

发布包含实时广告的应用

确保在应用中对间隙广告的使用遵循我们的间隙广告指南。
在合作伙伴中心中，转到应用内广告页，然后创建广告单元。对于广告单元类型，请选择视频间隙或横幅间隙，具体取决于你将要显示的间隙广告类型。记下广告单元 ID 和应用程序 ID。

注意

测试广告单元和实时 UWP 广告单元的应用程序 ID 值采用不同的格式。测试应用程序 ID 值为 GUID。在合作伙伴中心中创建实时 UWP 广告单元时，该广告单元的应用程序 ID 值始终与应用的 Store ID（例如 Store ID 值类似于 9NBLGGH4R315）匹配。
你可以选择性地通过配置中介设置部分（位于应用内广告页面上）中的设置为间隙广告启用广告中介。广告中介显示来自多个广告网络（包括其他付费广告网络，如 Taboola 和 Smaato）的广告及 Microsoft 应用促销活动的广告，从而使你能够最大化你的广告收益和应用促销能力。
在你的代码中，将测试广告单元值替换为你在合作伙伴中心生成的实时值。
使用合作伙伴中心提交应用至 Microsoft Store。
在合作伙伴中心中查看广告性能报告。

管理你的应用中多个间隙广告控件的广告单元

你可以在单个应用中使用多个 InterstitialAd 控件。在此情况下，我们建议你为每个控件分配不同的广告单元。对每个控件使用不同的广告单元使你可以分别配置中介设置并获取每个控件的独立报告数据。这还使我们的服务能够更好地优化我们为应用提供的广告。

重要

每个广告单元都只能在一个应用中使用。如果在多个应用中使用某个广告单元，将不为该广告单元提供广告。

间隙广告

什么是间隙广告？

先决条件

在应用中集成间隙广告

XAML/.NET

HTML/JavaScript

C++（DirectX 互操作）

发布包含实时广告的应用

管理你的应用中多个间隙广告控件的广告单元

反馈

反馈

其他资源

间隙广告

什么是间隙广告？

先决条件

在应用中集成间隙广告

XAML/.NET

HTML/JavaScript

C++（DirectX 互操作）

发布包含实时广告的应用

管理你的应用中多个间隙广告控件的广告单元

相关主题

反馈

反馈

其他资源