Using the Microsoft Ad SDK in Windows 8

Article
08/28/2012

One of the best ways to make money with Windows 8 is to display ads in your Windows Store app using the Microsoft Advertising SDK. Here’s how you can get started.

Prerequisites: You’ll need Windows 8 RTM and Visual Studio 2012. A free 90 day evaluation edition of Windows 8 Enterprise is available, and VS2012 Express Edition is completely free.

Start by downloading and installing the Microsoft Advertising SDK. At the time this post is being written, Windows 8 RTM has been released, but the Microsoft Ad SDK is still in beta at version 6.1.0813.1. It works with Windows 8 RTM, but not all features are supported yet. The RTM version of the Microsoft Ad SDK is expected in mid-September. I’ll update this blog post as necessary then.

The SDK which you just installed supports both JavaScript and .NET. This post focuses on using the Ad SDK in a JavaScript app.

Open Visual Studio and create a JavaScript Windows Store Blank App:

In the Solution Explorer, right-click on References and select “Add Reference”. Then select the Microsoft Advertising SDK and click OK:

Back in the Solution Explorer, expand References and drill down into the SDK to find ad.js:

That’s the SDK. Open it if you like. It’s just a big JavaScript file.

Open default.html, and insert a <script> element to include the SDK. Do this in the <head> of your document, and make sure you add it after your <script> tag which calls default.js. You can easily add this <script> by dragging ad.js from the Solution Explorer to a point at the bottom of your <head> section. Or, just type it by hand:

In the <body> of default.html, insert the ad control:

It’s just a <div> with a “data-win-control” attribute, just like other Windows 8 controls. In “data-win-options” you can enter your applicationId from pubCenter (sign up there to get one), and you can also change the type of ad displayed by altering adUnitId. Lots of choices for adUnitId are listed in the Ad SDK documentation. Ad units vary by size, type (either text or image), and by the action that clicking on it produces. Match the <div>’s width and height to the size of the ad unit. In the above example, both the <div> and the ad returned are 728 pixels wide by 90 pixels high. Hit F5 to run your app:

If you tinker with the CSS a bit, which I like to do in Blend, you’ll end up with something passable such as this ad shown with the EaselJS game Space Rocks:

Now that we have the basics out of the way, let’s dig a little deeper. Here are all the options available for the AdControl:

data-win-control="MicrosoftNSJS.Advertising.AdControl"
data-win-options="{applicationId: 'test_client',
                    adUnitId: 'Image_300x250',
                    countryOrRegion: 'us',
                    isAutoRefreshEnabled: false,
                    keywords: 'windows8,awesome',
                    latitude: 40.47,
                    longitude: 73.58,
                    postalCode: '10021',
                    onAdRefreshed: myAdRefreshed,
                    onErrorOccurred: myAdError,
                    onEngagedChanged: myAdEngagedChanged,
                    onPointerDown: myPointerDown,
                    onPointerUp: myPointerUp }"

applicationId: your key from pubCenter
adUnitId: the type of ad
countryOrRegion: where you are
isAutoRefreshEnabled: set to false if you want to control how often a new ad is shown. Make your own call to refresh() to show a new ad. This doesn’t appear to work in the beta of the SDK though.
keywords, latitude, longitude, and postalCode can be used to request relevant ads based on keywords and location. If you get too specific, there might not be any ads available and nothing will be shown.
onAdRefreshed points to a function which will be called when an ad is refreshed.
onErrorOccurred points to a callback for errors.
onEngagedChanged points to a function which will be called when a user clicks on an ad. Depending on the adUnitId, this may show a fullscreen ad or even open a browser. Use this callback to pause the game. See the SDK documentation for an example.
onPointerDown and onPointerUp point to functions which are called when a user clicks, points, or touches inside an ad.

The above options are shown in HTML5, but they can also be set in JavaScript. For example:

var adDiv = document.getElementById("myAd");
var myAdControl = new MicrosoftNSJS.Advertising.AdControl(adDiv,
                {
                  applicationId: 'test_client',
                  adUnitId: 'Image_250x250'
                });
myAdControl.isAutoRefreshEnabled = false;
myAdControl.countryOrRegion = "us";
myAdControl.keywords = "windows8, rocks";
myAdControl.latitude = 40.47;
myAdControl.longitude = 73.58;
myAdControl.postalCode = "10021";
myAdControl.onErrorOccurred = myAdError;
myAdControl.onAdRefreshed = myAdRefreshed;
myAdControl.onEngagedChanged = myAdEngagedChanged;

Check out the Additional Help page in the SDK documentation for more resources including a link to the online support forum.

Screenshots made with SnagIt from TechSmith.

Using the Microsoft Ad SDK in Windows 8

Additional resources