Using the iAd Adobe AIR native extension for iOS

With the iAd Extension for iOS from Milkman Games, you can rapidly integrate advertisements from the Apple iAd Network into your mobile AIR application using ActionScript 3.

The iAd Extension for iOS is a completely native iAd solution implemented to Apple specifications that enables you to:

• Monetize free games via Apple's iAd Network
• Display your first ad with just two lines of code
• Jumpstart development with a complete sample application, ActionScript 3 documentation, and a getting started guide
• Support iAd banner formats for iPad, iPhone, and iPod Touch
• Reposition ads automatically when your app changes orientation
• Create, destroy, show, and hide ads with simple commands
• Support lucrative interstitial ads on iPad

This tutorial provides details on getting started with the iAd Extension for iOS. If you want to follow all the steps below, you'll need to purchase and download the iAd Extension for iOS.

You'll need to set up iAd for your apps inside iTunes Connect before you can use the extension. Follow these steps:

1. Log into the Apple Developer center at http://developer.apple.com and go to the iOS Developer area.
2. Click iTunes Connect on the right.
3. Before you can use the iAd Network in your apps, you must read and agree to Apple's Developer Advertising Services Agreement. In iTunes Connect, click Contracts, Tax, and Banking and then click Request to the right of iAd Network (see Figure 1). Follow the on-screen instructions.

4. Click Manage Your Applications.

Note: If your app is already configured in iTunes Connect, select it and skip to step 13 below.

5. Click Add New App.

6. Select a default language and then type a Name and SKU Number for your application (see Figure 2). Under Bundle ID, click You Can Register A New Bundle ID Here, which will bring you to the Provisioning Portal.
7. In the Provisioning Portal, click New App ID (see Figure 3).

8. Type a description for your new app. For Bundle Identifier, type a unique name in the recommended scheme (like com.yourcompany.YourGameName).

Note: Take note of what you type here, as you'll need to match it exactly in your application descriptor file.

9. Click Submit and close the Provisioning Portal. Back on the App Information page, select the Bundle ID you just created. If you don't see your new Bundle ID listed, refresh the page or cancel the operation and click New App again.
10. Click Continue.
11. Continue through the next couple of steps, entering the release date, pricing tier, version information, rating information, metadata, icons, screenshots, and other required data for your application. If you're just creating a test app, you can set the release date far in the future. At least one screenshot and icon are required to register an application. If you need some dummy images to test with, you can find them in the /tutorialimages folder included with the iAd Native Extension zip package from Milkman Games.
12. Click Save.
13. On the iTunes Connect screen for your app, click Set Up iAd Network.
14. Click Enable iAds and select a primary target audience (see Figure 4).

15. Click Save.

You're now ready to start building an iAd enabled AIR application.

The next step is to add the com.milkmangames.nativeextensions.IAd.ane library to your project. (If you are not using Flash Builder 4.6 and later or Flash Professional CS6 and later you will need to add the IadAPI.swc library instead.)

These files can be found in the /extension folder of the extension package zip file.

In Flash Professional CS6:

1. Create a new project of the type AIR for iOS.
2. Choose File > Publish Settings.
3. Click the wrench icon next to Script for ActionScript Settings.
4. Select the Library Path tab.
5. Click Browse for Native Extension (ANE) File select the com.milkmangames.nativeextensions.IAd.ane file.

In Flash Builder 4.6:

1. Go to Project Properties (right-click your project in Package Explorer and select Properties).
2. Select ActionScript Build Path and click the Native Extensions tab.
3. Click Add ANE and navigate to the com.milkmangames.nativeextensions.IAd.ane file.

In FlashDevelop:

1. Copy the IAdAPI.swc file to your project folder.
2. In the explorer panel, right-click the SWC and select Add To Library.
3. Right-click the SWC file in the explorer panel again, select Options, and then select External Library.

You can get the iAd Extension for iOS up and running with a few simple calls. See example/IAdExample.as for a full example that shows how to create and destroy ads, set visibility, handle errors, and more.

1. Start by importing the API Classes:

2. Next, initialize the API and create an instance of the IAd object:

