Instructions for implementation of the XNA version of AdRotator

For instructions to implement the Silverlight control click Here

For instructions to implement the Windows 8 control click Here

Control Usage

First create a reference to the AdRotator XNA control in your project and ensure that you also ensure you add any references to other Ad Providers DLL's that you intend to use (you don't have to actually use them but if you enable them remotely they must already be present)

Create an instance of the AdRotatorControl add the following in the Initialize function of your game:

 

protected override void Initialize()
{

	//Initialise the XNA AdRotator Component
	AdRotatorXNAComponent.Initialize(this);

	//Add the control to the XNA Component list which will display the ad
	//Note as this is XNA be sure to just to this for the game states you want it shown.
	Components.Add(AdRotatorXNAComponent.Current);

	base.Initialize();
}

 

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.
  • AdPosition - Position on the screen where the Ad will be displayed/Drawn to
  • DefaultHouseAdImage - Texture2D image to be displayed for the Default House Ad (optional)
  • DefaultHouseAdClick - Listener event for when the user clicks on the Default House Ad (optional)

Configuring of the AdControl should be between initialise and Adding the component to the game as follows:

 

protected override void Initialize()
{
	// TODO: Add your initialization logic here

	//Initialise the XNA AdRotator Component
	AdRotatorXNAComponent.Initialize(this);

	//Specify where you want the Ad to display (based on the top left corner of the Ad)
	AdRotatorXNAComponent.Current.AdPosition = Vector2.Zero;

	//Optionally specify your own House Ad which will display if there is no network
	AdRotatorXNAComponent.Current.DefaultHouseAdImage = Content.Load<Texture2D>(@"AdRotatorDefaultAdImage");

	//Event handler to do something should the user click on your Default House Ad
	AdRotatorXNAComponent.Current.DefaultHouseAdClick += new AdRotatorXNAComponent.DefaultHouseAdClickEventHandler(Current_DefaultHouseAdClick);

	//Optionally specify the slide (popup) direction for the Ad
	AdRotatorXNAComponent.Current.SlidingAdDirection = SlideDirection.Right;

	//Optionally Set the local configuration file used to set the default Ad Locations
	AdRotatorXNAComponent.Current.DefaultSettingsFileUri = "defaultAdSettings.xml";

	//Optionally set a URL from where to pull the configuration file down remotely each time the game is run
	AdRotatorXNAComponent.Current.SettingsUrl = "http://mysite.com/defaultAdSettings.xml";

	//Add the control to the XNA Component list which will display the ad
	//Note as this is XNA be sure to just to this for the game states you want it shown.
	Components.Add(AdRotatorXNAComponent.Current);

	base.Initialize();
}

 

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 configuration files are shipped as part of 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 AppID="<Remote URL of house Ad Image>"/>
    </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.

Also we have now added the capability to specify a remote URL for your House Ad Image, when provided AdRotator will attempt to download the image and use it as your house ad texture, this will also be stored locally in case network connectivity is unavailable later.  We recommend you also provide a default House Ad texture in your app as above in case the app is started without connectivity as this will be the fall-back.  This is also optional and you can still use House Ads with just an image deployed with your app if you wish.  (We also recommend you test any images prior to replacing your remote image to ensure it will successfully display on the phone and keep the size of the image low as to not overly stress mobile connections)

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 4, 2012 at 4:23 PM by Darkside, version 7

Comments

cdxrd Jun 15, 2013 at 12:31 AM 
Any samples / builds / etc for using Ad Rotator with Monogame for windows 8 store apps ?