Getting Started with the Amazon Mobile Ads API

Introduction

Following the success of the In-App Purchasing API, we are pleased to introduce a new monetization option for app developers, theAmazon Mobile Ads API. Now, whether you monetize through paid apps, in-app purchases, or mobile advertising, Amazon offers a solution to help grow your business.

The Amazon Mobile Ads API is an in-app display advertising API, which offers:

• A monetization opportunity with a competitive eCPM
• High-quality ads from Amazon and brand advertisers
• Easy integration and revenue tracking through the Mobile App Distribution Portal
• Distribution at scale through Amazon and other Android platforms

The Amazon Mobile Ads API serves ads to U.S. users, and works with mobile apps on Kindle Fire, Kindle Fire HD, and Android phones and tablets. Apps that use the Amazon Mobile Ads API may be distributed through any Android platform as long as they are available for download from Amazon as well.

To learn how to quickly integrate the Amazon Mobile Ads API, read on. This Quick Start Guide provides you step-by-step instructions for incorporating the Amazon Mobile Ads API into your app. The Amazon Mobile Ads API currently supports both static image banners and expandable rich media banners with videos.

Before You Use the Amazon Mobile Ads API

The Amazon Mobile Ads API for Android requires Android 1.6 (Donut) or later and assumes you have Eclipse installed with Android Development Tools (ADT) Plugin. Familiarity with Android development is also required.

Account Registration - Self Service

Sign in to your Distribution Portal account at http://developer.amazon.com. If you do not already have one, you will be prompted to create an account.

Submit Your Payment Information and Tax Information 

Submit your payment information through the Payment Information Page and your tax information through the Tax Identity Interview. (Skip this step if you have already submitted this information through the Amazon Mobile App Distribution Portal) This information is required to receive ads.

Obtain an Application Key

Once signed in, click on the "My Apps" tab and then select an existing app or click on the "Add a New App" button. When creating a new app, just fill in the "App Title" and "Form Factor" fields and click the "Save" button. The next screen will show the unique Application Key value, which is a 32-character globally unique alphanumeric string that is used to identify your app. The same Application Key can be used across platforms, but each distinct app must have a unique Application Key. For example, the IMDb apps for Android Phone and Kindle Fire use the same Application Key, but the IMDb Trivia app has a different Application Key. The Application Key is used in the setAppKey call mentioned in Step 3 of the Quick Start Guide, and your developer reports will aggregate data by Application Key. Proper use of your Application Key permits accurate tracking, reporting, and accrual of advertising fees.

Note: If you use an Application Key that is issued for one app in connection with the display of ads on a second app, we will not pay you for any resulting impression, click or other user action relating to ads on the second app.

Apps that use the Amazon Mobile Ads API may be distributed through any Android platform as long as they are available for download through the Amazon App Distribution Program.

Enabling Ads in Android Apps

This section of the Quick Start Guide steps you through adding ads to an existing Android app Eclipse project:

1. Incorporate the API into Your Project
2. Update the Android Manifest
3. Set Your Application Key
4. Add the Amazon Ad Layout to Your App

Note: If you choose to incorporate the Amazon Mobile Ads API into your project via the Amazon Mobile App SDK Eclipse Plugin, Step 1 and Step 2 will be completed automatically. Note that you will need to extract the Mobile Ads zip file to the same folder as the Apps-SDK zip to take advantage of this functionality. You can learn more about the Eclipse plugin by visiting this site.

1. Incorporate the API into Your Project

Add the Amazon Mobile Ads API Jar to Your Eclipse Project

You need to add the amazon-ads-x.y.z.jar to your project build path.

In Eclipse:

1. Click on project Properties, which opens the Properties dialog
2. Select "Java Build Path"
3. Select Libraries on the top
4. Click "Add External JARs..." to open the JAR Selection dialog
5. Select the amazon-ads-x.y.z.jar and click "Open"

 

Add the Amazon Ad Resources to your project

You need to copy the contents of the res directory to root directory of your project when building your user interface via Android XML layout files. This will merge the contents of the Ads resources to your project. For example if the root directory of your project is HelloAds, then the contents of the project's res directory should contain the Amazon file:

./HelloAds/res/values/amazon_ads_attr.xml

2. Update the Android Manifest

Amazon MRAID Browser Activity

The Amazon Mobile Ads API requires the com.amazon.device.ads.MraidBrowser and com.amazon.device.ads.VideoActionHandler to be declared in your app's AndroidManifest.xml file. This is required to support rich media ads. Please add the following MraidBrowser and VideoActionHandler declarations within the application tags of your AndroidManifest.xml file:

<activity android:name="com.amazon.device.ads.MraidBrowser" android:configChanges="keyboardHidden|orientation"/>

<activity android:name="com.amazon.device.ads.VideoActionHandler" android:configChanges="keyboardHidden|orientation|screenSize"/>

Permissions

Making ad requests to the Amazon Mobile Ad Network requires the INTERNET permission. Additionally we recommend that you include permissions for FINE_LOCATION, COARSE_LOCATION,NETWORK_STATE, and WIFI_STATE. These additional permissions allow Amazon to provide relevant, targeted ads to your users, which may result in higher CPMs. These permissions need to be declared outside of the application tags in your AndroidManifest.xml file. See the permission declarations below:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

