Home > APIs > Earn > Mobile Ads

Quick Start Guide

Introduction

The Quick Start Guide provides you step-by-step instructions for incorporating Amazon Mobile Ads into your app. The Amazon Mobile Ads API currently supports static image banners, expandable rich media banners with videos, and interstitials.

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 Amazon Apps & Games Developer Portal account, which you can access through the Amazon Developer Services Page. 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 Page (skip this step if you have already submitted this information through the Amazon Apps & Games Developer 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 app uses the same Application Key on Android phone and Fire tablets, 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.

Add the Google Play Services SDK to Your App

Important: This step is required if you plan to submit your app to the Google Play Store after August 1, 2014. If not, you may skip this section.

Beginning on August 1, 2014, ad-serving apps distributed through Google Play must comply with the Google Play Services Advertising Identifier conditions outlined on Google’s policy page. To ensure adherence to these new conditions, developers intending to distribute apps integrated with the Amazon Mobile Ads API on Google Play must follow these instructions:

  • Integrate the Google Play Services SDK into the app by following the Google Play Services SDK Setup Instructions.
  • Ensure that the version of the Amazon Mobile Ads Android API that's being used is 5.4.46 or higher. Older versions do not support the required identification changes.

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 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. You can learn more about the Eclipse plugin by visiting the Eclipse Plugin Page.

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"

Fig. 1: Screenshot depicting the addition of Amazon Mobile Ads API jar to a project in the Eclipse environment

2. Update the Android Manifest

Amazon Ad Activity

The Amazon Mobile Ads API requires the com.amazon.device.ads.AdActivity to be declared in your app's AndroidManifest.xml file. Please add the following AdActivity declaration within the application tags of your AndroidManifest.xml file:

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

Permissions

Making ad requests to the Amazon Mobile Ad Network requires the INTERNET permission. We also highly recommend including permissions for ACCESS_NETWORK_STATE and ACCESS_WIFI_STATE. These additional permissions allow Amazon to provide relevant, targeted ads to your users, which may result in higher CPMs. These permissions, as well as any additional 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_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

The ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION permissions can also be included to allow location-based targeting. Including one of these permissions allows Amazon to supply highly relevant targeted ads and may result in higher CPMs. If either of these permissions are included, they should also be declared in the same way:

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

Important: To allow targeting based on location, you must also enable geographic location targeting via the enableGeoLocation API as specified in the Ad Targeting Options section.

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"?>
    package="com.company"
    android:versionCode="1"
    android:versionName="1.0" >
    <uses-sdk android:minSdkVersion="4" android:targetSdkVersion="17" />
    <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.AdActivity"
            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 the AdRegistration.setAppKey() method on every app start using the Application Key from the Amazon Mobile App Distribution. You could add this call to your activity's onCreate method, 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("0123456789ABCDEF0123456789ABCDEF");
}

4. Add the Amazon Ad to Your App

The Amazon Mobile Ads API now supports both banner ads and interstitial ads. Banner ads, which include static click-through ads as well as rich media expandable ads, are created via AdLayout objects. Meanwhile, interstitial ads are full-screen ads that are created via InterstitialAd objects. Both AdLayout and InterstitialAd are Java classes that implement the Ad interface.

Learn more about different ad types on the Android Ad Concepts Page.

Adding Banner Ads through Java Code

To retrieve and display a banner 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 a background thread to request an ad from the Amazon Mobile Ad Network. Only one ad can be loading or displayed by a given AdLayout 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 a particular ad is loading, you can call the method AdLayout.isLoading. When requesting an ad, you can also set a number of optional targeting parameters; these are covered on the Ad Targeting Options Page. Below is an example of a simplified AdLayout.loadAd call placed in the activity's onCreate method:

@Override
public void onCreate(Bundle savedInstanceState)
{
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
    AdRegistration.setAppKey("0123456789ABCDEF0123456789ABCDEF");
 
    // Programmatically create the AmazonAdLayout      
    this.adView = new AdLayout(this);
    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);
    
    AdTargetingOptions adOptions = new AdTargetingOptions();
    // Optional: Set ad targeting options here.
    this.adView.loadAd(adOptions); // Retrieves an ad on background thread
}
Here's the activity's onDestroy method:
@Override
public void onDestroy()
{
    super.onDestroy();
    this.adView.destroy();
}

Note: To have the Amazon Mobile Ads Android SDK automatically select the ad's size based on the layout's size and the device's screen size, you should make sure to follow the guidelines in the Auto Ad Size section. The above implementation uses Auto Ad Size by default. If you would instead like to set the size manually, follow the instructions for Manual Ad Size.

