Its taken a few weeks and loads of chasing people up and tests but we finally got our unified ad engine integrated into IwGame. And to celebrate that event we are releasing the code as open source. You can download the latest version of IwGame Engine from here

Here are the latest changes to IwGame:

• Bug fix – Headers are now applied to CIwGameHttp GET requests
• Added CIwGameHttpManager::DetermineUserAgent() to build a browser compatible user-agent
• Added CIwGameHttpManager::DetermineIPAddress() to determine the users IP address. Please change PING_DOMAIN to your own domain!
• Added CIwGameString::Replace(char chr, char with) char string replacment method
• Added CIwGameString::Contains(char chr) to check if a string contains a particular char
• Added CIwGameString::URLEncode(const char* str) to url encode an ascii string
• Added CIwGameUtils::GetGraphicModeName(int width, int height) returns VGA style naming graphics mode
• Added CIwGameAd – Main ad request class which requests and retrievs ads from a variety of ad providers (Inner-active and Adfonic are supported at the moment)
• Added CIwGameAdView – Requests ads at set intervals and displays them using animations, can cache ads
• Added CIwGameAdsViewAnimator, a basic example animator that can be used to animate ads in a CIwGameAdsView

As well as the ad request and ad view classes you will notice a few other neat additions that may prove useful such as DetermineIPAddress() and DetermineUserAgent(). DetermineUserAgent returns the IP of the device that your app is running on whilst builds a browser compatible user-agent string for all supported Marmalade platforms. Yes, I know the user-agent is fudged bit it seems to work well and its a lot more compatible with other web API’s than the default s3e user-agent header.

We decided to separate the ad request class CIwGameAds from the actual ad renderer CIwGameAdsView to enable developers to simply use one without the other, so if you just want the ability to put in an ad request feel free to just roll with CIwGameAds. if on the other hand you want the complete package that requests ads at a regular interval, displays them and handles clicks then go with CIwGameAdsView.

We have provided an example with the test bed this update that shows you how to initialise, update and shut down ads (see main.cpp). Lets take a quick look at the code that has been added:

Application ID

