Install the Microsoft Advertising SDK for Windows and Windows Phone 8.x

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

To display ads in your Windows apps, install the Microsoft Advertising SDK for Windows and Windows Phone 8.x. This SDK is an extension to Visual Studio 2015 and Visual Studio 2013.

Installation instructions

To install the Microsoft Advertising SDK for Windows and Windows Phone 8.x:

1. Close all instances of Visual Studio.

2. If you previously installed any previous versions of the Microsoft Advertising SDK, uninstall these SDK versions now. Optionally, open a Command Prompt window and run these commands to clean out any older advertising SDK versions that may have been installed with Visual Studio, but which may not appear in the list of installed programs on your computer:

   MsiExec.exe /x{5C87A4DB-31C7-465E-9356-71B485B69EC8}
   MsiExec.exe /x{6AB13C21-C3EC-46E1-8009-6FD5EBEE515B}
   MsiExec.exe /x{6AC81125-8485-463D-9352-3F35A2508C11}
   

3. Download and install the Microsoft Advertising SDK for Windows and Windows Phone 8.x. It may take a few minutes to install. Be sure and wait until the process has finished.

4. Restart Visual Studio.

5. If you have an existing project that references advertising libraries from any earlier version of the Microsoft Advertising SDK, we recommend that you open your project in Visual Studio and clean and rebuild your project (in Solution Explorer, right-click your project node and choose Clean, and then right-click your project node again and choose Rebuild).

For walkthroughs that show how to get started using the advertising APIs, see the following articles:

• Banner ads
• Interstitial ads

Update your app to the latest SDK for banner ads

Windows 8.x and Windows Phone 8.x apps that show banner ads must use AdControl or AdMediatorControl from the Microsoft Advertising SDK for Windows and Windows Phone 8.x. This SDK supports a minimum set of advertising capabilities, including the ability to serve HTML5 rich media via the Mobile Rich-media Ad Interface Definitions (MRAID) 1.0 specification from the Interactive Advertising Bureau (IAB). Many of our advertisers seek these capabilities, and we require app developers to use this SDK release to help make our app ecosystem more attractive to advertisers and ultimately drive more revenue to you.

Before this SDK released, we previously provided several older advertising SDK releases for Windows 8.x and Windows Phone 8.x apps. These older advertising SDK releases are no longer supported because they do not support the minimum advertising capabilities described above.

As of April 1, 2017, we no longer serve banner ads to apps that use an unsupported advertising SDK release. If you have an existing app (already in the Store or still under development) that displays banner ads using AdControl or AdMediatorControl and you aren't sure which advertising SDK is being used by your app, follow the instructions below to determine whether you need to update your app to a supported SDK. If you encounter any issues or you need assistance, please contact support.

Note  If your app already uses the Microsoft Advertising SDK for Windows and Windows Phone 8.x, your app already uses the latest available SDK and you do not need to make any further changes to your app.

Prerequisites

• The complete source code and Visual Studio project files for your app that uses AdControl or AdMediatorControl.
• The .appx or .xap package for your app. Note  If you no longer have the .appx or .xap package for your app but you do still have a development computer with the version of Visual Studio and the advertising SDK that was used to build your app, you can regenerate the .appx or .xap package in Visual Studio.  

Part 1: Determine whether you need to update your app

Follow the instructions in the following sections to determine if you need to update your app.

Your app uses AdControl

1. Create a copy of the the .appx or .xap package for your app so you do not disturb the original, rename the copy so it has a .zip extension, and extract the contents of the file.

2. Check the extracted contents of your app package:

   • If you see a Microsoft.Advertising.winmd file but no UniversalXamlAdControl.\*.dll file, your app uses an old SDK and you must update your project by following the instructions in the sections below. Proceed to Part 2.
   • Otherwise, continue with the following step.