Example Manifest

For an illustration of how these declarations are implemented into an AndroidManifest.xml file, please refer to the example below:

   <?xml version="1.0" encoding="utf-8"?>
   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
       package="com.company"
       android:versionCode="1"
       android:versionName="1.0" >
       <uses-sdk android:minSdkVersion="4" android:targetSdkVersion="13" />
       <application
           android:icon="@drawable/ic_launcher"
           android:label="@string/app_name" >
          <activity
              android:name=".AdTestAppActivity"
              android:label="@string/app_name" >
              <intent-filter>

                  <action android:name="android.intent.action.MAIN" />
                  <category android:name="android.intent.category.LAUNCHER" />
              </intent-filter>
          </activity>    
          <activity android:name="com.amazon.device.ads.MraidBrowser" android:configChanges="keyboardHidden|orientation"/> 
          <activity android:name="com.amazon.device.ads.VideoActionHandler" android:configChanges="keyboardHidden|orientation|screenSize"/> 
      </application>
      <uses-permission android:name="android.permission.INTERNET" />
      <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
      <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
      <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
      <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
  
  </manifest>

3. Set Your Application Key

You must set your Application Key in order to receive ads. This allows Amazon to track your impressions and clicks, and associate them with your account. You should have your app call theAdRegistration.setAppKey() function on every app start using the Application Key from the Amazon Mobile App Distribution. You could add this call to your Activity's onCreate function, or some other app initialization code. Here's an example of setAppKey in onCreate:

public void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.main);

  AdRegistration.setAppKey(getApplicationContext(),
      "0123456789ABCDEF0123456789ABCDEF");
}

4. Add the Amazon Ad Layout to Your App

To retrieve and display an ad, you will use an instance of AdLayout, which can be created either in code or XML. To load an ad, call the AdLayout.loadAd method, which uses an asynchronous task to request an ad from the Amazon Mobile Ad Network. Only one ad can be loading or displayed by a given Ad Layout at a given time. AdLayout.loadAd will return false if a request for a new ad is ignored because of another pending ad request. To check if there is an ad loading, you can call the method AdLayout.isAdLoading. When requesting an ad, you can also set a number of optional targeting parameters; these are covered here.

Below is an example of a simplified AdLayout.loadAd call placed in the Activity's onCreate function:

   @Override
   public void onCreate(Bundle savedInstanceState) 
   {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.main);
       AdRegistration.setAppKey(getApplicationContext(),
           "0123456789ABCDEF0123456789ABCDEF");
 
       // Programmatically create the AmazonAdLayout       
  this.adView = new AdLayout(this, AdLayout.AdSize.AD_SIZE_320x50);
      LinearLayout layout = (LinearLayout) findViewById(R.id.mainLayout);
    // Set the correct width and height of the ad.
  LinearLayout.LayoutParams lp = new LinearLayout.LayoutParams(
         LinearLayout.LayoutParams.MATCH_PARENT,
         LinearLayout.LayoutParams.MATCH_PARENT);
      layout.addView(this.adView,lp);
 
      // If you declared AdLayout in your xml you would instead
      // replace the 3 lines above with the following line
      // this.adView = (AdLayout) findViewById( R.id.adview );
    
      this.adView.loadAd(new AdTargetingOptions()); // async task to retrieve an ad
  }

Here's the Activity's onDestroy function:

  @Override
  public void onDestroy() {
      super.onDestroy();
      this.adView.destroy();
  }

Optional - Add the AdLayout to Your Corresponding Layout XML File

You can also add the AdLayout to your XML layout file. You would need to first add the Amazon namespace to the root Layout and the AdLayout to your layout.xml file. In the definition of AdLayout, the attribute Amazon:adSize is required. For example:

   <?xml version="1.0" encoding="utf-8"?>
   <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
       xmlns:Amazon="http://schemas.android.com/apk/res/<type your package name>"
       android:orientation="vertical"
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       >
       <com.amazon.device.ads.AdLayout  
           android:id="@+id/adview" 
          android:layout_width="320dp" 
          android:layout_height="50dp" 
          Amazon:adSize="320x50"/>
   </ LinearLayout>

The Amazon Mobile Ads API samples directory includes the full source and project file for the above SimpleAdSample.

Optional - Set an Ad Request Timeout Value

An ad request call has a default timeout of 10 seconds. After the timeout threshold is exceeded the AdListener.onAdFailedToLoad event is called. The default timeout value can be changed using the AdLayout.setTimeout function, which takes milliseconds as an argument.

Example:

  AdLayout adLayout = new AdLayout();
  adLayout.setTimeout(20000); //20 seconds

Where Do I Go From Here?

1. Please read the following sections:
   • Ad Targeting Options
   • Event Tracking
   • Errors
   • Ad Sizes
   • Testing and Debugging
   • Updating Attributions
   • Developer Launch Checklist
2. Compile and run the two sample apps located in the /Ads/samples directory. The SimpleAdSample demonstrates the basics of how to load an ad, and the FloatingAdSample demonstrates how to load an ad that floats in from the bottom of the screen.

To learn more about the Amazon Mobile Ads API, click here. If you’re ready to get started, download the Amazon Mobile Ads API now.