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
- SlidingAdDirection, SlidingAdDisplaySeconds
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