本机广告

项目
07/05/2024

警告

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

本机广告是基于组件的广告格式，其中每一个广告创意元素（如标题、图像、说明和行动号召文字）都作为单独的元素提供给你。可以使用自己的字体、颜色、动画和其他 UI 组件将这些元素集成到应用中，以将不显眼的用户体验拼凑在一起，适合你的应用的外观，同时从广告中获得高收益。

对于广告商来说，本机广告提供高性能的放置，因为广告体验紧密集成到应用中，因此用户倾向于与这些类型的广告交互更多。

注意

当前仅支持基于 XAML 的 UWP 应用（适用于 Windows 10 和 Windows 11）的本机广告。计划针对使用 HTML 和 JavaScript 编写的 UWP 应用提供支持，以便将来发布Microsoft 广告 SDK。

先决条件

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

将本机广告集成到应用中

按照以下说明将本机广告集成到应用中，并确认本机广告实现是否显示测试广告。

在 Visual Studio 中，打开项目或创建新项目。

注意

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

注意

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

在启动时运行的代码（例如，在页面的构造函数中），实例化 NativeAdsManagerV2 对象，并连接对象的 AdReady 和 ErrorOccurred 事件的事件处理程序。

myNativeAdsManager = new NativeAdsManagerV2(myAppId, myAdUnitId);
myNativeAdsManager.AdReady += MyNativeAd_AdReady;
myNativeAdsManager.ErrorOccurred += MyNativeAdsManager_ErrorOccurred;

准备好显示本机广告时，请调用 RequestAd 方法提取广告。
```
myNativeAdsManager.RequestAd();
```

为应用准备本机广告时，将调用 AdReady 事件处理程序，并将表示本机广告的 NativeAdV2 对象传递给 e 参数。 使用 NativeAdV2 属性获取本机广告的每个元素，并在页面上显示这些元素。请务必调用 RegisterAdContainer 方法来注册充当本机广告容器的 UI 元素;这是正确跟踪广告印象和点击所必需的。

注意

本机广告的某些元素是必需的，并且必须始终显示在应用中。有关详细信息，请参阅有关本机广告的指南。

例如，假设你的应用包含以下 StackPanel 的一个MainPage（或其他一些页面）。此 StackPanel 包含一系列控件，这些控件显示本机广告的不同元素，包括标题、说明、图像、由文本赞助的按钮，以及显示操作文本调用的按钮。

<StackPanel x:Name="NativeAdContainer" Background="#555555" Width="Auto" Height="Auto"
            Orientation="Vertical">
    <Image x:Name="AdIconImage" HorizontalAlignment="Left" VerticalAlignment="Center"
           Margin="20,20,20,20"/>
    <TextBlock x:Name="TitleTextBlock" HorizontalAlignment="Left" VerticalAlignment="Center"
           Text="The ad title will go here" FontSize="24" Foreground="White" Margin="20,0,0,10"/>
    <TextBlock x:Name="DescriptionTextBlock" HorizontalAlignment="Left" VerticalAlignment="Center"
               Foreground="White" TextWrapping="Wrap" Text="The ad description will go here"
               Margin="20,0,0,0" Visibility="Collapsed"/>
    <Image x:Name="MainImageImage" HorizontalAlignment="Left"
           VerticalAlignment="Center" Margin="20,20,20,20" Visibility="Collapsed"/>
    <Button x:Name="CallToActionButton" Background="Gray" Foreground="White"
            HorizontalAlignment="Left" VerticalAlignment="Center" Width="Auto" Height="Auto"
            Content="The call to action text will go here" Margin="20,20,20,20"
            Visibility="Collapsed"/>
    <StackPanel x:Name="SponsoredByStackPanel" Orientation="Horizontal" Margin="20,20,20,20">
        <TextBlock x:Name="SponsoredByTextBlock" Text="The ad sponsored by text will go here"
                   FontSize="24" Foreground="White" Margin="20,0,0,0" HorizontalAlignment="Left"
                   VerticalAlignment="Center" Visibility="Collapsed"/>
        <Image x:Name="IconImageImage" Margin="40,20,20,20" HorizontalAlignment="Left"
               VerticalAlignment="Center" Visibility="Collapsed"/>
    </StackPanel>
</StackPanel>

下面的代码示例演示了一个 AdReady 事件处理程序，该事件处理程序在 StackPanel 中的控件中显示本机广告的每个元素，然后调用 RegisterAdContainer 方法来注册 StackPanel。此代码假定它从包含 StackPanel 的页面的代码隐藏文件运行。