Adding Banner Ads through XML Layout 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 following example AdLayout definition, the attribute Amazon:adSize is omitted, meaning that the dimensions of the ad will be determined using Auto Ad Size. If you'd rather set the size yourself, you will have to include this attribute as described in the Manual Ad Size section.

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    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="match_parent" 
        android:layout_height="wrap_content"/>
</LinearLayout>

The Amazon Mobile Ads API samples directory includes the full source and project file for the Simple Ad Sample, which provides an example implementation similar to what's seen above.

Adding Interstitial Ads through Java Code

Interstitials are full-page ads designed to be loaded in the app's background and then shown to the user during a natural transition point in the app. An instance of InterstitialAd needs to be created in your code before you can retrieve and display interstitial ads. Ad loading can be accomplished by calling the InterstitialAd.loadAd method, which uses a background thread to request an ad from the Amazon Mobile Ad Network. Only one ad can be loaded by a given InterstitialAd object at a given time, and only one interstitial ad can be displayed in your app at a given time. InterstitialAd.loadAd will return false if a request for a new ad is ignored because of another pending ad request. To check if a particular ad is currently loading, you can call the method InterstitialAd.isLoading. To check if a particular ad is currently showing, you can call the method InterstitialAd.isShowing. To check if any interstitial ad is currently showing, you can call the static method InterstitialAd.isAdShowing. And finally, just as you can when requesting a banner ad, you can also set a number of optional targeting parameters when requesting an interstitial; these parameters are covered on the Ad Targeting Options Page.

Below is an example of a simplified InterstitialAd.loadAd call placed in the onCreate method of an Activity that loads the next level in a game app. The interstitial ad is displayed as soon as it is ready, and the next level is started after the user has dismissed the ad by pressing either the ad's "X" button or the device's back button.

public class LoadNextLevel extends Activity
{

    private InterstitialAd interstitialAd;

 
    @Override
    public void onCreate(Bundle savedInstanceState)
    {
          super.onCreate(savedInstanceState);
 

          AdRegistration.setAppKey("0123456789ABCDEF0123456789ABCDEF");
 

          // Create the interstitial.
          this.interstitialAd = new InterstitialAd(this);
 
          // Set the listener to use the callbacks below.
          this.interstitialAd.setListener(new MyCustomAdListener());
 
          // Load the interstitial.
          this.interstitialAd.loadAd();
    }
 
    class MyCustomAdListener extends DefaultAdListener
    {
        @Override
        public void onAdLoaded(Ad ad, AdProperties adProperties)
        {
            if (ad == LoadNextLevel.this.interstitialAd)
            {
                // Show the interstitial ad to the app's user.
                // Note: While this implementation results in the ad being shown
                // immediately after it has finished loading, for smoothest user
                // experience you will generally want the ad already loaded
                // before it’s time to show it. You can thus instead set a flag
                // here to indicate the ad is ready to show and then wait until
                // the best time to display the ad before calling showAd().
                LoadNextLevel.this.interstitialAd.showAd();
            }
        }
 
        @Override
        public void onAdFailedToLoad(Ad ad, AdError error)
        {
            // Call backup ad network.
        }
 
        @Override
        public void onAdDismissed(Ad ad)
        {
            // Start the level once the interstitial has disappeared.
            startNextLevel();
        }
    }
}

Adding Modeless Interstitial Ads through Java Code

To retrieve and display a modeless interstitial ad, you will use an instance of ModelessInterstitialAd. To load a modeless interstitial, call the method ModelessInterstitialAd.loadAd, which uses a background thread to request a modeless interstitial from the Amazon Mobile Ad Network. Only one modeless interstitial can be loading for a given ModelessInterstitialAd instance at a given time, ModelessInterstitialAd.loadAd will return false if a request for a new ad is ignored because of another pending ad request. When loading a modeless interstitial, you can also set a number of optional targeting parameters; these are covered on the Ad Targeting Options Page. To check if a particular ad is currently loading, you can call the method ModelessInterstitialAd.isLoading Once loaded, the onAdLoaded callback is fired and the ad is ready for showing. ModelessInterstitialAd also provides the isReady property to check the readiness of the modeless interstitial for convenience. You must call ModelessInterstitialAd.adShown when the modeless interstitial is presented on the screen for impression counting. You must also callModelessInterstitialAd.adHidden to inform the SDK when the modeless interstitial leaves the screen.

Below is a code excerpt from SwipeableModelessInterstitialAdSample which displays an ad interspersed with images. This sample utilitizes a FragmentPagerAdapter to handle the user interaction and the process of creating and loading a ModelessInterstitialAd for displaying. It also utilizes an OnPageChangeListener to identify the fragment on screen which provides the ability to execute ModelessInterstitialAd.adShown and ModelessInterstitialAd.adHidden when an ad is presented to and hidden from the user.

