Instructions for implementation of the Silverlight version of AdRotator

For instructions to implement the XNA control click Here

For instructions to implement the Windows 8 control click Here

Control Usage

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"/>

Default House AD functionality

In Silverlight 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 Remote Configuration File

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 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="70" 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 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 the AdRotator.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:25 PM by Darkside, version 25

Comments

kumaran52v Sep 22 at 6:22 PM 
Is it possible to keep the remote settings in Onedrive as a public file?

ahumeniy Feb 13 at 11:35 AM 
Is it necessary to put the ad networks ID on the config file if they're already on the adrotator control properties?

atkulp Jan 24 at 10:55 PM 
Is there a way to pass location to AdRotator for it to pass on to those providers that support it? If not, this would be a very useful feature!

arulk Jan 8 at 3:35 AM 
I installed this control from nuget. AdMobAdUnitID doesn't show up in the control intellisense. Does nuget have latest version of this control ?

tutorle Aug 1, 2012 at 2:35 PM 
Is it possible to setup AdRotator to show 2 different PubCenter's ad units (eg. 70% – one, 30% – another).

dgdelage Jun 11, 2012 at 5:49 AM 
The "Default House AD functionality" section above says to create a custom user control with a size of 480x100, yet the standard ad size is 480x80. Is there a specific reason for the extra 20 pixels of height?

joeymk Apr 30, 2012 at 2:10 PM 
Any video tutorial? Would be great ...

gergelyorosz Jun 19, 2011 at 11:05 PM 
@toddmain: no, there's no such culture as en-UK! Thanks for noticing, I've corrected it.

toddmain Jun 17, 2011 at 6:25 PM 
in your solution example you have "<AdCultureDescriptor CultureName="en-GB">", but above in "AdCultureDescriptor.CultureName" you list "en-UK". Are both valid for the same thing, i.e. interchangable?