Edit

Share via

AdControl in XAML and .NET

  • Article

Warning

As of June 1, 2020, the Microsoft Ad Monetization platform for Windows UWP apps will be shut down. Learn more

This walkthrough shows how to use the AdControl class to display banner ads in a Universal Windows Platform (UWP) XAML app for Windows 10 or Windows 11 that is implemented using C#.

Note

The Microsoft Advertising SDK also supports XAML apps that are implemented using C++. For a complete sample project, see the advertising samples on GitHub.

Prerequisites

Integrate a banner ad into your app

  1. In Visual Studio, open your project or create a new project.

    Note

    If you're using an existing project, open the Package.appxmanifest file in your project and ensure that the Internet (Client) capability is selected. Your app needs this capability to receive test ads and live ads.

  2. If your project targets Any CPU, update your project to use an architecture-specific build output (for example, x86). If your project targets Any CPU, you will not be able to successfully add a reference to the Microsoft advertising library in the following steps. For more information, see Reference errors caused by targeting Any CPU in your project.

  3. Add a reference to the Microsoft Advertising SDK in your project:

    1. From the Solution Explorer window, right click References, and select Add Reference…
    2. In Reference Manager, expand Universal Windows, click Extensions, and then select the check box next to Microsoft Advertising SDK for XAML (Version 10.0).
    3. In Reference Manager, click OK.

  4. Modify the XAML for the page where you are embedding advertising to include the Microsoft.Advertising.WinRT.UI namespace. For example, in the default sample app generated by Visual Studio (named, in this app, MyAdFundedWindows10AppXAML), the XAML page is MainPage.XAML.

    The Page section of the MainPage.xaml file generated by Visual Studio has the following code.

    <Page
  x:Class="MyAdFundedWindows10AppXAML.MainPage"
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  xmlns:local="using:MyAdFundedWindows10AppXAML"
  xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
  xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
  mc:Ignorable="d">
  <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
  </Grid>
</Page>

    Add the namespace reference Microsoft.Advertising.WinRT.UI so the Page section of the MainPage.xaml file has the following code.

    <Page
  x:Class="MyAdFundedWindows10AppXAML.MainPage"
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  xmlns:local="using:MyAdFundedWindows10AppXAML"
  xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
  xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
  xmlns:UI="using:Microsoft.Advertising.WinRT.UI"
  mc:Ignorable="d">
  <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
  </Grid>
</Page>

  5. In the Grid tag, add the code for the AdControl. Assign the AdUnitId and ApplicationId properties to the test ad unit values. Also adjust the Height and Width of the control so it is one of the supported ad sizes for banner ads.

    Note

    Every AdControl has a corresponding ad unit that is used by our services to serve ads to the control, and every ad unit consists of an ad unit ID and application ID. In these steps, you assign test ad unit ID and application ID values to your control. These test values can only be used in a test version of your app. Before you publish your app to the Store, you must replace these test values with live values from Partner Center.

    The complete Grid tag looks like this code.

    <Grid Background="{StaticResource ApplicationPageBackgroundThemeBrush}">
    <UI:AdControl ApplicationId="3f83fe91-d6be-434d-a0ae-7351c5a997f1"
        AdUnitId="test"
        HorizontalAlignment="Left"
        Height="250"
        VerticalAlignment="Top"
        Width="300"/>
</Grid>

    The complete code for the MainPage.xaml file should look like this.

    <Page
  x:Class="MyAdFundedWindows10AppXAML.MainPage"
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  xmlns:local="using:MyAdFundedWindows10AppXAML"
  xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
  xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
  xmlns:UI="using:Microsoft.Advertising.WinRT.UI"
  mc:Ignorable="d">
  <Grid Background="{StaticResource ApplicationPageBackgroundThemeBrush}">
        <UI:AdControl ApplicationId="3f83fe91-d6be-434d-a0ae-7351c5a997f1"
              AdUnitId="test"
              HorizontalAlignment="Left"
              Height="250"
              VerticalAlignment="Top"
              Width="300"/>
  </Grid>
</Page>

  6. Compile and run the app to see it with an ad.

Release your app with live ads

  1. Make sure your use of banner ads in your app follows our guidelines for banner ads.

  2. In Partner Center, go to the In-app ads page and create an ad unit. For the ad unit type, specify Banner. Make note of both the ad unit ID and the application ID.

    Note

    The application ID values for test ad units and live UWP ad units have different formats. Test application ID values are GUIDs. When you create a live UWP ad unit in Partner Center, the application ID value for the ad unit always matches the Store ID for your app (an example Store ID value looks like 9NBLGGH4R315).

  3. You can optionally enable ad mediation for the AdControl by configuring the settings in the Mediation settings section on the In-app ads page. Ad mediation enables you to maximize your ad revenue and app promotion capabilities by displaying ads from multiple ad networks, including ads from other paid ad networks such as Taboola and Smaato and ads for Microsoft app promotion campaigns.

  4. In your code, replace the test ad unit values (ApplicationId and AdUnitId) with the live values you generated in Partner Center.

  5. Submit your app to the Store using Partner Center.

  6. Review your advertising performance reports in Partner Center.

Manage ad units for multiple ad controls in your app

You can use multiple AdControl objects in a single app (for example, each page in your app might host a different AdControl object). In this scenario, we recommend that you assign a different ad unit to each control. Using different ad units for each control enables you to separately configure the mediation settings and get discrete reporting data for each control. This also enables our services to better optimize the ads we serve to your app.

Important

You can use each ad unit in only one app. If you use an ad unit in more than one app, ads will not be served for that ad unit.