When displaying ads in your apps and games, you may want to know how often you are actually displaying ads to your users, what types of ads are being displayed, and how your users are interacting with an ad. 

Thankfully, the Amazon Mobile Ads API includes events that can aid you in understanding performance of ads displayed on your apps.  You have the ability to track when an ad is successfully displayed from the Amazon Ad Network, how long a user views an ad, and when your user opens or closes a rich media expandable banner ad.  These events should help you track and better understand user behavior in your apps when ads are being shown.

With a guaranteed CPM of $1.50 for banner ads displayed on qualified apps during March and April (up to 2 million impressions per app per month), there has never been a better time to get started using the Amazon Mobile Ads API.

Handling Ad Events

All of the events associated with an ad provided by the Amazon Mobile Ads API will be returned by the AdListener interface.  Once you have declared an instance of an Amazon AdLayout, setting an event listener to the layout will let you track the entire life cycle of an ad. 

Keep in mind all of the listener's events are part of the main UI thread.  So if you are planning on executing any long running tasks you should do so in an AsyncTask.

Capturing Metrics When Ads are Loaded

You can capture metrics in your app each time an ad is loaded using the AdLoaded event.  AdLoaded is called each time an ad is successfully served by the Amazon Mobile Ad Network, and available for display.  You can use this event to adjust your app’s user interface when a new ad is loaded or to keep track of the type of ads you are being served. 

For example, if you have a game, you should choose to delay displaying the AdView until the player is at a point where an ad will not interrupt gameplay.  In the below example I am updating a TextView each time an ad is successfully loaded and then adding the AdView to the root container for display.

You can get additional properties about the ad being served at runtime through AdProperties.  These properties can help determine if your ad is a static banner or a rich media expandable banner.  Static banners are HTML web views that typically open an in-app browser, native browser, or Android Intent.  Rich Media Expandable Banners are HTML web views that expand in-app with rich interactive content (including videos), but also typically include opening an in-app browser, native browser, or Android Intent.

In the above screenshot, I have set a breakpoint to get information from the AdProperties variable.  There are four types of information that are filled by AdProperties.  These include:

• adType - possible values are 'Image Banner', 'MRAID 1.0' or 'MRAID 2.0'.  MRAID stands for Mobile Richmedia Ad Interface Definition and will determine the capability of the rich media expandable banner.
• canExpand – determines if the ad can be expanded
• canPlayAudio – determines if the ad plays audio when expanded
• canPlayVideo – determines if the ad plays video when expanded

Trigger changes when an ad expands

The onAdExpanded and onAdCollapsed events are called when a rich media expandable banner ad has been clicked by a user and is either expanded or collapsed.  You can use this event to pause your game or suspend background audio music when an ad has expanded, among other options.

Handling Ad Load Errors

If an ad fails to load, the AdListener.onAdFailedToLoad event returns an AdError object that contains an error code and a descriptive response message.  For example, the onAdFailedToLoad event below is logging the ad error message, removing the Amazon view from the UI, and then loading a Google AdMob view to request an ad.

It is important to keep in mind that the there is no logic to retry loading an ad.  If you encounter an error, you should decide whether to call AdLayout.loadAd again based on the error code returned. 

The error codes are helpful in debugging where errors may be occurring; server side, network based, or within the app code itself.  In the below example we see an AdError occurring due to the developer setting an incorrect view size.  This can happen if an ad is requested before its parent view is available. 

The possible error codes that can be returned include the following.

• NETWORK_ERROR The ad request failed due to problems with network connectivity. Try again when a connection becomes available.
• NO_FILL The ad request succeeded but no ads were available. Don’t retry immediately.
• INTERNAL_ERROR The ad request failed due to a server-side error. Try again but limit the number of retry attempts.
• REQUEST_ERROR There is a problem with the ad request parameters. Do not retry. Review the error message and update your app accordingly.

For specific error message descriptions, please refer to the following chart on our developer portal here.

You can get more information on the Amazon Mobile Ads API including code samples and training videos here.

-Dave (@TheDaveDev)