Windows Phone – Getting Started

Installing AdRotator in a Windows Phone project is now easier than ever, just add the control to your page, setup your configuration XML and off you go.

Windows Phone at present supports the following Ad Providers:

Installing AdRotator for Windows Phone

The best way to get a hold of the new and improved AdRotator control is through NuGet, just search for the “AdRotator” project, install and away you go, we include everything you needs to get started, including:

  • The AdRotator DLL’s for your platform (The Core Project and a platform specific DLL)
  • A sample Configuration XML file
  • A Read-Me file with everything you need to get started

*Note  As the V2 control is still an Alpha release, please ensure you check the “Include PreRelease” option when installing NuGet Packages

Enabling Providers

When implementing the AdRotator control it’s important to decide which providers you wish to support and add their respective SDK’s to your project, if you don’t add an ad providers SDK then configuration for that provider will be ignored.

Ensure you get the specific version for the level of Windows Phone you are using, some of the controls will work on both but if you are targetting Windows Phone 8 specifically and there is a WP8 version available, then use that.  Some WP7 versions have issue natively on WP8 (but work fine in WP7 compatibility more on WP8)

For more detail on the providers we support for Windows Phone, visit their respective web sites to obtain their latest SDK:

Control Usage

To create an instance of the AdRotatorControl use the following template:

<adRotator:AdRotatorControl 
		x:Name="AdRotator"
		xmlns:adRotator="clr-namespace:AdRotator;assembly=AdRotator"
		AdHeight="90"
		AdWidth="480"
		LocalSettingsLocation="defaultAdSettings.xml"
		AutoStartAds="True" />

*Note – in a change from V1 – you only need to use the Invalidate function if you want to state the control manually. If you would rather Ads started automatically, set the “AutoStart” option to true, see below

Important properties of the AdRotator control:

  • IsEnabled - setting this property to false will collapse the control
  • RemoteSettingsLocation – URL to the remote XML file that controls the probability of ad providers shown. Strongly advised to set this property (otherwise there’s not much point in using the control)
  • DefaultAdType - what ad type should be shown if either the ad settings file could not be loaded or other ad providers have failed to load. The value of this property can be PubCenter, AdMob, AdDuplex, InnerActive or None.
  • LocalSettingsLocation – URI to a local xml file that will be used if the remote file specified with SettingsUrl could not be loaded since the installation of the application using the control.
  • AutoStart – Controls whether AdRotator will start delivering Ad’s straight away or not, to control this manually set to false
  • AdWidth – Set’s the width of the AdControl, also sets the request Ad Width to Ad Providers (be sure to check your supported provided Ad Widths)
  • AdHeight – Set’s the height of the AdControl, also sets the request Ad Height to Ad Providers (be sure to check your supported provided Ad Heights)
  • IsTest – Sets Ad Providers in to “Test” mode (where supported)
  • IsAdRotatorEnabled – Control whether AdRotator is enabled or not, if disabled it will not display on screen or collect Ads.
  • AdRefreshInterval – Controls how often AdRotator will try to refresh Ads, the minimum value (and default) is 60 seconds

We also recommend that if you intend to use the control on multiple pages that you embed the above control in a separate User Control for your app and use that User Control for the pages you wish to implement it in.

Default House AD functionality

*Coming Soon (currently not implemented in the V2 stream yet)

With AdRotator you have the ability to create your own ads through the Default House AD functionality.

To use this just define your own user control with the dimension of 480wx100h with the content that you want to display, optionally you can either hook your Click event within your control or hook it up externally in your Page.cs using the “DefaultHouseAdClick” Event.

With your control defined either set the “DefaultHouseAdBody” setting in XAML or add a secondaryID property in the configuration XML for the HouseAd to:

<namespace>.<object name>

For example in the test solution we set the default house Ad that is in the same project to:

AdRotatorExample.MyDefaultAd

And to alternately use the Ad in the separate class library we set it to:

DefaultAdSolution.MyLibraryHouseAd

So long as the local XAML is in your project and can be referenced it will be available.  We’ve also tested thoroughly that if it cannot find it for any reason it will fail cleanly and just disable the house Ad.

As before if you also provide a Remote House Ad URL that will take preference unless it is unable to download it.

The Ad Configuration File

When you install AdRotator through NuGet we supply a sample configuration file for use titled “defaultAdSettings.xml”.  Either hosted within your solution or remotely on an external website (or both) this file tailors the AdRotator experience within your application.

Since V1 this configuration file has been significantly advanced to allow more flexibility and control with the additional capability to have more than one configuration for a single provider.

For more details on the configuration file see the “Configuration File Basics” page.

Caching and Fallback

The control implements caching of the remote configuration file to minimize network traffic and performs fallback in case of errors during showing of ads or loading of settings. The important parts of this mechanism are as follow:

  • The remote settings file defined in SettingsUrl is only attempted to be fetched once per the lifetime of the application. If this is successful, the copy of this file is persisted in isolated storage.
  • If fetching of the remote settings file defined in SettingsUrl is unsuccessful, the last persisted settings file will be used from isolated storage.
  • If there has previously been no successful fetching of the remote settings file defined in SettingsUrl, the local settings file defined in the DefaultSettingsFileUri property will be used (if the property is assigned)
  • If loading of a particular ad type failed, that ad will not be loaded again through the lifetime of the application (that is if an ad was not filled, it will not be used again).
  • If no other ad can be loaded, the ad type defined in the DefaultAdType property of the control we be used. By default this property is set to None. Setting this property is strongly advised.