Introduction to iAd in Flash AIR for iOS – Kick Start Tutorial & Samples

Sourcefiles for the tutorials are here.

SUMMARY

It can be very confusing to know where to start when you want to add advertisements in your Flash/AIR based iOS app. Google search results can be ambiguous at best, and there are a number of free solutions out there, but little or no support. The most recommended pay for solution is Milkman Games’s iAd for iOS Extension. There are also a number of others (like Smaato For Android and iOS ) for pay, but I’m a firm believer in that “if they do it, I should be able to do it too”.
…I’d like to make my own ANE someday. That would be so awesome.

Once you find a service you will quickly figure out that relying on one ad network (like iAd) isn’t enough. iAd only shows ads in specific countries, for example.
If you plan to use the “pay to remove ads” feature, you will need to use more than one ad network. If you don’t, some people will essentially get the game/app for free.
To avoid this you would need to use a number of other services. If one fails then fall back on the other — like Tapjoy, Placeplay, Admob, RevMob. Most of them provide their own AIR SDKs. Then you would have to write your own ad mediation (if iAd fails, show from other service, if that fails, show the other, if that fails have a final fallback showing something that promotes your work — a “house ad”…), etc. Some SDK’s will do this for you (like adwhirl) — specify/linkup your network (links bellow, see More iAd ane’s (SDKs, etc)).
From what I have heard (but can’t stand by because I haven’t tried it) displaying ads are not the best way to generate revenue (don’t base a business model on it because of those overnight success stories!). It takes a lot more effort than that.

My goal for this post is to save people time, hassle, and hopefully money, by offering sourcecode samples, and a compilation of links all in one convenient place. I will continue to build on, and update, this post as I find more.

RESOURCES

Documentation:
Adobe’s docs for All Packages: http://www.adobe.com/devnet-docs/gamingsdk/anedocs/

StageAd docs: http://www.adobe.com/devnet-docs/gamingsdk/anedocs/com/adobe/ane/stageAd/package-detail.html

Adobe Gaming SDK support forum: http://forums.adobe.com/community/game_developers/adobe_gaming_sdk –If you have an issue, this is where you would search for answers (not always on Google).

Getting started with Adobe Game Developer Tools

It is also a good idea to browse through Apple’s iAd Programming Guide: HERE.
From what I heard (and know from their process) they have some fairly strict requirements for how you are allowed to display Ads. For example their fullscreen ads section: HERE.
This will make your app less likely to be rejected for “overlooked” reasons…

More Air Native Extensions:
http://www.as3gamegears.com/category/air-native-extension/ This is one of the best places that rounds up resources for AS3. In this case it’s a great collection for any App developer. Like CameraRoll, iAd, Ad Network, etc… It’s a very exciting summary to get you started, and will save you time.

Adobe AIR Native Extensions round-up: HERE, has some more good links to other iAd solutions.

More iAd ane’s (SDKs, etc):
adwhirl-flash-sdk (An unofficial port of the Adwhirl Client SDK to Actionscript 3. Usage HERE (see first post). Source here: HERE.)

iad-ane-for-flash-air-mobile-ios (A free actionscript native extension for iAd, for Flash AIR for iOS applications. Android is not supported. This air ane supports all native function, including all size type banners, interstitial, and events…)

