Event Tracking
The API includes the AmazonAdViewDelegate
and AmazonAdInterstitial
protocols intended for a delegate to conforms to and to implement the necessary protocol methods for tracking ad life-cycle events. They allow your app to take action based on the current state of the ad. AmazonAdViewDelegate
defines the protocol methods for banner ads, and AmazonAdInterstitial
defines the protocol methods for interstitial ads.
AmazonAdViewDelegate
ViewController for Modal views
The application's ViewController is required to implement this protocol method. The AmazonAdView relies on this method to determine which view controller is used to present/dismiss modal views, such as the in-app browser view presented when a user taps on an ad. Called each time an ad is successfully loaded.
- (UIViewController *)viewControllerForPresentingModalView
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.
Callback:
- (void)adViewDidLoad:(AmazonAdView *)view
Ad Will Expand
After a user clicks on a rich media ad, but prior to expanding, this callback is called. This callback can be used to do things like pause your app or suspend audio prior to expanding the ad.
Callback:
- (void)adViewWillExpand:(AmazonAdView *)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.
Callback:
- (void)adViewDidCollapse:(AmazonAdView *)view
Ad Failed To Load
Whenever an ad fails to be retrieved, the adviewDidFailToLoad
method is called, returning an AmazonAdError
object that contains an error code and message. An ad load 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.
Callback:
- (void)adViewDidFailToLoad:(AmazonAdView *)view withError:(AmazonAdError *)error
AmazonAdInterstitialDelegate
Interstitial Loaded
Sent when an interstitial load has succeeded and the interstitial is ready for display at the appropriate moment. You can use this to log metrics on ad views and assist with initial integration.
Callback:
- (void)interstitialDidLoad:(AmazonAdInterstitial *)interstitial
Interstitial Failed To Load
Sent when an interstitial load has failed, returning an AmazonAdError
object that contains an error code and message. An interstitial load 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 interstitial 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 interstitial.
Callback:
- (void)interstitialDidFailToLoad:(AmazonAdInterstitial *)interstitial withError:(AmazonAdError *)error
Interstitial Will Present
Sent immediately before interstitial is presented on the screen. At this point you should pause any animations, timers or other activities that assume user interaction and save app state. User may press Home or touch links to other apps like iTunes within the interstitial, leaving your app.
Callback:
- (void)interstitialWillPresent:(AmazonAdInterstitial *)interstitial
Interstitial Did Present
Sent when interstitial has been presented on the screen.
Callback:
- (void)interstitialDidPresent:(AmazonAdInterstitial *)interstitial
Interstitial Will Dismiss
Sent immediately before interstitial leaves the screen, restoring your app and your view controller used for presenting the interstitial. At this point you should restart any foreground activities paused as part of interstitialWillPresent
.
Callback:
- (void)interstitialWillDismiss:(AmazonAdInterstitial *)interstitial
Interstitial Did Dismiss
Sent when the user has dismissed interstitial and it has left the screen.
Callback:
- (void)interstitialDidDismiss:(AmazonAdInterstitial *)interstitial
Errors
When the ad fails to load, both -[AmazonAdViewDelegate adViewDidFailToLoad:withError:]
and -[AmazonAdInterstitalDelegate interstitialDidFailToLoad:withError:]
return an AmazonAdError
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 load an ad again based on the error code returned. The possible error codes and their meanings are listed below.
- AmazonAdErrorNetworkConnection The ad request failed due to problems with network connectivity. Try again when a connection becomes available.
- AmazonAdErrorNoFill The ad request succeeded but no ads were available. Don’t retry immediately.
- AmazonAdErrorInternalServer The ad request failed due to a server-side error. Try again but limit the number of retry attempts.
- AmazonAdErrorRequest 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 |
---|---|---|
AmazonAdErrorNetworkConnection | The Internet connection appears to be offline. | A network connection is not available -- Retry. |
AmazonAdErrorNoFill | SDK Message: Ad not found. | No ad returned from the server. |
AmazonAdErrorInternalServer | Failed to load configuration. | Configuration is not loaded before loading an ad -- Retry. |
AmazonAdErrorInternalServer | Server Message: DISABLED_APP | The server has denied your ad request. If you have recently integrated ads on this app for the first time then you may need to wait longer for your registration information to process. |
AmazonAdErrorInternalServer | Server Message: INVALID_APPID | Your Application Key was not recognized. Make sure that you have received one from Amazon and that you have configured it correctly (see Step 3 of the Quick Start Guide. |
AmazonAdErrorRequest | Server Message: An invalid interstitial request was sent. | Make sure that the values in the `AmazonAdOptions` used for ad loading is set correctly and retry. |