HTML5 Zone is brought to you in partnership with:

Microsoft Developer Evangelist in San Francisco and Silicon Valley. Matt has posted 1 posts at DZone. You can read more from them at their website. View Full User Profile

Using the Microsoft Ad SDK in Windows 8

10.22.2012
| 3581 views |
  • submit to reddit

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:

SNAGHTML3c3f61

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

SNAGHTML45512c

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

image

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:

<script src="http://blogs.msdn.com/MSAdvertisingJS/ads/ad.js"></script>

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

<div id="myAd" style='position: absolute; top: 53px; left: 0px; width: 728px; height: 90px; z-index: 1'
    data-win-control="MicrosoftNSJS.Advertising.AdControl"
    data-win-options="{applicationId: 'test_client', adUnitId: 'Image_728x90'}">
</div>

 

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:

image

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:

image

 

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.

 

 

 

Published at DZone with permission of its author, Matt Harrington. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)