3. Check if the device will support iAd ads. Although AIR apps will run on iOS 4.0 and later, iAd support is only available in iOS 4.2 or later.

4. Create a Banner Ad container, and listen for the appropriate events. You should listen for all the relevant error events listed below, to be sure all error events are caught. After the call to createBannerAd(), the extension will automatically handle the lifecycle of banner ads. Specifically, it will automatically try to get a new ad after one fails to load, automatically show a new ad when one is ready, and automatically hide the ad view when there's a problem—all in accordance with Apple requirements.

The following example code creates a banner ad container at the top of the screen that can show either portrait or landscape content.

5. When a user clicks on one of the banner ads in your application, either they will be taken out of your application to the App Store or Safari, or they will be shown a full screen pop-up ad. In the case of a pop-up ad, you'll want to stop sounds in your application and pause any major actions. You can tell whether the user is going to be viewing a pop-up or leaving the application by the event's willLeaveApplication property:

6. When the user is done with the ad, they may be returned to your application. If you had paused actions and sounds in the previous event, you'll want to resume them when the interaction is over:

7. You may want to hide or show an ad area based on the application state. For instance, you might want to show ads most of the time, but hide them when the user is viewing a special menu (and then show them again later). This is easily done with the setBannerVisibility() method. The first parameter, visibility , shows the ad when true and hides it when false . When the second parameter, withAnimation , is true the ad will slide on to and off of the screen with an animated effect.

In addition to banner ads, you may be able to show a special type of ad known as an interstitial ad. These ads only work on iPads running iOS Version 4.3 or later.

Interstitial ads take up the full screen until the user is done with them. As a result, they are typically more lucrative than banner ads. Interstitial ads are most often used between two parts of your app; for instance, an interstitial ad may be shown after one game finishes, before the user can play another game.

Follow these steps to display an interstitial ad:

1. First make sure you're listening for the interstitial ad events, and then call showInterstitial().

2. If the iAd object succeeds in loading an interstitial ad, it will trigger the IAdEvent.INTERSTITIAL_AD_LOADED event. The iPad's screen will now be covered completely by the ad, and the app should stop any sounds until the ad is done. If there's an error and the iAd object can't get an interstitial ad, it will trigger IAdErrorEvent.INTERSTITIAL_AD_FAILED. Finally, the IAdEvent.INTERSTITIAL_AD_UNLOADED event will fire when the ad is being removed from the screen; at that point the app can resume its normal operation.

For complete examples of all available methods for interstitial ads, see the IAdExample.as file in the /example folder.

In your application descriptor XML file you need to specify the version of the AIR SDK you are using (3.1 or later) as well as a link to the extension. For a working example, see example/app.xml.

1. If it is not already set, set your AIR SDK version in the application descriptor file (use 3.2 below if you are using that version of the SDK):

2. Include a link to the extension in the descriptor:

If you're using Flash Builder 4.6 or later (or /Flash Professional CS6 or later), and have added the iAd extension library as described above, then you can compile as you usually do directly from your IDE. If not and you are building your app with the extension from the command line, then you'll need to specify the directory containing the com.milkmangames.nativeextensions.IAd.ane file.

Here is an example build command line:

When you're building a version of your app for testing be sure you use the development version of the .mobileprovision file

You can and should use the distribution version of the .mobileprovision file when building the release version of your app to upload to the App Store.

Use the tips below to troubleshoot any problems you may be having with the iAd Extension for iOS:

• If the Enable Ads Button is not present in iTunes Connect, make sure you've agreed to Apple's iAd contract in the Contracts section.
• If you're adding iAd support to an already published game, you need to create a new version, and enable iAd on that new version. Make sure you update the version number appropriately in the new version's application descriptor file.
• If the test ad starts in portrait mode, even though your app is in landscape mode, that's not unusual for a test ad on some devices. In production, the appropriate ads will always be shown, as long as you've set the correct IAdContentSize settings when calling createBannerAd().

Now that you have the iAd Extension for iOS up and running, you may want to explore the ActionScript 3 documentation or check out the other tools from available from Milkman Games.