void MyNativeAd_AdReady(object sender, NativeAdReadyEventArgs e)
{
    NativeAdV2 nativeAd = e.NativeAd;

    // Show the ad icon.
    if (nativeAd.AdIcon != null)
    {
        AdIconImage.Source = nativeAd.AdIcon.Source;

        // Adjust the Image control to the height and width of the 
        // provided ad icon.
        AdIconImage.Height = nativeAd.AdIcon.Height;
        AdIconImage.Width = nativeAd.AdIcon.Width;
    }

    // Show the ad title.
    TitleTextBlock.Text = nativeAd.Title;

    // Show the ad description.
    if (!string.IsNullOrEmpty(nativeAd.Description))
    {
        DescriptionTextBlock.Text = nativeAd.Description;
        DescriptionTextBlock.Visibility = Visibility.Visible;
    }

    // Display the first main image for the ad. Note that the service
    // might provide multiple main images. 
    if (nativeAd.MainImages.Count > 0)
    {
        NativeImage mainImage = nativeAd.MainImages[0];
        BitmapImage bitmapImage = new BitmapImage();
        bitmapImage.UriSource = new Uri(mainImage.Url);
        MainImageImage.Source = bitmapImage;

        // Adjust the Image control to the height and width of the 
        // main image.
        MainImageImage.Height = mainImage.Height;
        MainImageImage.Width = mainImage.Width;
        MainImageImage.Visibility = Visibility.Visible;
    }

    // Add the call to action string to the button.
    if (!string.IsNullOrEmpty(nativeAd.CallToActionText))
    {
        CallToActionButton.Content = nativeAd.CallToActionText;
        CallToActionButton.Visibility = Visibility.Visible;
    }

    // Show the ad sponsored by value.
    if (!string.IsNullOrEmpty(nativeAd.SponsoredBy))
    {
        SponsoredByTextBlock.Text = nativeAd.SponsoredBy;
        SponsoredByTextBlock.Visibility = Visibility.Visible;
    }

    // Show the icon image for the ad.
    if (nativeAd.IconImage != null)
    {
        BitmapImage bitmapImage = new BitmapImage();
        bitmapImage.UriSource = new Uri(nativeAd.IconImage.Url);
        IconImageImage.Source = bitmapImage;

        // Adjust the Image control to the height and width of the 
        // icon image.
        IconImageImage.Height = nativeAd.IconImage.Height;
        IconImageImage.Width = nativeAd.IconImage.Width;
        IconImageImage.Visibility = Visibility.Visible;
    }

    // Register the container of the controls that display
    // the native ad elements for clicks/impressions.
    nativeAd.RegisterAdContainer(NativeAdContainer);
}

定义 ErrorOccurred 事件的事件处理程序，以处理与本机广告相关的错误。以下示例在测试期间将错误信息写入 Visual Studio 输出窗口。

private void MyNativeAdsManager_ErrorOccurred(object sender, NativeAdErrorEventArgs e)
{
    System.Diagnostics.Debug.WriteLine("NativeAd error " + e.ErrorMessage +
        " ErrorCode: " + e.ErrorCode.ToString());
}

编译并运行应用，以通过测试广告查看它。

使用实时广告发布应用

确认本机广告实现成功显示测试广告后，请按照以下说明将应用配置为显示真实广告并将更新的应用提交到应用商店。

确保本机广告实现遵循本机广告指南。
在合作伙伴中心中，转到应用内广告页，然后创建广告单元。对于广告单元类型，请指定 Native。记下广告单元 ID 和应用程序 ID。

注意

测试广告单元和实时 UWP 广告单元的应用程序 ID 值采用不同的格式。测试应用程序 ID 值为 GUID。在合作伙伴中心中创建实时 UWP 广告单元时，该广告单元的应用程序 ID 值始终与应用的 Store ID（例如 Store ID 值类似于 9NBLGGH4R315）匹配。
可以选择通过在应用内广告页上的中介设置部分配置设置来为本机广告启用广告中介。通过广告中介，可以通过显示来自多个广告网络的广告来最大化广告收入和应用推广功能。
在代码中将测试广告单元值（即 NativeAdsManagerV2 构造函数的 applicationId 和 adUnitId 参数）替换为在合作伙伴中心生成的实时值。
使用合作伙伴中心提交应用至 Microsoft Store。
在合作伙伴中心中查看广告性能报告。

在应用中管理多个本机广告的广告单元

可以在单个应用中使用多个本机广告位置。在此方案中，建议为每个本机广告放置分配不同的广告单元。使用本机广告的不同广告单元可以单独配置中介设置，并为每个控件获取离散报告数据。这还使我们的服务能够更好地优化我们为应用提供的广告。

重要

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

通过

本机广告

先决条件

将本机广告集成到应用中

使用实时广告发布应用

在应用中管理多个本机广告的广告单元

反馈

其他资源

通过

本机广告

先决条件

将本机广告集成到应用中

使用实时广告发布应用

在应用中管理多个本机广告的广告单元

相关主题

反馈

其他资源