Table of Contents
- Before You Use the Amazon Mobile Ads API
- Add the Google Play Services SDK to Your App
- Enabling Ads in Android Apps
- 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
- Optional - Set an Ad Request Timeout Value
- Where Do I Go From Here?
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.
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 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.
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:
- Incorporate the API into Your Project
- Update the Android Manifest
- Set Your Application Key
- 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
You need to add the amazon-ads-x.y.z.jar to your project build path. In Eclipse:
- Click on project Properties, which opens the Properties dialog
- Select "Java Build Path"
- Select Libraries on the top
- Click "Add External JARs..." to open the JAR Selection dialog
- 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
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
Making ad requests to the Amazon Mobile Ad Network requires the
INTERNET permission. We also highly recommend including permissions for
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:
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:
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.
For an illustration of how these declarations are implemented into an
AndroidManifest.xml file, please refer to the example below:
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
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
InterstitialAd are Java classes that implement the
Learn more about different ad types on the Android Ad Concepts Page.
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
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.
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.
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.
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.
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 call
ModelessInterstitialAd.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.adHidden when an ad is presented to and hidden from the user.
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.
Where Do I Go From Here?
1) Please read the following sections:
- Ad Targeting Options
- Event Tracking
- Ad Sizes
- Testing and Debugging
- Updating Attributions
- Developer Launch Checklist
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.