All ad networks need some way to identify you and your app as the originator of the ad and click requests, without them you wouldn’t get paid, so ensure that you sign up with any ad network that you are planning on usng and get your Application ID. Each ad p[rovider may call the application ID something different, such as site ID or vendor ID etc.. No matter what they call it, we call it the Application ID and it must be supplied to IW_GAME_ADS_VIEW->Init(Application_ID_String);. Note that the current example will show House Ads from inner-active even with no Application ID (this is just to show you it working).

Note that you can change your Application ID in-between requests as well as which provider you are using, this is a good way to ensure that you get a close to a 100% fill rate maximising your revenue; if one ad provider does not return an ad then request one from the next ad provider. We will add support to automate this at a later date.

Whats Changed in Our Code

Firstly we added the following headers:

#include “IwGameAdsView.h”
#include “IwGameAdsViewAnimator.h”

Then we added an initialisation function to initialise the ads system:

void AdTest_Init()
{
	int width = IwGxGetScreenWidth();
	int height = IwGxGetScreenHeight();

	// Create ad view
	CIwGameAdsView::Create();

	// Initialise with Application ID (you get this from your ad provider)
	IW_GAME_ADS_VIEW->Init("");

	// Set ad provider
	IW_GAME_ADS_VIEW->setAdProvider(CIwGameAds::InnerActive);

	// Set ad request interval in seconds
	IW_GAME_ADS_VIEW->setNewAdInterval(30);

	// Force a request for an initial ad
	IW_GAME_ADS_VIEW->RequestNewAd(CIwGameAds::InnerActive);

	// Set total number of ads visible in the ads view
	IW_GAME_ADS_VIEW->setNumAdsVisible(1);

	// Tell animators to loop
	IW_GAME_ADS_VIEW->setLooped(true);

	// Create and attach an animator that fades the ad in over 1 second, pauses for 7 seconds and then fades the ad back out
	CIwGameAdsViewAnimator* anim = new CIwGameAdsViewAnimator();
	anim->Init();
	anim->setAdViewDataIndex(0);
	anim->setCanvasSize(width, height);
	anim->setInAnim(CIwGameAdsViewAnimator::AnimFadeIn, 1000);
	anim->setOutAnim(CIwGameAdsViewAnimator::AnimFadeOut, 1000);
	anim->setStayDuration(7000);
	IW_GAME_ADS_VIEW->addAnimator(0, anim);

	// Create and attach an animator that sweeps the ad in from the right the over 1,2 seconds, pauses for 7 seconds and then sweeps back out
	anim = new CIwGameAdsViewAnimator();
	anim->Init();
	anim->setAdViewDataIndex(0);
	anim->setCanvasSize(width, height);
	anim->setRestingPosition(0, -height / 8);
	anim->setInAnim(CIwGameAdsViewAnimator::AnimRightSweepIn, 1200);
	anim->setOutAnim(CIwGameAdsViewAnimator::AnimRightSweepOut, 1200);
	anim->setStayDuration(7000);
	IW_GAME_ADS_VIEW->addAnimator(0, anim);

	// Create and attach an animator that scales the ad in over 1.5 seconds, pauses for 7 seconds and then scales back out
	anim = new CIwGameAdsViewAnimator();
	anim->Init();
	anim->setAdViewDataIndex(0);
	anim->setCanvasSize(width, height);
	anim->setInAnim(CIwGameAdsViewAnimator::AnimScaleIn, 1500);
	anim->setOutAnim(CIwGameAdsViewAnimator::AnimScaleOut, 1500);
	anim->setStayDuration(7000);
	IW_GAME_ADS_VIEW->addAnimator(0, anim);

	// Create and attach an animator that rotates the ad in over 1 second, pauses for 7 seconds and then rotates back out
	anim = new CIwGameAdsViewAnimator();
	anim->Init();
	anim->setAdViewDataIndex(0);
	anim->setCanvasSize(width, height);
	anim->setInAnim(CIwGameAdsViewAnimator::AnimSpinIn, 1000);
	anim->setOutAnim(CIwGameAdsViewAnimator::AnimSpinOut, 1000);
	anim->setStayDuration(7000);
	IW_GAME_ADS_VIEW->addAnimator(0, anim);
}

Don’t be alarmed and think OMG this is much harder than using AdMobs or iAds, most of this code is simply for setting up animations. In fact, yuo can just strip out the animation code (marked in orange) and remove it, the adw ill simply sit in the middle of the screen quite motionless.

Now lets take a look at how we update the ad system:

void AdTest_Update()
{
	// Update the ads view
	IW_GAME_ADS_VIEW->Update(GAME->getCurrentScene(), 1.0f);
	// Draw the ads view
	IW_GAME_ADS_VIEW->Draw(GAME->getCurrentScene());
}

Nice and super simple. if you are wondering, the underlying rendering is taken care of by Iw2D.

And finally our Ad clean up code:

void AdTest_Release()
{
IW_GAME_ADS_VIEW->Release();
CIwGameAdsView::Destroy();
}

All nice and easy stuff. Now you can run ads across all Marmalade SDK platforms, depending on the Ad Providers support for those platforms. Thus far we have tested on iOS, Android, Blackberry Playbook and Bada and ads are delivered and clicks registered.

Hiding and Showing Ads

If you are using CIwGameAdsView to display  ads then you can call IW_GAME_ADS_VIEW->setVisible(ad_visibility) to change ad visibility. Note that, if you make the ads view invisible then it will stop requesting and updating ads.

Displaying Multiple Ads

CIwGameAdsView currently supports display of multiple cached ads simultaneously. To enable this feature simply call IW_GAME_ADS_VIEW->setNumAdsVisible(ad_count); This will tell ads view to draw the last ad_count ads that have not expired. You will need to set the screen positions, scales, rotations etc for each separate ad unit by calling setPosition(), setScale(), setAngle() etc methods of CIwGameAdsView. The first parameter is the index of the ad slot you want to change. You cam do this manually or attach animators.

Which Ad Providers Are Supported?

We’ve spent most of the last few weeks trying to integrate with ad providers network API’s, which is made more difficult than it should be because some providers are a bit lax and even unhelpful when it comes to providing integration support, some have been pretty good though, especially Inner-Active, they are very on-the-ball.

We went ahead and left all of the code in there for all providers that we have attempted to integrate this far in case any of you want to pick up on where we left off.

The current list of providers we have attempted integration with includes:

• Inner-Active – Works incredibly well across all platforms
• AdFonic – Works, now has full support for carrier and WiFi
• MobFox – Ads wont deliver over WiFi or carrier, trying to fix
• InMobi – Ads wont deliver over WiFi or carrier, trying to fix
• Madvertise – Registering impressions but never returns any ads
• Mojiva – Awaiting app approval before we can test, so potentially works

We plan to ad support for most of the other major Ad players, once we find details of the REST based API’s

What Information Do I Need to Supply?

You should provide at least the following minimum information to the CIwGameAds class before requesting ads:

• Application ID

If you want more targeted ads then you can also supply other information such as:

• Users Age
• Users Gender
• Users Location
• Application Category
• Users Mobile Number
• Keywords associated with the user

Note that not all ad providers will use all of the above.