Review of WP7 Mango Beta’s Advertising SDK

I’ve been using Microsoft’s XNA Advertising SDK since March and consider it to be the top XNA Ad SDK for Windows Phone 7. I’ve also invested a lot of time notifying Microsoft of over 70 problems with that SDK’s software and documentation and have been eagerly awaiting a new release that addresses those issues. The latest Ad SDK (version 5.2) has been available since June and is now included in the Mango Dev Tools Beta (previously it was not in the Dev Tools and was only provided as a separate download). Yesterday, I decided to port my code to v5.2 and this article describes my observations in doing that.

• SDK LOCATION

  Note that this new version of the Advertising SDK has been relocated from this folder “C:\Program Files (x86)\Microsoft Advertising SDK for Windows Phone 7? to this folder “C:\Program Files (x86)\Microsoft SDKs\Advertising for Phone”. Microsoft recommends that you uninstall the previous version before installing the new one, but be aware that this new version has breaking changes, so I left the old version on my drive and am still using it without issue.

• SDK DOCUMENTATION – HELP FILE

  I had sent Microsoft a list of 65 errors in the previous SDK’s documentation, so I was really interested to see how many of them were addressed in the new “Microsoft Advertising SDK for Windows Phone 7.chm” Help File. Overall the documentation is better than it was in the previous version, but it still needs some work. My comments follow:

  1. The simplified main menu is much easier to read and understand.
  2. The introduction now clearly explains how the terms “application” and “game” are used through the Help File.
  3. The “What’s New” section describes changes to SDK version 5.2, and says “The goal of this release is to make the Advertising namespaces cleaner and easier to use. Developer feedback was reviewed and prioritized; more simplicity in the control was a predominant theme.” The Silverlight changes are clearly documented, but the XNA changes (although highly similar) are missing – Oops! Here is a good substitute by Arthur Bierer from Microsoft Advertising http://community.microsoftadvertising.com/forums/t/69768.aspx
  4. The “Getting Started” section clearly describes how to download & install the SDK, but since you only get the Help File by installing the SDK, I’m not sure why the “Download & Installation” page is necessary.
  5. The other “Getting Started” page is about pubCenter and has useful info, but this section needs work. It’s not technically accurate, since an LLC is not “incorporated”. It also still does not address concerns of non-U.S. developers, or indie devs in the U.S. Military, and it should! And I really think the “we can’t send checks to P.O. boxes” line is B.S. and should be removed. If I can send a check to a P.O. Box (or an FPO/MPO Box), then certainly Microsoft can too. Besides, most U.S. devs are going to wire-transfer payments directly into their bank accounts (or should!). A simple & secure way to pay non-U.S. devs & military personnel that could be implemented very quickly: Allow payment via PayPal.
  6. Developing Section: UI & Experience Guidelines page has good stuff, but still focused solely on Silverlight AdControl. “Recommended Ad Unit Format” page explains how smaller ads would be centered in larger AdControls, but doesn’t explain why this can happen. Note: The API still does not allow specifying a background fill color for this scenario, which would be nice.
  7. Developing Section: Integrating Ads in Apps (should be “Integrating Ads in Apps & Games”): The “Integrating” examples are too simplistic, awkwardly presented, and fairly useless. The inclusion of TextAd testing here isn’t needed, since real ad-units are always specified as Image Banners (that can render text ads too). And finally, Microsoft should explain why ID_CAP_IDENTITY_USER, ID_CAP_MEDIALIB, and ID_CAP_PHONE_DIALER are required capabilities for using the Ad SDK.
  8. API Reference Section: Looks complete. Missing Visual Basic code blocks and the empty C++, J#, and JScript sections should probably be removed.
  9. SDK Samples Section: these “sample” pages are what the Developing Section’s Integrating examples are linked to, and as mentioned above, they’re not very useful. Even the “Additional Samples Online” page links to a website showing two *Deprecated* samples. This section should instead reference Visual Studio sample solutions within the SDK, but none exist. For example, it should instead link to this MSDN Code Sample and include that sample code in the SDK.
  10. Known Issues Section: This section lists known issues with the SDK and provides two hyperlinks to online versions of this documentation that *might* have updates to this list. I still think it would be better to provide a link to pubCenter Support, since their list of known issues is updated in real-time.