3. Open Windows PowerShell, enter the following command, and assign the -Path argument to the full path to the extracted contents of your app package. This command displays all the advertising libraries that are referenced by your project and the version of each library.

   get-childitem -Path "<path to your extracted package>" * -Recurse -include *advert*.dll,*admediator*.dll,*xamladcontrol*.dll,*universalsharedlibrary*.dll | where-object {$_.Name -notlike "*resources*" -and $_.Name -notlike "*design*" } | foreach-object { "{0}`t{1}" -f $_.FullName, [System.Diagnostics.FileVersionInfo]::GetVersionInfo($_).FileVersion }
   

4. Locate the file listed in the following table for the target platform of your app, and compare the versions of that file with the version listed in the table.

5. If the file has a version that is equal to or later than the version listed in the previous table, you do not need to make any changes to your project. If the file has a lower version number, you must update your project by following the instructions in the sections below. Proceed to Part 2.

Your app uses AdMediatorControl

1. Create a copy of the the .appx or .xap package for your app so you do not disturb the original, rename the copy so it has a .zip extension, and extract the contents of the file.

2. Open Windows PowerShell, enter the following command, and assign the -Path argument to the full path to the extracted contents of your app package. This command displays all the advertising libraries that are referenced by your project and the version of each library.

    get-childitem -Path "<path to your extracted package>" * -Recurse -include *advert*.dll,*admediator*.dll,*xamladcontrol*.dll,*universalsharedlibrary*.dll | where-object {$_.Name -notlike "*resources*" -and $_.Name -notlike "*design*" } | foreach-object { "{0}`t{1}" -f $_.FullName, [System.Diagnostics.FileVersionInfo]::GetVersionInfo($_).FileVersion }
   

3. If the version of the Microsoft.AdMediator.\*.dll files listed in the output are version 2.0.1603.18005 or later, you do not need to make any changes to your project. If these files have a lower version number, you must update your project by following the instructions in the sections below. Proceed to Part 2.

Part 2: Install the latest SDK

If your app uses an old SDK release, follow the instructions at the beginning of this article to be sure you have the latest SDK on your development computer.

Part 3: Update your project

Follow these instructions to update your project.

Windows 8.1 or Windows Phone 8.1 projects

1. Remove all Microsoft.Advertising.\* and Microsoft.AdMediator.\* references from your project. You may have two references (one each for Windows and Windows Phone) if you used the Universal project template.
2. If your app uses AdMediatorControl, add back the library references by following the instructions in Adding and using the ad mediation control. If your app uses AdControl, add back the library references by following the instructions in Banner ads.

Note the following:

• If your app was previously compiled to the Any CPU platform, you must recompile your project to an architecture-specific platform (x86, x64, or ARM).
• If you have a Windows Phone 8.x XAML app that previously used a version of the SDK in which the AdControl class was defined in the Microsoft.Advertising.Mobile.UI namespace, you must update your code to refer to the AdControl class in the Microsoft.Advertising.WinRT.UI namespace (this class moved namespaces in the more recent SDK releases).
• Other than the previous issue, you can preserve your existing XAML markup and code.

Windows Phone 8.x Silverlight projects

1. Remove all Microsoft.Advertising.\* and Microsoft.AdMediator.\* references from your project.
2. If your app uses AdMediatorControl, add back the library references by following the instructions in Adding and using the ad mediation control. If your app uses AdControl, add back the library references by following the instructions in Banner ads.

Note the following:

• You can preserve your existing XAML markup and code.
• From Solution Explorer, check the properties for the Microsoft.Advertising.Mobile.UI reference in your project. It should be version 6.2.40501.0 if your app targets Windows Phone 8.0, or 8.1.50112.0 if your app targets Windows Phone 8.1.
• For Windows Phone 8.x Silverlight apps, testing production units on an emulator is not supported. We recommend that you test on a device.

Part 4: Test and republish your app

Test your app to make sure it displays banner ads as expected.

If the previous version of your app is already available in the Store, create a new submission for your updated app in the Dev Center dashboard to republish your app.

Related topics

Banner ads

Interstitial ads