Tutorial 29 - Codea v1.5.2: Objective C Add On, iAds

Figure 0. Codea implementing iAds - showAdFromTop()

29.1 Overview

CodeaAddon is an experimental protocol for adding native extensions to exported Codea projects. You must deal with Lua directly to register your functions and globals. This protocol should be considered alpha and is subject to change in future Codea releases.

With that disclaimer out of the way, let's have a look at what we can do with this new functionality. We have previously done tutorials to add Game Center and iAd functionality using the old runtime but with the great new export to Xcode functionality, this is no longer the best way to skin that particular cat.

You may want to re-read our previous tutorial on implementing iAds in Codea as we won't cover the same background in this tutorial.

We will build on the previous tutorial which uses the audio add on. This has the added benefit of showing how you can stack a number of add ons to the same project.

Note that before you start adding advertising support to your applications available on iTunes, you must first agree to the iAd Network agreement. Further, you must explicitly enable iAd for each application in iTunes Connect. As a part of the iAd Network, you control the kinds of ads that are delivered to your application. We don't need to do this to test it in the simulator though.

Figure 1. Add the iAd Framework to your App

29.2 Add the iAd Framework to your App

Fire up Xcode and load the exported version of your Codea application (See Tutorial 27). Click on the imported project file at the top of the project navigator then in the Build Phases tab, scroll down to the link binary with libraries area and select the drop down arrow. Click on the "+" button below your existing frameworks to add a new framework. Find iAds and click on "Add" (Figure 1).

29.3 Update the AppDelegate Files

In the AppDelegate we need to register our new add on classes. The new AppDelegate.h file now looks like:


//
//  AppDelegate.h
//  AudioDemo
//
//  Used to demonstrate the audio add on and iAds add on libraries
//
//  Created by Reefwing Software on Sunday, 14 April 2013
//  Copyright (c) Reefwing Software. All rights reserved.
//

#import <UIKit/UIKit.h>
#import "AudioAddOn.h"
#import "IAdsAddOn.h"

@class CodeaViewController;

@interface AppDelegate : UIResponder <UIApplicationDelegate>

@property (strong, nonatomic) IAdsAddOn *iAdsAddOn;
@property (strong, nonatomic) AudioAddOn *audioAddOn;
@property (strong, nonatomic) UIWindow *window;
@property (strong, nonatomic) CodeaViewController *viewController;

@end


And similarly to what we had in the previous tutorial AppDelegate.mm now looks like:


//
//  AppDelegate.mm
//  AudioDemo
//
//  Created by Reefwing Software on Sunday, 14 April 2013
//  Copyright (c) Reefwing Software. All rights reserved.
//

#import "AppDelegate.h"
#import "CodeaViewController.h"

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];
    self.viewController = [[CodeaViewController alloc] init];
    
    //  Create and add our AudioAddOn to Codea
    
    self.audioAddOn = [[AudioAddOn alloc] init];
    [self.viewController registerAddon: self.audioAddOn];
    
    //  Create and add our iAdsAddOn to Codea
    
    self.iAdsAddOn = [[IAdsAddOn alloc] init];
    [self.viewController registerAddon: self.iAdsAddOn];
    
    NSString* projectPath = [[[NSBundle mainBundle] bundlePath] stringByAppendingPathComponent:@"AudioDemo.codea"];
    
    [self.viewController loadProjectAtPath:projectPath];
    
    self.window.rootViewController = self.viewController;
    [self.window makeKeyAndVisible];
    
    return YES;
}

- (void)applicationWillResignActive:(UIApplication *)application
{
}

- (void)applicationDidEnterBackground:(UIApplication *)application
{
}

- (void)applicationWillEnterForeground:(UIApplication *)application
{
}

- (void)applicationDidBecomeActive:(UIApplication *)application
{
}

- (void)applicationWillTerminate:(UIApplication *)application
{
}

@end

29.4 The iAds Add On

Our iAds add on implements two internal booleans, isBannerVisible and showBannerFromTop. Hopefully the use of these should be fairly obvious. We also register three new functions for use within Codea:

1. showAdFromTop();
2. showAdFromBottom(); and
3. hideAd()

Our example project demonstrates the use of all 3 of these functions. We start by displaying Ads from the top of the page (once the ad has been loaded from the ad server). We hide ads when the play button is tapped and then show them from the bottom when the stop button is tapped.

In the simulator apple will send you ad errors regularly (e.g. Ad inventory unavailable) to make sure that your code can handle this. Your app will get rejected if it displays an empty ad banner so the add on takes care of this situation. When displaying the ad banner, it will slide down from the top or up from the bottom depending on which function that you have used. Similarly hideAd() will animate the ad sliding above or below the screen depending on the state of the boolean showBannerFromTop.

Figure 2. Codea implementing iAds - showAdFromBottom()

This example add on only handles ads for an iPad in portrait orientation. We have included device detection macros in IAdsAddOn.h, just remove the comment slashes if you want to use these to position your Ads. To handle different orientations and devices update the banner view frame variables in the two methods:

1. - (void)showBannerViewAnimated:(BOOL)animated; and
2. - (void)hideBannerViewAnimated:(BOOL)animated.

If you don't want the banner views to slide to the new position then set animated = NO for the above two methods.

29.5 Download the Code

The complete code listing is available below.