Instructions for implementation of the Windows 8 version of AdRotator

For instructions to implement the Silverlight control click Here

For instructions to implement the XNA control click Here

Control Usage

*Note - In this initial phase we only support Local House Ads and AdDuplex, more will come shortly

Before starting you will need to install AdRotator from Nuget, just right click on the references folder in your solution in Visual Studio 2012 and select "Manage NuGet Packages" then search for "AdRotator" and you will find the Windows 8 version there.

*Note this is the only deployment method available for Windows 8 so you will find you will be doing this a lot more going forward.

**Note Don't forget to also download any ad provider packages you will need fro your solution through NuGet as well, like the AdDuplex Control

Create an instance of the AdRotatorControl:

 

<adRotator:AdRotatorControl x:Name="AdRotatorControl" Width="480" Height="80"
    SettingsUrl="http://mydomain.com/myAdSettings.xml" (...)/>

 

Then call the "Invalidate" function from your code behind, for best results we suggest doing this in the "Loaded" event handler.  If it doesn't exist already then hook up to it from either the XAML (XAML page header) or in the constructor for the page in the code behind, e.g.

 

void Page_Loaded(object sender, RoutedEventArgs e)
{
	AdRotatorWin8.Invalidate();
}

 

Important properties of the AdRotator control:

  • IsEnabled - setting this property to false will collapse the control
  • SettingsUrl - 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.
  • DefaultSettingsFileUri - 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.
  • PubCenterAdUnitId - ad unit ID to use the control with Microsoft PubCenter
  • PubCenterAppId - app ID to use the control with Microsoft PubCenter
  • AdDuplexAppId - app ID to use the control with AdDuplex
  • AdMobAdUnitId - app ID to use the app with AdMob
  • InneractiveAppId - app ID to use the control with Inner-Active
  • InneractiveExternalId, InneractiveGender, InneractiveAge, InneractiveKeywords, InneractiveReloadTime - optional Inner-Active specific configuration variables
  • MobFoxAppId - app ID to use the control with MobFox
  • SmaatoPublisherId and SmaatoAppId - Smaato specific configuration variables
  • SlidingAdDirectionSlidingAdDisplaySeconds and SlidingAdHiddenSeconds - set SlidingAdDirection to Left, Right, Bottom or Top to have the ad slide in, stay for SlidingAdDisplaySeconds, slide out and stay hidden for SlidingAdHiddenSeconds. If SlidingAdDirection is set to None (this is the default), this behaviour does not take place, the ad remains static.

The markup of an ad control that uses all ad providers would look like the following:

 

<adRotator:AdRotatorControl x:Name="AdRotatorControl" 
xmlns:adRotator="clr-namespace:AdRotator;assembly=AdRotator"
Width="480" Height="80"
    SettingsUrl="http://mydomain.com/myAdSettings.xml"
    DefaultAdType="None"
    DefaultSettingsFileUri="/AppAssemblyName;component/defaultAdSettings.xml"
    PubCenterAdUnitId="99999"
    PubCenterAppId="xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    AdDuplexAppId="9999"
    AdMobAdUnitId="xxxxxxxxxxxxxx"
    InneractiveAppId="xxxxxxxxxxxxxxxxxx"/>
    MobFoxAppId="xxxxxxxxxxxxxxxxxx"/>
    SmaatoPublisherId ="xxxxxxxxxxxxxxxxxx"/>
    SmaatoAppId="xxxxxxxxxxxxxxxxxx"/>
    SlidingAdDirection="Left"/>
    SlidingAdDisplaySeconds="10"/>
    SlidingAdHiddenSeconds="20"/>

 

Be sure to also call the "Invalidate" function of the AdControl to start the Ad gathering process.  We recommend you do this in the Page's "OnLoaded" event (in testing this was the best practice)

Default House AD functionality

In XAML we have now added the ability to use a custom Silverlight User Control for your own Default House AD.

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 Configuration File

*Note we are still testing remote config but it's on the way, for now Local config works fine

The structure of the remote configuration file is split up according to cultures and within each culture a set of ad provider probabilities are defined. The probability values are used for weighing: for easy overview it's encouraged that probabilities within an AdCultureDescriptor add up to 100, however this is not required.