adoble-flash-air-ad-network-framework (adwhirl for actionscript. Like adwhirl, but simpler, and no need for a server. Add a variety of ad networks advertising in mobile applications. Comes with support for admob (ios, android), inmobi (ios, android), chartboost (ios, android), iad (ios) 4 ad platforms…

adwhirl (Use the AdWhirl technology to display ads from different ad networks in your Android and iPhone applications. Switch ad networks on the fly, all for free. With the source code available, you can see how it all works. )

Smaato ANE (Not free. The iOS version can be configured to show Apple iAd. If iAd fails and can’t be fetched then a iSmaato banner is displayed.)

Keep These Tutorials At Hand:
Using the Game Center Adobe AIR native extensions for iOS: http://www.adobe.com/devnet/air/articles/gamecenter-ane-ios.html

Getting StageAd:

You may download all the SDK’s, ane’s, libraries, etc. from Adobe Gaming’s (very impressive & helpful) Adobe Gaming SDK: http://gaming.adobe.com/technologies/gamingsdk/

Once you do this you need StageAd.ane
It should be provided in the “Native Extensions (ANEs)” folder of Adobe Gaming SDK.
Docs are also provided in the “Docs” folder. In this case Native Extensions (ANEs)>Docs>com>adobe>ane>stageAd

Working examples are in Samples>Native Extensions (ANEs)>StageAd>src

TUTORIAL

stageAd EXAMPLE
Getting StageAd Running In Flash CS6, Flash CC

Start a new AIR for iOS project.

Open the Edit ActionScript settings window. Click on the Wrench icon next to the ActionScript tab in the Properties panel.

Go to the Library path tab.

Select Add New Path.

Then Browse to a Native Extension (ANE) file.

Navigate to the StageAd.ane

And hit OK.
That’s the setup…

Code:

Again, stageAd docs are here.
The samples given by Adobe in Samples>Native Extensions (ANEs)>StageAd>src are more elaborate. This is a very simplified example/walkthrough.

Following is for a simple banner positioned bottom or top of the screen.

import com.adobe.ane.stageAd.*;

//create an instance of a normal banner ad
var ad:StageBannerAd;

//HANDLERS

function onActionCompleteHandler(event:StageAdEvent)
{

	trace("Action complete handler properties:bubbles-" + event.bubbles + "cancelable:" + event.cancelable + "target:" + event.target + "type:" + event.type + "leaveApplication" + event.willLeaveApplication);

}


function onAdLoadCompleteHandler(event:StageAdEvent)
{

	trace("AD load handler properties:bubbles-" + event.bubbles + "cancelable:" + event.cancelable + "target:" + event.target + "type:" + event.type + "leaveApplication" + event.willLeaveApplication);

}

function onActionStartingHandler(event:StageAdEvent)
{
	trace("Action starting handler properties:bubbles-" + event.bubbles + "cancelable:" + event.cancelable + "target:" + event.target + "type:" + event.type + "leaveApplication" + event.willLeaveApplication);

}

function onAdLoadFailHandler(event:StageAdEvent)
{
	trace("ADLoadfail handler properties:bubbles-" + event.bubbles + "cancelable:" + event.cancelable + "target:" + event.target + "type:" + event.type + "leaveApplication" + event.willLeaveApplication);

}

function onAdUnloadHandler(event:StageAdEvent)
{
	trace("AdUnload handler properties:bubbles-" + event.bubbles + "cancelable:" + event.cancelable + "target:" + event.target + "type:" + event.type + "leaveApplication" + event.willLeaveApplication);
}

//Normal advertisements
if (StageBannerAd.isSupported)
{

	ad = new StageBannerAd();
	//if set to true the ad will only display once loaded
	ad.showOnlyIfLoaded = false;
	//set the stage
	ad.stage = this.stage;

	ad.addEventListener(StageAdEvent.AD_ACTION_COMPLETE,onActionCompleteHandler);
	ad.addEventListener(StageAdEvent.AD_ACTION_START,onActionStartingHandler);
	ad.addEventListener(StageAdEvent.AD_LOAD_COMPLETE,onAdLoadCompleteHandler);
	ad.addEventListener(StageAdEvent.AD_LOAD_FAIL,onAdLoadFailHandler);
	ad.addEventListener(StageAdEvent.AD_UNLOAD,onAdUnloadHandler);

	//placement - default is bottom
	//ad.align = StageAdAlign.BOTTOM;
	//ad.align = StageAdAlign.TOP;

	//to unload set it to null
	//ad instance gets disposed once ad gets loaded on the screen and cancelled by the user
	//ad.stage = null;

	trace("iad init");

}
else
{

	trace("StageBannerAd.isSupported=false");


}

To remove an ad set the instance to null: ad.stage = null;
From what I read, you do not need to remove listeners. It gets fully disposed of once it is cancelled by the user (SOURCE).

Alternatively, this is a fullscreen ad:
It’s basically the same except you create a: var fullscreenAd:StageFullscreenAd;
And check for:

var fullscreenAd:StageFullscreenAd;

//Fullscreen advertisements from the iAd network (fullscreen ads are supported on iPad devices only). 
//https://developer.apple.com/library/ios/documentation/userexperience/conceptual/iAd_Guide/Full-ScreenAdvertisements/Full-ScreenAdvertisements.html
//Fullscreen
if (StageFullscreenAd.isSupported)
{
	//
	fullscreenAd=new StageFullscreenAd();
	fullscreenAd.addToStage();
	//
	fullscreenAd.addEventListener(StageAdEvent.AD_ACTION_COMPLETE,onActionCompleteHandler);
	fullscreenAd.addEventListener(StageAdEvent.AD_ACTION_START,onActionStartingHandler);
	fullscreenAd.addEventListener(StageAdEvent.AD_LOAD_COMPLETE,onAdLoadCompleteHandler);
	fullscreenAd.addEventListener(StageAdEvent.AD_LOAD_FAIL,onAdLoadFailHandler);
	fullscreenAd.addEventListener(StageAdEvent.AD_UNLOAD,onAdUnloadHandler);
	//
}
else
{
	trace("stageFullscreenAd.isSupported=false");
}

Note that fullscreen ads are only supported on iPad.

If it’s working you will see a fake “welcome” ad by Apple.

And that’s stageAd.
Sourcefiles here: http://nathalielawhead.com/sourcefiles/StageAd_iAd_WorkingExample/

iAd EXAMPLE

iAd is another one. It’s free. So here it is…
Link: http://code.google.com/p/iad-ane-for-flash-air-mobile-ios/
ANE here: http://code.google.com/p/iad-ane-for-flash-air-mobile-ios/source/browse/#svn%2Ftrunk%2Fane
Download Source Here: http://nathalielawhead.com/sourcefiles/StageAd_iAd_WorkingExample/iad-ane_Example/

Start a new AIR for iOS project.
Browse to the ANE, as described above.

Code:

import so.cuo.platform.iad.*;

if (IAd.getInstance().supportDevice)
{
	IAd.getInstance().showBanner(IAd.BANNER,IAdPosition.BOTTOM_CENTER);
}

// Check ane support. Apple does not provide Interstitial ad on iphone.;
if (IAd.getInstance().supportDevice && IAd.getInstance().supportedInterstitial)
{
	IAd.getInstance().addEventListener(IAdEvent.onInterstitialReceive,onAdReceived);
	IAd.getInstance().cacheInterstitial();
}

function onAdReceived(event:IAdEvent)
{
	if (event.type == IAdEvent.onInterstitialReceive)
	{
		IAd.getInstance().showInterstitial();
	}
}

Download Source Here: http://nathalielawhead.com/sourcefiles/StageAd_iAd_WorkingExample/iad-ane_Example/

CONCLUSION

I wrote this walkthrough to help people starting out. I will be building on it as I find more information, and adding more examples. Perhaps this will grow into a reliable reference as things unfold.
Hope this helps, good luck!

If you found this helpful maybe you will enjoy Making an App: Adobe AIR for iOS – Flash to iOS Walkthrough. It will guide you through the setup, and development process of an AIR app (as well as getting started with Apple Developer, certificates, etc)…