Using the AdMob Adobe AIR native extension for Android

With the AdMob Extension for Android from Milkman Games, you can rapidly integrate Google AdMob ads into your mobile AIR application using ActionScript 3.

The AdMob Extension for Android is a 100 percent native AdMob Java solution that enables you to:

• Monetize free games via Google AdMob
• 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
• Reposition ads automatically when your app changes orientation
• Support AdMob banner formats on both phones and tablets
• Register your test devices so you can develop without affecting your metrics
• Create, destroy, show, and hide ads with simple commands

This tutorial provides details on getting started with the AdMob Android extension. If you want to follow all the steps below, you'll need to purchase and download the AdMob Android extension.

The first step in using the AdMob Android extension is to add the com.milkmangames.nativeexetnsions.AdMob.ane library to your project. (If you are not using Flash Builder 4.6 and later or Flash Professional CS6 and later you'll need to add the AdMobAPI.swc library instead.)

In Flash Professional CS6:

1. Create a new project of the type AIR for Android.
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 and select the com.milkmangames.nativeextensions.AdMob.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.AdMob.ane file.

In FlashDevelop:

1. Copy the AdMobAPI.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 your code up and running with the AdMob extension with a few simple calls. See example/AdMobExample.as for a full example that shows how to handle errors, destroy and refresh ads, set ad visibility, and handle ad status changes.

Follow these steps to get started:

1. Import the API Classes:

2. Verify that AdMob is supported on your current platform, using the AdMob.isSupported property, and initialize the API with your AdMob publisher ID (you can retrieve your publisher ID from the AdMob web site control panel):

3. Show your first ad. The following call displays a banner ad, with bottom-left alignment:

4. To avoid making ad impressions while testing, you can set a list of testDevice IDs. You can retrieve the test ID for your device by running adb logcat (the command is android-sdk\platform-tools\adb logcat ) once while running the app. Look for the following line in the output:

Note: This is not the same as the Device ID. You'll need to run logcat at least this one time to find your ad test ID.

When you are done with testing, pass an empty testDevices Vector object or null instead.

5. To use absolute pixel positions for your ad you can supply x and y offsets as the fifth and sixth parameters to showAd() respectively. Note that the pixel offsets are relative to the true size of the screen (which you can read with stage.stageWidth and stage.stageHeight ) as the AdMob extension has no knowledge of any scaling being done by AIR (with the fullscreen property or otherwise). The following example shows an ad at the pixel position 20, 32 (relative to top left of the device):

Google has designed the AdMob API in such a way that the absolute physical pixel dimensions of the ads will vary based on the physical size of the device's screen. To precisely layout your application, you may need to know what dimensions the ad will have on the particular device. You can access these dimensions with the getPixelSize() function, which returns a Rectangle object that's width and height represent the real size in pixels, on the current phone or tablet, that an IAB_BANNER will display. For convenience, you can also read the .dimensions property of the AdMobAdEvent object to get this in an event listener function. You can use this information to accurately perform layouts based on the size of the ad. Here is an example function call:

Unfortunately, this means the size of the ad (in pixels) will vary based on the phone or tablet the ad runs on. However, the vast majority of Android devices will run in one of two modes that Google calls large and xlarge.

Almost all Android phones fall into the large category and will have banners that are 480 x 75 pixels. Almost all Android tablets and some of newer, larger Android phones are in the xlarge category and will have banners that are 640 x 100 pixels.

The large and xlarge dimensions are intended as guidelines; you should use the getPixelSize() method described above for accurately determining banner sizes on your own devices.

You need to configure your AIR application descriptor file to use the AIR 3.0 SDK (or later), include the AdMob extension, and update the Android manifest additions with some AdMob specific settings. For a working example, see example/app.xml.

1. Set your AIR SDK to 3.0 or later in the app descriptor file:

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

3. Update your Android manifest additions. The android.permission.INTERNET and android.permission.ACCESS_NETWORK_STATE permissions must be present for AdMob to work. You also must add the com.google.ads.AdActivity activity within the <application> element, as shown below:

If you're using Flash Builder 4.6 or later, or Flash Professional CS6 or later, and have added the AdMob Android extension library as described above, then you can compile as you usually do directly from the 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.AdMob.ane file.

Here is an example build command line:

If you're having trouble displaying ads, try these tips:

• Ensure that your publisher ID is correctly set via AdMob.init().
• Ensure you have ad inventory. You can guarantee an ad will display by setting your test Device's ID when you call showAd(). See example/AdMobExample.as for a sample of how to do this.
• Check for errors retrieving ads by listening for the FAILED_TO_RECEIVE_AD event:

• Execute android-sdk/platform-tools/adb logcat to review full debug text from the AdMob extension.
• Make sure you're handling all possible AdMobErrorEvent events. Uncaught errors may cause your code to halt.

Now that you have the AdMob Android extension up and running, you may want to explore the ActionScript 3 documentation or check out the other tools from available from Milkman Games.