Event Tracking and Errors

Event Tracking

The API includes an AdListener interface that allows you to track life-cycle events of an ad. The listener allows your app to take action based on the current state of the Amazon ad view.

The following example demonstrates how to assign an AdListener instance to an AdLayout.

Example:
	AdLayout adLayout = new AdLayout();
	adLayout.setListener(myAdListener);

Important: The listener's events are part of the main UI thread, so any long running tasks should be done in an ASYNC task.


Ad Loaded

Each time an ad is successfully loaded this callback is called. You can use this to log metrics on ad views and assist with initial integration. Detailed information about the ad that loaded can be obtained from the AdProperties object.

Event:
	public interface AdListener
	{
	    ...
	
	    public void onAdLoaded(AdLayout view, AdProperties adProperties);
	}

Ad Expanded

After a user clicks on a rich media ad and after the rich media ad expands, this callback is called. This callback can be used to do things like pause your app or suspend audio when an ad has expanded.

Event:
	public interface AdListener
	{
	    ...    
	
	    public void onAdExpanded(AdLayout view);
	}

Ad Collapsed

After a user clicks on the close ad button on an expanded rich media ad, this callback is called immediately after collapsing the ad. This callback can be used to do things like resume your app or restart audio.

Event:
	public interface AdListener
	{
	    ...
	    
	    public void onAdCollapsed(AdLayout view);
	}

Ad Failed To Load

Whenever an ad fails to be retrieved the AdListener.onAdFailedToLoad event is called, returning an AdError object that contains an error code and message. An ad can fail for a number of reasons, which can be grouped into two categories: transient and non-transient errors. When an error is transient, you should make another call to load the ad based on a standard retry algorithm, or when conditions change, e.g. when a network becomes available. When the failure is non-transient, you should log the error and investigate why your app is unable to successfully retrieve an ad.

Event:
	public interface AdListener
	{
	    ...    
	
	    public void onAdFailedToLoad(AdLayout view, AdError error);
	}

Errors

When the ad fails to load, the AdListener.onAdFailedToLoad event returns an AdError object that contains an error code and a descriptive response message. The Amazon Mobile Ads API does not contain any retry logic. If you encounter an error, you should decide whether to call AdLayout.loadAd again based on the error code returned.

The possible error codes and their meanings are listed below.

  • NETWORK_ERROR The ad request failed due to problems with network connectivity. Try again when connectivity 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.

Error Code Example Error Message Description
NETWORK_ERROR Network error reading data from ad server. Service temporarily unavailable -- Retry.
NETWORK_ERROR Unknown error occurred. A network connection is not available -- Retry.
NO_FILL SDK Message: no results. Try again in X seconds. No ads are available for the next X seconds.
NO_FILL Server Message: no results. The server did not have any ads for this request.
NO_FILL Server Message: no results. Try again in X seconds. The server did not have any ads for this request. Subsequent calls will return immediately with no results for the next X seconds.
INTERNAL_ERROR No valid creative types found. The returned ad does not have any creative type attributes set -- Retry.
INTERNAL_ERROR Server Message: DISABLED_APP The server has denied your ad request. You may need to wait longer for your registration information to process.
INTERNAL_ERROR Server Message: INVALID_APPID Your Application Key was not found or was disabled. Make sure that you have received one from Amazon and that you have configured it correctly (see Step 3 of the Quick Start Guide).
INTERNAL_ERROR Unable to parse response from ad server. The returned ad was invalid -- Retry.
REQUEST_ERROR Ads cannot load unless "com.amazon.device.ads.AdActivity" is correctly declared as an activity in AndroidManifest.xml. Find more information here: https://developer.amazon.com/sdk/mobileads/quick-start.html#Step2 Please refer to Step 2 of the Quick Start Guide for more information about adding AdActivity to your app’s AndroidManifest.xml file.
REQUEST_ERROR Ad request failed due to invalid Auto Ad Size parameters. Your ad view is too small to receive an automatically sized ad on the current device. See the Auto Ad Size section for guidelines on creating an appropriately sized ad view.
REQUEST_ERROR Can't load an ad because layout parameters are blank. Use setLayoutParams() to specify dimensions for this AdLayout. Make sure to set your AdLayout's width and height layout parameters before loading ads if your AdLayout was created off the screen in memory.
REQUEST_ERROR Can't load an ad because the view size cannot be determined. Your ad view has been set up in a way that is not compatible with the way it's attempting to load ads. If you're loading an ad off the screen, make sure your AdLayout does not have a parent view set until it's been added to the visible view hierarchy. If you're using Auto Ad Size, you may need to set the size manually instead.


Return to the Amazon Mobile Ads API Overview

Unavailable During Maintenance