• API CHANGES

  Changing my code to use Ad SDK v5.2 was not difficult, but I did run into one big snag that is still unresolved (more on this below in “The Worst API Change” section).

  In general, my feelings about the SDK changes evoke an old cliche: “If it ain’t broke, don’t fix it”. Apparently Microsoft Advertising hasn’t heard that one before. Yes, there have been some serious things wrong with the pubCenter system, SDK documentation, drawing of Ads, crashes, incorrect event firings, corrupted Ad graphics, incorrect target URLs, ignoring component DrawOrder, and bad Web redirects. Some of these issues have been fixed, but not all of them – a fact that makes the unnecessary API changes in v5.2 feel very superficial.

  The previous API was OK and it did what it was supposed to do. I’m sure there were devs who said it wasn’t as clear as it could be (I said this too), but does that justify renaming, removing, or redesigning just about *every* class, function, and member of the public API? No, it doesn’t, but that’s exactly what Microsoft did in v5.2 – and it just leaves me wondering “Why?”. Why make everyone who has already integrated the Ad SDK into their software do it all over again, when it worked fine already? Why not finish fixing the real problems and adding new features instead of changing the whole API? So many breaking changes – it’s a good thing this API wasn’t that big to begin with.

  I can see that some of the changes had other purposes – the Singleton implementation prevents devs from accidentally creating multiple AdManagers and really gumming things up. Searching on “DrawableAd” in your code will give you more accurate search results than just “Ad” would. And getting rid of the unused demographic data items was long overdue. But while some of the renames make sense (although still unnecessary), other renames just seem silly. For example, “AdManager” to “AdGameComponent”, which only makes it more clear that XNA is being used (which the developer already knows), while making less clear what the component actually does, “Ad Management”.

  The “biggest silliness award” goes to using the verb “Refresh” instead of “Request”. It’s client-server afterall, you send a request and the server replies. Why isn’t this 40-year old commonly used terminology clear enough? In nearly all other products where distributed data is displayed, “refresh” implies that the data being displayed is stale (temporally irrelevant) and there is possibly newer data that could be displayed. Do in-app Ads become stale within 30 seconds that would justify this terminology switch? I don’t think so, and really, if you have to think this hard to justify it, then it doesn’t warrant having your whole developer base doing “Refactor-Renames” for their next software release.

• THE WORST API CHANGE

  Now if those were my only beefs with the API, I probably wouldn’t be blogging about it right now. But there is one change that drew my ire – the removal of the ErrorCode from the ErrorOccurred event args. Some devs won’t care about this, but I really do. Arthur Bierer’s provided an explanation of the ErrorCode’s removal and I just don’t buy it:

  “The ErrorEventArgs is now known as AdErrorEventArgs and contains the error as a property. We no longer offer an ErrorCode to decode why an ad was not returned, as the exception will contain all the information.”

  The exception info is contained in a Message string. While that’s great if you just want to read it during debug, it’s completely insufficient if you want your code to react differently based on the cause of the error. Remember, NoAdAvailable errors are fairly common with pubCenter and most other mobile Ad-Networks. Most devs will ignore them, although I prefer to inject ads from other sources when this occurs. With the error code, this is very easy to do, and I can keep retrying to see if pubCenter eventually fills the ad, so that I can return to displaying pubCenter ads.

  But what about the “NoConnectionError” and “OtherError” codes? I can no longer distinguish them from “NoAdAvailable”. If I lose the connection, it could mean one of a few things, but it usually means I’ve lost my Internet connection (common on a phone) or pubCenter is down (which happened for 2 whole days in 2011 so far). “OtherError” is very infrequent and represents some unspecified internal error in the AdManager component – and has sometimes been unrecoverable.

  With “NoAdAvailable”, I’m more likely to give pubCenter another cycle to get an ad, or to programmatically change ad-units to see if it has better luck. But with these “NoConnectionError” and “OtherError” codes, pubCenter is on a short leash and I’m more inclined to failover to another Ad Network for a while (for example, AdDuplex or House Ads). This is why that ErrorCode is useful, and I’m a little steamed that this perfectly working functionality has been removed in v5.2.

So please, Microsoft Advertising, put the ErrorCode back into the API before the Mango release, and I’ll overlook all of the other stuff that I complained about up there…

CodeProject