间隙广告

项目
07/05/2024

警告

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

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

什么是间隙广告？

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

使用 Paywall 广告时，用户必须定期观看广告。例如，游戏级别之间：
借助基于 Rewards 的广告，用户会显式寻求一些好处，例如提示或额外时间来完成级别，并通过应用的用户界面初始化广告。

我们提供两种类型的间隙广告用于你的应用和游戏： 间隙视频广告 和 间隙横幅广告。

注意

间隙广告的 API 不会处理除视频播放时以外的任何用户界面。在考虑如何在应用中集成间隙广告时，请参阅间隙最佳做法，了解操作指南，并避免这样做。

先决条件

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

将间隙广告集成到应用中

若要在应用中显示间隙广告，请按照项目类型的说明操作：

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

XAML/.NET

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

在 Visual Studio 中打开项目。

注意

如果使用的是现有项目，请在项目中打开 Package.appxmanifest 文件，并确保 已选择 Internet（客户端） 功能。你的应用需要此功能才能接收测试广告和实时广告。
如果你的项目面向任何 CPU，请更新你的项目以使用特定于体系结构的生成输出（例如，x86）。如果你的项目面向任何 CPU，你将无法在以下步骤中成功添加对 Microsoft Advertising 库的引用。有关详细信息，请参阅项目中由面向任何 CPU 引起的引用错误。
在项目中添加对Microsoft 广告 SDK的引用：
1. 在解决方案资源管理器窗口中，右键单击引用，然后选择添加引用...
2. 在引用管理器中，展开通用 Windows，单击“扩展”，然后选择 XAML（版本 10.0）Microsoft 广告 SDK旁边的复选框。
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（版本 10.0）Microsoft 广告 SDK旁边的复选框。
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：:D isplay 。
```
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）匹配。
可以选择通过在应用内广告页上的 中介设置部分配置设置来为 InterstitialAd 启用广告中介。通过广告中介，你可以通过显示来自多个广告网络的广告（包括来自其他付费广告网络（如 Taboola 和 Smaato）的广告以及用于Microsoft应用促销活动的广告来最大化广告收入和应用推广功能。
在你的代码中，将测试广告单元值替换为你在合作伙伴中心生成的实时值。
使用合作伙伴中心提交应用至 Microsoft Store。
在合作伙伴中心中查看广告性能报告。

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

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

重要

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

通过

间隙广告

什么是间隙广告？

先决条件

将间隙广告集成到应用中

XAML/.NET

HTML/JavaScript

C++ （DirectX 互操作）

使用实时广告发布应用

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

反馈

其他资源

通过

间隙广告

什么是间隙广告？

先决条件

将间隙广告集成到应用中

XAML/.NET

HTML/JavaScript

C++ （DirectX 互操作）

使用实时广告发布应用

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

相关主题

反馈

其他资源