An example ad descriptor that targets US, German and all other cultures looks as follows: (Sample XMLConfiguration file is also included with the release)

 

<?xml version="1.0" encoding="utf-8"?>
<AdSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<CultureDescriptors>
		<AdCultureDescriptor CultureName="en-US">
      <Probabilities Probability="15" AdType="InnerActive" AppID="<InnerActiveAPPID" />
      <Probabilities Probability="15" AdType="MobFox" AppID="<MobFox APP ID>" IsTest="false"/>
      <Probabilities Probability="40" AdType="PubCenter" AppID="<Pubcenter APP ID>" SecondaryID="<Pubcenter AD Unit ID>" />
      <Probabilities Probability="10" AdType="AdDuplex" AppID="<AdDuplex AD ID"/>
      <Probabilities Probability="10" AdType="DefaultHouseAd"/>
    </AdCultureDescriptor>
		<AdCultureDescriptor CultureName="en-GB">
      <Probabilities Probability="40" AdType="InnerActive" AppID="<InnerActiveAPPID" />
      <Probabilities Probability="40" AdType="MobFox" AppID="<MobFox APP ID>" IsTest="false"/>
      <Probabilities Probability="15" AdType="PubCenter" AppID="<Pubcenter APP ID>" SecondaryID="<Pubcenter AD Unit ID>" />
      <Probabilities Probability="5" AdType="AdDuplex" AppID="<AdDuplex AD ID"/>
      <Probabilities AdType="DefaultHouseAd"/>
    </AdCultureDescriptor>
		<AdCultureDescriptor CultureName="de-DE">
      <Probabilities Probability="20" AdType="InnerActive" AppID="<InnerActiveAPPID" />
      <Probabilities Probability="50" AdType="MobFox" AppID="<MobFox APP ID>" IsTest="false"/>
      <Probabilities Probability="5" AdType="PubCenter" AppID="<Pubcenter APP ID>" SecondaryID="<Pubcenter AD Unit ID>" />
      <Probabilities Probability="5" AdType="AdDuplex" AppID="<AdDuplex AD ID"/>
      <Probabilities Probability="20" AdType="DefaultHouseAd"/>
    </AdCultureDescriptor>
		<AdCultureDescriptor CultureName="default">
      <Probabilities Probability="25" AdType="InnerActive" AppID="<InnerActiveAPPID" />
      <Probabilities Probability="25" AdType="MobFox" AppID="<MobFox APP ID>" IsTest="false"/>
      <Probabilities Probability="25" AdType="PubCenter" AppID="<Pubcenter APP ID>" SecondaryID="<Pubcenter AD Unit ID>" />
      <Probabilities Probability="25" AdType="AdDuplex" AppID="<AdDuplex AD ID"/>
      <Probabilities AdType="DefaultHouseAd"/>
    </AdCultureDescriptor>
	</CultureDescriptors>
</AdSettings>

 

The valid values for certain node properties are as follow:

  • AdCultureDescriptor.CultureName: en-US, de-DE, en-GB, it-IT, es-ES, default (all values that Thread.CurrentThread.CurrentUICulture.Name can have along with the special, default string. Currently, pre-mango this means the previous 5 UI cultures)
  • Probabilities.AdType: PubCenter, AdMob, AdDuplex, InnerActive, None. (prohibited values are theAdRotator.AdType enumeration values. The values are case sensitive)
  • Probabilities.Probability: a double value. Probabilites within an AdCultureDescriptor group will be added together and weighed. So if there are two probabilites listed, one with the value of 30 and the other with 10, the ad type defined in the first one will appear three times the probability as the second one.

Note: The DefaultHouseAd Type can optionally have No probability configured (As shown above) in this case it will ONLY display when no network is available, if a probability is supplied then it will rotate the DefaultHouseAd in with the other ad's based on that probability.  This is purely optional and does not have to be added.

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.

Further Tutorials

Last edited Dec 27, 2012 at 6:26 PM by Darkside, version 7

Comments

No comments yet.