I recently published a blog post about how you get started using the Amazon Mobile Ads API in your Android Java based app or game. This blog is about how you do the same with an iOS app or game.

What Is the Amazon Mobile Ads API?

The Amazon Mobile Ads API allows you to monetize apps and games across the Android, Fire OS, and iOS platforms by displaying ads to customers in the US, UK, France, Italy, Spain, and Germany. Ads can be banner or interstitial and will advertise products or services coming from Amazon or other well-known brands. You are paid on ad impressions served whilst some other Ad networks only pay on clicks. To get more information on the benefits of using the Amazon Mobile Ad Network, check out the Success Stories.

How Do I get Access to the APIs?

The Amazon Mobile Ads API requires iOS 6.0 or above and Xcode 5.1.1 or above. The API is part of a single SDK (the Amazon Mobile App SDK, which you can download here) that also provides access to other Amazon mobile services and APIs such as GameCircle and In-App Purchasing.  The same download also includes the necessary files to use the API in apps developed for Android.

To use the Amazon Mobile Ads API in your Xcode projects, first download the SDK and extract the zip file to the appropriate location on your development machine. Here’s what the iOS part of the SDK folder looks like on my machine:

Obtain an Application Key

Before you can use the Amazon Mobile Ads API in an app, you should create an Application Key that is unique to the application. This key is used by the Amazon framework to identify your app so it’s essential that you use the correct one so that you will be paid. Note that if you have Android and iOS variants of the same app they must use different application keys.

To create a new key you need an Amazon Apps & Games Developer Portal account. If you don’t have one, you can create an account by visiting here. Also note, because you will be receiving income into the account, you will need to add your payment and tax information details to your developer account profile.

You can bypass this step for now if you want to just try out the API using one of the sample apps. Just make sure you create your own key (and account) later.

Check out the Samples First

Before you start including the Amazon Mobile Ads API in your project, I would recommend playing around with the samples that come with the SDK. You can find these samples in the /iOS/Ads/Samples folder and they are as follows:

Building the Samples in Xcode

Building the iOS samples in Xcode is pretty straightforward. You can import the samples as individual projects into your workspace or you can just get them all in one go by importing the workspace file (.xcworkspace extension) that is in the iOS samples root folder.

If you have imported all of the samples, you will see something similar in the Xcode projects window to the following:

Running the Samples

Once you have imported a sample, there’s nothing more to do within Xcode except to select the build option. I found that all samples build OK in the latest version (6.1.1) of Xcode at the time of writing. If for example, you run the sample FloatingAdUniversalSample you will see something similar to that shown in the screenshot below when it runs:

Including the APIs into Your Own Code

Using the Amazon Mobile Ads API in your own code is relatively straightforward and this Quick Start Guide goes through the steps that you need to follow. The following sections provide some additional tips on using the APIs.

Frameworks

At a minimum you usually need to add the Mobile Ads framework AmazonAd.framework and you may need to add any of the frameworks that are listed in the section “Incorporate the API into your project” in the Quick Start Guide if they are not referenced by your project.

The screenshot below shows the project “Build Phases” settings where the frameworks are added:

Note that you add frameworks to Swift and Objective-C projects in the same way in Xcode.

Using the APIs with Swift

The Quick Start Guide does not at the time of writing discuss the Swift version of the APIs so I thought it would be useful if I provided a quick overview in the sections below.

Amazon Mobile Ads API Swift Classes

There are 5 classes in the Swift implementation of the Amazon Mobile Ads API, which I have summarized below:

Setting the Application Key in Swift Code

Before your app can request an Ad, it’s essential that the app registers itself with the Amazon Mobile Ads framework. To do this, your app needs to specify the application key to the framework via the setAppKey() method in the AmazonAdRegistration class. The best place to call setAppKey() is in the application method in your app’s AppDelegate class. In this method, you should place the following call:

AmazonAdRegistration.sharedRegistration().setAppKey("123")

Where: you substitute ‘123’ with the real application key in the production version of the app.

Adding Banner Ads in Swift Code

To create a banner Ad, your app must create an instance of the AmazonAdView class in the applicable UIViewController class and then load the Ad using the loadAd() method from the AmazonAdView class. The Ad is then loaded in a separate thread (created by the framework) that will report its status via callbacks in the delegate AmazonAdViewDelegate.

The abbreviated code snippet below shows the main activities that need to be done in the app’s applicable UIViewController instance.

// Connect to the banner view control in the storyboard

    @IBOutlet var amazonBannerAd: AmazonAdView!

            override func viewDidLoad() {

      super.viewDidLoad()

      // Create a banner Ad at a given size

      amazonBannerAd = AmazonAdView(adSize: AmazonAdSize_320x50)

      // During development, you must tell the framework that the

      // app is not a production version

      var adOptions = AmazonAdOptions()

      adOptions.isTestRequest = true

      // This loads the Ad

      amazonBannerAd.loadAd(adOptions)

  // Ensure our delegate receives the callback messages

  amazonBannerAd.delegate = self

    }

