Posted: 20th Aug 2013 00:49
Edited at: 20th Aug 2013 01:02
* This is a pretty long tutorial but the main process is very simple; I am including as much detail as I can for clarity. *
AGK V1 BASIC only supports Admob or Inner-Active advertisements. However, many times it is beneficial to include multiple ad networks so that if one network cannot fill a request another source will be used. Depending on your device, some ad networks will tend to have higher CTR/eCRM and higher payouts per click.
One feature that many are not very familiar with is ad network mediation. Google recently revamped its entire Admob service and now provides a very diverse and powerful mediation service with very little extra work required. This approach is compatible with the existing version of AppGameKit and allows you to effortlessly implement multiple ad networks into your apps. Each ad network can be customized to determine how often it is used in relation to the rest. For instance, I just implemented iAds and Admob into an iOS app, with iAds taking priority due to higher eCRM I've experienced in other apps. When no iAd advertisement is available, an Admob ad will load instead.
Below are the basic steps required to get ad mediation up and running in your AppGameKit products. I explain in relation to iOS, but it is very similar on Android and I try to describe that process as well when necessary. You won't be able to use iAds on an Android device, but can use other networks.
Configuring Admob Mediation for an App
The first steps will be to create your Admob account, add the app(s) that you wish to enable ads for, and specify the ad networks and settings you wish to use.
1.) Make sure you are registered at [href=http:/apps.admob.com/]http:/apps.admob.com/[/href] -- if you have an existing Admob account Google will provide a link on this site to migrate all of your existing Admob data to their new service (in house ads will need to be recreated).
2.) Click on the Monetize button at the top of the page. If you have not yet added your app for Admob support, click the "Monetize New App" button and follow the instructions. If the app is already on the market (Google Play or iTunes) you can search for it, otherwise click the "Add your App Manually" tab to specify the details manually. On the next screen, select "Banner" for the format, indicate the refresh rate (I recommend 45 or 60 seconds), specify any other customization options and then give the ad unit a name for identification within Admob. Then click Save.
3.) Once the app has been added through Admob, you can select it from the Monetize page by clicking "All Apps" and selecting the desired app. After selecting the app, click on the "Edit Mediation" link to customize ad network options.
4.) Admob is the default ad source and you cannot disable it. To add an additional ad network, such as iAds, click the "New Ad Network" button. Then, click the ">>" button next to the ad network(s) you wish to include. Google supports over 20 ad networks. In this example, I will select "iAd". Depending on the network, you may be asked to provide an ID for that specific ad network before continuing--this is a code you will get after registering your app at each external ad network you wish to use. iAds do not require any such parameters so you can add them right away.
5.) Now specify the eCRM weight you wish to give each enabled ad network. The higher the number, the more frequently that ad network will be called. In my example, I have Admob and iAds. So I give iAds an eCRM of $3 and Admob an eCRM of $1 (this is an arbitrary number to give priority to iAds and is not necessarily the actual eCRM) and then press Save.
6.) Finally, take note of the Ad Unit ID for the newly created app. You can get this ID by clicking on the corresponding app under "All Apps" as described in step #3. The new format of this code will be similar to: xx-app-pub-################/########## - This code will be added into your AppGameKit app.
Preparing the AppGameKit Framework
The included Google Admob libraries with AppGameKit are out-of-date. To enable full support for ad mediation, you will want to download the latest Google Admob SDK.
1.) You can download a the SDK for Android and for iOS at [href=https:/developers.google.com/mobile-ads-sdk/download]https:/developers.google.com/mobile-ads-sdk/download[/href]. Grab the right SDK for you (i.e., if you will only be releasing your app on iOS, you only need to download the iOS version).
2a.) iOS Admob SDK: Delete all of the existing files from IDE\platform\apple\Source\Social Plugins\GoogleAdMobAdsSDK and copy the contents of the ZIP to this directory. Also copy the "Mediation" folder over (from within the "Add-ons" directory).
2b.) Android Admob SDK: Delete the GoogleAdMobAdsSdk-6.1.0.jar file from within each Android project 'libs' directory (e.g., IDE/apps/interpreter_android_prebuilt/libs). Copy the latest jar file from the downloaded SDK to the same directory (e.g., GoogleAdMobAdsSdk-6.4.1.jar). There are five different Android project directories that include this lib.
(When working with Android, you will also have to go to Project Properties > Java Build Path > Libraries and remove the old SDK reference and add the new one in its place.)
Adding the Code to your AppGameKit BASIC Project
Now that your app's Admob information has been configured on Google's website and the SDK has been updated within AppGameKit, it's time to add the simple commands to call up the ads.
1.) During the initialization of your game (or wherever you'd like) set the Admob details using the Ad Unit ID you obtained in part 1:
SetAdmobDetails("xx-app-pub-################/##########")
2.) When you wish to create an ad, do so using the following command (the first parameter must be 0, the second and third indicate horizontal and vertical placement--centered at bottom in this case--and the final parameter allegedly toggles test ads if set to 1):
CreateAdvert(0, 1, 2, 0)
3.) You can hide or show the ads at any time using SetAdvertVisible(1) (this will show the ad) or SetAdvertVisible(0) (this will hide the ad).
4.) You can manually call a new ad at any time by calling RequestAdvertRefresh(). It is easy to set up a timer to refresh the ads every so many seconds, but you should never refresh more than once every thirty seconds and the ads by default should update the duration specified in the mediation settings.
Building the Final App and Adding Ad Network Adapters
The final series of steps is to include the necessary libraries and adapters to support whichever ad network(s) you wish to support alongside Admob. This process varies depending on the ad network and whether you are building for Android or iOS.
To start, follow the usual procedure for preparing your Tier 1 BASIC app for publishing. The full process is beyond the scope of this guide. In brief, this involves using Eclipse if exporting for Android, or Xcode if exporting for iOS. The included template projects for iOS and Android (IDE/apps/interpreter_android_prebuilt for Android, IDE/apps/interpreter_ios for iOS) are meant to be copied and renamed to reflect your project. The Android template includes a Readme file with more specific steps (make sure to also import the Facebook project into your Eclipse workspace). The iOS template is straight forward except you need to delete the FacebookSDK.framework folder and re-extract FacebookSDK.framework.zip within IDE\platform\apple\Source\Social Plugins\FacebookSDK (as explained by the Readme in this directory).
iAds: To enable iAds, you must enable the iAd Network through iTunes Connect before uploading your app's binary. To do this, you will first need to create an editable entry for your app (or a new version of the app if it already exists) through the "Manage Your Apps" section of iTunes Connect. Once you have an app entry created (just the meta data, not the binary), go to the app's main iTunes Connect page and click "Set Up iAd Network". Follow the simple on-screen instructions to enable iAd Network for the next version of the app.
1.) Visit [href=https:/developers.google.com/mobile-ads-sdk/docs/admob/mediation-networks]https:/developers.google.com/mobile-ads-sdk/docs/admob/mediation-networks[/href] - This site includes brief instructions and download links to the necessary SDKs and Admob adapters for each of the supported ad networks. You will need to download the import the necessary SDKs, libraries and adapters into your app for each ad network you wish to include. You'll also have to ensure you've established an account and configured your app for each ad network service as mentioned earlier in this guide. Google provides links to guides on how to do this for most of the ad networks.
2.) In the case of iAds (only available on iOS), you only need to download the iAd Adapter from the link mentioned previously. In Xcode, you will need to include the iAd framework and import the libAdapterIAd.a into your project (making sure that your app is selected as the target).
Again, each ad network has its own SDK and required frameworks and Admob adapters, so refer to the link above for specific details. Once you have gone through the process of implementing one, you should be comfortable implementing others.
Now, when you compile and run your application you should see a mix of all ad networks you have enabled and properly configured. Check the console logs to see if there are any problems. For instance, if you do not include the iAd adapter from Google, you will see a warning that the adapter could not be found when you run the app, and only Admob ads will be served. When viewing iAd advertisements before the app has been approved and published, only test ads will appear.
One limitation of AGK's current Admob implementation is that it only supports 320px wide banner ads. A much more versatile solution would be to support other banner sizes including smart banners. Smart banners are supported by iAd and Admob and stretch the ad across the width of the device in either portrait or landscape, making them much more appealing especially on tablets. It is a simple configuration option of Admob but one that we do not have direct access over in Tier 1. I hope this will become configurable in future versions of AGK.
Please post if you have any questions... I hope you find this helpful!