private class ModelessInterstitialFragmentPagerAdapter extends FragmentPagerAdapter
{
    private final int[] images; // the collection of images to display in the image gallery
    private int nextImageIndex; // the next image to display from the collection of images
    private static final int PAGE_COUNT = 20;
    private FrameLayout adContainerLayout;

    public ModelessInterstitialFragmentPagerAdapter(FragmentManager fm)
    {
        super(fm);
        this.images = new int[]{R.drawable.image1, R.drawable.image2, R.drawable.image3,
                                R.drawable.image4, R.drawable.image5};
    }

    @Override
    public Fragment getItem(int index)
    {
        if (index % AD_FREQUENCY == 2)
        {
            this.adContainerLayout = new FrameLayout(SwipeableModelessInterstitialAdActivity.this;
            modeless = new ModelessInterstitialAd(this.adContainerLayout);
            modeless.setListener(new SampleAdListener());
            modeless.loadAd();
            // Note: You can choose to provide additional targeting information to
            // modify how your ads are targeted to your users. This is done via an
            // AdTargetingOptions parameter that's passed to the loadAd call.
            // See an example below:
            //
            // final AdTargetingOptions adOptions = new AdTargetingOptions();
            // adOptions.enableGeoLocation(true);
            // if (this.modelessInterstitialAd.loadAd(adOptions)) ...

        }
        if (index != 0 && index % AD_FREQUENCY == 0 && isReadyToShow)
        {
             modelessAds.put(index, modeless);
             return new ModelessInterstitialFragment().setAdContainerLayout(this.adContainerLayout);
        }
        final ImageGalleryFragment fragment = new ImageGalleryFragment();

        fragment.setImageResource(this.images[this.nextImageIndex++;
        if (this.nextImageIndex == this.images.length)
        {
            this.nextImageIndex = 0;
        }
        return fragment;
    }

    @Override
    public class int getCount()
    {
        return PAGE_COUNT;
    }

    /**
     * This class is for an event listener that tracks ad lifecycle events. It
     * extends DefaultAdListener, so you can override only the methods that you
     * need. In this case, there is no need to override methods specific to
     * expandable ads.
     */

    private class SampleAdListener extends DefaultAdListener
    {
        /**
         * This even is called once an ad loads successfully.
         */

        @Override
        public void onAdLoaded(final Ad ad, AdProperties adProperties)
        {
            Log.i(LOG_TAG, adProperties.getAdType().toString() + "ad loaded successfully.");
            isReadyToShow = true;
        }

        /**
         * This event is called if an ad fails to load.
         */

        @Override
        public void onAdFailedToLoad(final Ad view, final AdError error)
        {
            Log.w(LOG_TAG, "Ad failed to load. Code: " + error + ", Message: " + error.getMessage());
            isReadyToShow = false;
        }
    }
}

/**
* Used for capturing page change events
*/

private class ModelessInterstitialOnPageChangeListener implements OnPageChangeListener
{
    private int prevPosition = -1; // index of previous on screen fragment
    private int currPosition = -1; // index of current on screen fragment

    @Override
    public void onPageScrollStateChanged(final int state)
        {
            switch(state)
            {
                case ViewPager.SCROLL_STATE_IDLE:
                    ModlessInterstitialAd modelessAd = modelessAds.get(this.currPosition);
                    if (modelessAd != null)
                    {
                        modelessAd.adShown();
                    }
                     modelessAd = modelessAds.get(this.prevPosition);
                    if (modelessAd != null)
                    {
                        modelessAd.adHidden();
                    }
                    break;
                default:
                    break;
            }
        }

    @Override
    public void onPageScrolled(final int position, final float positionOffset, final int positionOffsetPixels)
    {}

    @Override
    public void onPageSelected(final int position)
    {
        this.prevPosition = this.currPosition;
        this.currPosition = position;
    }
}

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 method, 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:

2) Compile and run one or more of the sample apps located in the /Ads/samples directory. The Simple Ad Sample demonstrates the basics of how to load an ad, the Floating Ad Sample demonstrates how to load an ad that floats in from the bottom of the screen, the Interstitial Ad Sample demonstrates how to load and display an interstitial ad, the Swipeable Modeless Interstitial Ad Sample demonstrates how to load and display a modeless interstitial ad with swiping gesture transitions, and the Framed Modeless Interstitial Ad Sample demonstrates how to load and display a modeless interstitial ad in a framed context.