本机广告

项目
06/02/2023

警告

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

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

对于广告商而言，本机广告提供了高绩效的展示位置，因为广告体验紧密集成在应用中，用户倾向于与此类广告进行更多的互动。

注意

本机广告目前仅支持用于Windows 10和Windows 11的基于 XAML 的 UWP 应用。我们打算在未来的 Microsoft 广告 SDK 版本中支持使用 HTML 和 JavaScript 编写的 UWP 应用。

先决条件

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

在应用中集成本机广告

请按照以下说明在应用中集成本机广告，并确认你的本机广告实现显示了测试广告。

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

注意

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

注意

每个 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 事件处理程序，并向 e 参数传递代表此本机广告的 NativeAdV2 对象。使用 NativeAdV2 属性获取本机广告的每个元素，在页面上显示这些元素。此外，请务必调用 RegisterAdContainer 方法注册用作本机广告容器的 UI 元素；要正确跟踪广告曝光数和点击数，就必须执行此操作。

注意

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

例如，假设你的应用包含以下 MainPageStackPanel 的 (或其他一些页面) 。此 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());
}

编译并运行应用以查看是否带有测试广告。

发布包含实时广告的应用

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

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

注意

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

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

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

重要

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

本机广告

先决条件

在应用中集成本机广告

发布包含实时广告的应用

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

反馈

反馈

其他资源

本机广告

先决条件

在应用中集成本机广告

发布包含实时广告的应用

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

相关主题

反馈

反馈

其他资源