The Amazon Mobile Ads API allows you to monetize apps and games across the Android, Fire OS, and iOS platforms by displaying ads to customers in the US, UK, France, Italy, Spain, and Germany. Ads can be banner or interstitial and will advertise products or services coming from Amazon or other well-known brands. You are paid on ad impressions served whilst some other Ad networks only pay on clicks. To get more information on the benefits of using the Amazon Mobile Ad Network, check out the Success Stories.

This blog is about how you get started with using the Amazon Mobile Ads API in your Android Java based app or game that is running on an Android device, Amazon Fire OS tablet or phone device.

How Do I get Access to the APIs?

The Amazon Mobile Ads API is part of a single SDK (the Amazon Mobile App SDK, which you can download here) that also provides access to other Amazon mobile services and APIs such as GameCircle and In-App Purchasing.  The same download also includes the necessary files to use the Amazon Mobile Ads API in apps developed for iOS.

You can use the Android Java version of the Mobile Ads API in projects that have been created in Eclipse or Android Studio. First, download the SDK and extract the zip file to the appropriate location on your development machine. Here’s what the SDK folder looks like on my machine…

Obtain an Application Key

Before you can use the Amazon Mobile Ads API in an app, you should create an Application Key that is unique to the application. This key is used by the Amazon framework to identify your app so it’s essential that you use the correct one so that you will be paid.

To create a new key you need an Amazon Apps & Games Developer Portal account. If you don’t have one, you can create a free account by clicking here. Also note, because you will be receiving income into the account, you will need to add your payment and tax information details to your developer account profile.

You can bypass this step for now if you want to just try out the API using one of the sample apps. Just make sure you create your own key (and account) later.

Check out the Samples First

Before you start including the Amazon Mobile Ads API in your project, I recommend that you first build and play with the three samples that come with the SDK. You can find these samples in the /Android/Ads/Samples folder and they are as follows:

Building the Samples in Eclipse

To build the samples in Eclipse is pretty straightforward. Once you have imported the projects, you just need to add the mobile ads JAR file library to your project and ensure that the library file is included in the build process.  There are some good instructions in this Quick Start Guide about how to do this but do note that you need to check the JAR library file in the “Order and Export tab” so that it is included in the build. The screenshot below shows how to do this:

This step is quite easy to miss and unfortunately, if you don’t complete the step, the project will still build successfully but you will get runtime errors saying that methods in the API cannot be found!

Building the Samples in Android Studio

The Mobile Ads API samples were created using Eclipse but you can also use the samples in Android Studio very easily. As this is currently not described in the Quick Start Guide I’ve written some instructions below on how to do this…

1. Run Android Studio and from the Quick Start pane select “Import Non-Android Studio project”. An import wizard begins
2. Locate the Eclipse project folder for the desired sample and click “OK”

1. In the “Import Project from ADT” dialog, first choose a destination directory for the Android Studio version of the project and click “Next”

1. Various import options will appear in the same dialog – just click “Finish” to start the import

1. Once the import has completed, the project will open in Android Studio
2. To add the Amazon Mobile Ads API library file to the project, first create a folder called “libs” under the “app” folder in your project. Use OSX Finder or Windows Explorer (as applicable) to do this
3. Next, find the file “amazon-ads-x.y.z.jar” which located in the “/ads/lib” folder within the Amazon SDK folder and copy it to your new “/app/libs” folder
4. In Android studio, refresh the project view so that the libs folder appears

1. Right click the .jar so that you see the context menu as shown below. Select “Add as library”

1.  Click “OK” in the “Create Library” dialog that appears

1. At this stage the library will have been added and you should see the following newly added lines in the build.gradle file under your ‘app’ folder:

dependencies {

    compile files('libs/amazon-ads-x.y.z.jar')

}

Where: x, y and z will be substituted with the actual version numbers

Running the Samples

Once you have added the library file to a sample project, you should be able to build the code and try it out on a device. In the SimpleAdSample project, for example, you should see something similar to this when it runs:

Including the APIs into Your Own Code

Using the Amazon Mobile Ads APIs in your own code is relatively straightforward and this Quick Start Guide goes through the steps that you need to follow. There are, however, a few things that are worth delving into a little deeper which I discuss below.

Additional Permissions

To use the APIs, you need to add a least one permission to the project’s manifest file. You have to add the permission android.permission.INTERNET as this enables the app to communicate with the ad server. Additionally, it is advisable to add the other permissions suggested in the Quick Start Guide as doing so will give the ad framework a better chance of delivering ads that are more relevant to the user - see also section “Loading the ad” below.

Loading the Ad

There are two main ways in which you can request an ad. The simplest way is just to call the version of the Ad object’s loadAd() method that takes no parameters. However, the problem with this approach is that you will get ads delivered to your app that might not be applicable to your user’s geographical location. A better approach is to use a different version of the same API that takes some parameters…

 final AdTargetingOptions adOptions = new AdTargetingOptions();       

 adOptions.enableGeoLocation(true);

 this.adView.loadAd(adOptions);

In the snippet above, the code uses the Mobile Ads API to send the position of the device to the Amazon Mobile Ad Network so that potentially more targeted ads are delivered to the host app. Note that the user may still choose to disable this feature by disabling location awareness on a system level in the device settings.

Debugging

During development, it’s a good idea to enable logging and testing using the associated methods in the AdRegistration class. Doing so will for example make it easier for you to track the messages sent to the ad framework in the logcat window. Just make sure to disable logging and testing before launching your app to production.

Handling Ad Events

Once an Ad object has been created, it’s possible to hook into events that are generated by the API. This is done via a special listener class from the Mobile Ads API called DefaultAdListener. When you do this, you can trap several events related to an ad and these result in calls to methods that you override. For example, the onAdFailedToLoad() method is called when the ad has failed to load and in that scenario you could determine the possible cause of the failure and if applicable choose to fill the advert using an alternative ad network.

See this article about event tracking and error handling for more details.

Conclusion

The Amazon Mobile Ads API provides you with additional ways in which you can monetize your mobile apps and games via ads relating to products or services that come from Amazon or other well-known brands. Integrating the API into your Android Java app or game is quick and easy. Once you have integrated the API, you are paid for ads on impressions rather than on clicks.

Here are some more links to useful articles on using the Amazon Mobile Ads API in your Android Java based app:

• Mobile Ads for Android
• Mobile Ads FAQ

In upcoming blogs, I will discuss how you can use the Amazon Mobile Ad API in games or apps running on iOS and those that have been developed using popular frameworks such as Unity and Marmalade.

Simon Howard (@SimonH109)