For simplicity, I have hard-coded the banner size as 320 by 50 pixels in the snippet above but normally you set the Ad size using constants in the AmazonAdOptions class according to whether the app is running on an iPhone or iPad. See Mobile Ads iOS API Concepts for more details.

It is essential that during development you set the isTestRequest member of the AmazonAdOptions instance (used when loading the Ad) to true. In the production version you must set it to false.

Adding Interstitial Ads in Swift Code

To create an interstitial Ad again you create an instance of the AmazonAdInterstitial class in the applicable UIViewController instance and then load the Ad using the load() method from the AmazonAdInterstitial class. The Ad is loaded in a separate thread that will then report its status via callbacks in the delegate AmazonAdInterstitialDelegate.

The abbreviated code snippet below shows the main activities that need to be done in the app’s applicable UIViewController instance to load an interstitial Ad.

// Connect to the banner view control in the storyboard

    @IBOutlet var interstitialAd: AmazonAdInterstitial!

            override func viewDidLoad() {

      super.viewDidLoad()

      // Create the Ad

      InterstitialAd = AmazonAdInterstitial()

      // During development, you must tell the framework that the

      // app is not a production version

      var adOptions = AmazonAdOptions()

      adOptions.isTestRequest = true

      // Loads the Ad

      interstitialAd.load(adOptions)

  // Ensure our delegate receives the callback messages

  interstitialAd.delegate = self

    }

Debugging

During development, it’s a good idea to enable logging using the associated methods in the AmazonAdRegistration class. Doing so makes it easier for you to track the messages sent to the ad framework in Xcode. Just make sure to disable logging before launching your app to production.

In Objective-C code, a good place to enable logging is in the didFinishLaunchingWithOptions method in the AppDelegate class:

    [[AmazonAdRegistration sharedRegistration] setLogging:YES];

In Swift code, the best place to do this is in the application method in your app’s AppDelegate class:

AmazonAdRegistration.sharedRegistration().setLogging(true)

Handling Banner Ad Events in Objective-C or Swift Code

As per the Android version of the API, the Amazon Mobile Ads API enables you to hook into several events related to a banner Ad. For example, you can hook into an event that indicates that the Ad failed to load and in that case you could could determine the possible cause of the failure and if applicable choose to fill the advert using an alternative ad network.

You handle banner Ad events using callback functions that are implemented by AmazonAdViewDelegate. Here are the main functions that you might use…

viewControllerForPresentingModalView()

This callback function must be implemented and it tells the AmazonAdView class which view controller class it should use to render the Ad and also to report events.

adViewDidLoad()

Implement this callback if you want to do something when the Ad was successfully loaded.

adViewDidFailToLoad()

Implement this callback if you want to so something when an Ad failed to load successfully. You would typically determine the likely cause of the error using the error code and respond accordingly.

adViewWillExpand()

Implement this callback if you want to know when the user has tapped the Ad and it is to be displayed modally.

adViewDidCollapse()

Implement this callback if you want to know then the user has closed down an Ad that was displayed modally.

Handling Interstitial Ad Events in Objective-C or Swift Code

You can also handle events for interstitial events via callback functions that are implemented by AmazonAdInterstitialDelegate

interstitialDidLoad()

Implement this callback if you want to do something after the interstitial Ad has loaded successfully.

interstitialDidFailToLoad()

Implement this callback if you want to do something when the interstitial Ad has failed to load. Typically you would process the error code and act accordingly.

interstitialWillPresent(), interstitialDidPresent()

Implement these callbacks if you want to do something just before or after the interstitial Ad is displayed.

interstitialWillDismiss(), interstitialDidDismiss()

Implement these callbacks if you want to do something just before or after the interstitial Ad is removed from the display.

It’s worth checking out this article about event tracking and error handling. It describes how you hook into the events in Objective-C code but it’s also still very relevant for apps that have been written using Swift. Also, it’s worth stepping through the sample code so that you are clear on when the events are received.

Conclusion

It’s easy to integrate the Amazon Mobile Ads API into your iOS app or game. Doing so provides you with additional ways in which you can monetize via ads relating to products or services that come from Amazon or other well-known brands. Once you have integrated the API, you are paid for ads on impressions rather than on clicks.

Here are some more links to useful articles on using the Amazon Mobile Ads API in your iOS app:

• Mobile Ads for iOS
• Mobile Ads iOS API Concepts
• Mobile Ads FAQ
• Quick Start Guide for iOS
• Event tracking
• Using the Amazon Mobile Ads API with other advertising SDKs

That’s it for now. In my upcoming blogs I will discuss how you can use the Amazon Mobile Ads API in games or apps created using various frameworks, as well as provide guidelines on Ad mediation and best practices when including Mobile Ads in your app or game.

Simon Howard (@SimonH109)