How to Integrate AdWhirl into a Cocos2D Game

This is a blog post by iOS Tutorial Team member Ibrahim Kteish, a student inspired by the iPhone with a passion for creating iOS software, and the cofounder of istockplus.com.

Learn how to get a high fill rate with ads in your game with AdWhirl!

Learn how to get a high fill rate with ads in your game with AdWhirl!

If you want to make an ad-based game, your first thought might be “well, I’ll just enable iAd!” Although iAd is a great ad network (and definitely easy to integrate, since it’s built into iOS), if you try it out in practice you’ll notice very low fill rates.

This means that often when you want to display an ad, there won’t be an ad available, and so you’ll get less money than you potentially might have otherwise. And since the goal is to make money, obviously this isn’t ideal!

This is where an ad mediation framework like AdWhirl comes to the rescue – and that’s the focus of this tutorial!

AdWhirl is a free, open source tool that allows developers to serve ads from any number of Ad networks you have accounts on, as well as your own house ads (to run your own ad campaigns and cross-promote your apps), via one simple client SDK.

By utilizing multiple ad networks and Switch ad networks on the fly, you can select which ones perform best for your app and ensure you have a high fill rate. Note AdWhirl won’t “mediate” your payments, the payments will be made by each network you’ve signed on.

In this tutorial, we will show you step-by-step how to get started with AdWhirl, and integrate it into one of the Cocos2D tutorials from this site. If you follow along, you’ll be all set up with AdWhirl and ready to integrate it into your own apps or games!

AdWhirl: An Overview

The way AdWhirl works is you configure a number of ad networks which you want to serve ads, and AdWhirl chooses one to serve an ad for you, based on your preferences and ad availability.

To configure AdWhirl to use an ad network, you have to create an account on that network. You also have to integrate that ad network’s SDK into your project.

AdWhirl supports a huge array of ad networks (currently 17 at the time of writing this article!), and we could set up AdWhirl to use all 17 networks, but then this tutorial would take forever!

So for the purposes of this tutorial, we are just going to configure AdWhirl to use two ad networks:

• iAd. iAd is Apple’s built-in advertising solution. You might have read about it already in our How To Integrate iAd into your iPhone App tutorial. iAd is great, but its fill rate is often low. So when it’s not available, AdWhirl can help with that by serving ads from another provider such as AdMob.
• AdMob. AdMob is one of the world’s largest mobile advertising platforms and claims to serve more than 40 billion mobile banner and text ads per month across mobile Web sites and handset applications. Their rates are generally not as high as iAd, but they have more ads available.

Before we do anything with AdWhirl, we need to enable iAds for our app, and set up an AdMob account. So let’s get started!

Enabling iAds for your App

In order to receive iAds in your app, you need to enable the iAd service for your app in iTunes Connect via the following steps:

1. Log onto the iOS Developer Center, go to the iOS Provisioning Portal, and create a new App ID for your app. We’re going to be integrating AdWhirl into a space game in this tutorial, so you might want to name it something like “com.yourdomain.spacegame.”
2. Log onto iTunes Connect and create a new app, choosing the App ID you just created. Just enter placeholder information for now until you get to the “waiting for upload” stage. Don’t worry you can change all this info later, we just have to create an enter to make iTunes Connect happy for now.
3. Once you’ve created your app’s entry, open it up in iTunes Connect and click “Set Up iAd Network”, as shown below:

4. Finally you must specify whether your audience is under 17 years of age, as shown in the following screenshot. This helps target your ads more appropriately for your age group.

Click the Enable iAds button and Save. The only other thing you have to do is go to the Contracts & Banking module in iTunes Connect, and accept the iAd network agreement if you haven’t already.

Creating an AdMob Account

Next, we will create an account for the AdMob network. Go ahead and visit the admob.com and click on Get Started:

Second, follow the steps to create an account by filling in the info and accepting the terms of service. When you’re done you should see a page like this:

Next, we need to create a new app in order to get a Publisher ID that we need for AdWhirl.

To do this, click on the Sites & Apps tab, and select the Add Site/App button from the dropdown. It will prompt you to enter your payment details, as you can see in the screenshot below:

Once you’ve entered your payment details, choose iPhone app from the next page:

A dropdown will appear to allow you to enter some additional information on your app. Enter the information as shown below, and then click continue:

You will then arrive at a screen where you can download the AdMob SDK. Be sure to download this, because you’ll need the SDK later on in this tutorial.

Now we just need to get the Publisher ID for the new app we created. To do this, click the “Go to Sites/Apps” button, scroll down to your new Space Game entry, move your mouse over it so the “Manage Settings” button appears, and click that button.

Finally, you will see your Publisher ID toward the top of this information sheet! Copy this down, as you will need it later in this tutorial.