LARSAdController

Lightweight Mobile Ad Mediation for iOS

Description

LARSAdController 3.0 is a singleton ad management class that manages ad classes that conform to the LARSAdAdapter protocol. Ads are managed in a way that most closely adheres to best practices for ad networks using a single instance for each ad network in order to provide the best publishing platform for advertisers to maximize ad inventory based on your particular needs. Currently there are two adapters available (iAd and Google Ads). The adapters can be extended to any ad framework wanted.

Installing

Cocoapods

The absolute easiest way to integrate the code into your project is to use Cocoapods to include the source in your project. If you need more detailed instructions or choose not to use Cocoapods, check out the project homepage.

To use Cocoapods with LARSAdController, simply create your new Podfile and include the following dependency:

platform :ios, '5.0'

pod 'LARSAdController', '~> 3.0'

This will tell cocoapods to include all LARSAdController components of any version in v3.x. You will get the latest revision that cocoapods has in it's repository whose major revision is 3.x.

Subspecs

If you are only interested in iAds or GoogleAds, but not both, you can specify that you would only like to have one or the other using the following in your Podfile:

platform :ios, '5.0'

pod 'LARSAdController/iAds', '~> 3.0'
pod 'LARSAdController/GoogleAds', '~> 3.0'

If you only need the core files without any ad adapters, then your Podfile will look something like this:

platform :ios, '5.0'

pod 'LARSAdController/Core', '~> 3.0'

Other Requirements

  1. iOS 5.0+
  2. Xcode 4.3+ - LLVM 4.0 support. Objective-C container literals are used.

Usage

Back in the days of yore, LARSAdController 2.0 forced you opt-in to rotation-handling. This is no longer necessary as the ad management class will auto-detect your current orientation given that the current view controller that the ad container lives in is correctly setup.

The first step is to register your ad classes that the ad manager will use. The ad networks take priority in the order they were added in, so the first network registered is the highest priority, the second is below that, and so on:

In app delegate or somewhere else convenient before first banner is needed to display:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions{
    [[LARSAdController sharedManager] registerAdClass:[TOLAdAdapteriAds class]];
    [[LARSAdController sharedManager] registerAdClass:[TOLAdAdapterGoogleAds class] withPublisherId:publisherId];
}

Then the only line of code you need in your view controller is to add the container to your view using either of the following in viewWillAppear::

[[LARSAdController sharedManager] addAdContainerToView:self.view withViewController:self];

or the simpler version:
[[LARSAdController sharedManager] addAdContainerToViewInViewController:self];

Once the current highest-priority ad network fails to obtain an ad, it will continue to wait for an ad while the next-highest priority ad network is allocated and sends a request. Once the ad network in priority above this network obtains an ad again, it will hide the lower-priority ad banner, clean it up and display the higher-priority network banner.

Ultra-Lazy Implementation

To make your life even easier, all you need to do is have each of your view controllers that you would like to have an ad pinned to the top or bottom of your view controller's view is to have your view controller subclasses inherit from TOLAdViewController. This will automagically add an ad view container to your view controller's view when it is supposed to. The only downside is less flexibility on ad placement in your view hierarchy.

@interface MYBestViewController : TOLAdViewController
//BOOM - Ads
@end

Conditionally Displaying Ads

If you'd only like the ads to be displayed under certain conditions (like when a user has purchased a certain in-app upgrade), then simply override -shouldDisplayAds in your TOLAdViewController subclass. Ads will not be loaded on viewWillAppear: if shouldDisplayAds returns NO:

- (BOOL)shouldDisplayAds{
  return ([self.purchaseTracker hasPurchasedUpgrade] == NO);
}

Ad Placement

In the past, you were only able to add a banner view to the bottom of a view and have it animate in from the bottom. Now, you are able to not only control whether it resides at the top or bottom of your view, but control how it animates in and out of the screen.

Two new properties are available on LARSAdController:

@property (nonatomic) LARSAdControllerPresentationType presentationType;
@property (nonatomic) LARSAdControllerPinLocation pinningLocation;

The options for presentationType are as follows. These options will slide the ad banner in and out from the direction indicated in the enum:

typedef NS_ENUM(NSInteger, LARSAdControllerPresentationType){
    LARSAdControllerPresentationTypeBottom = 0,
    LARSAdControllerPresentationTypeTop,
    LARSAdControllerPresentationTypeLeft,
    LARSAdControllerPresentationTypeRight
};

These options will pin the ad view container to the bottom (default) or top of the view you specify and layout the banner inside the container accordingly:

typedef NS_ENUM(NSInteger, LARSAdControllerPinLocation){
    LARSAdControllerPinLocationBottom =  0,
    LARSAdControllerPinLocationTop
};

Currently Available Ad Network Adapters

  1. iAd - TOLAdAdapteriAds
  2. Google Ads - TOLAdAdapterGoogleAds

Planned Ad Network Adapters (Not Yet Implemented)

  1. House Ads - Display your own image with an action for a banner
  2. Developer Ads - Display auto-generated banner ads for all of your apps with a single line of code

Creating a New Ad Network Adapter

In order to create a new ad adapter for an ad vendor not already created, simply create a new NSObject subclass that conforms to the LARSAdAdapter protocol. There are a few required methods and properties that must be present in order for the adapter to function, as well as some optional ones that give some additional control/functionality of an ad banner. More detailed documentation can be found in the header file for LARSAdAdapter.h.

A good start would be to simply conform to the LARSAdAdapter protocol, compile, and let all of the warnings, errors, and runtime asserts help you complete the implementation:

@interface LARSAdControllerHouseAdsAdapter : NSObject <LARSAdAdapter>
  //fill out the meaty part  
@end

Apps Using LARSAdController

If your app is using LARSAdController, and you'd like to be included in this list, please let me know either on twitter or by submitting a pull request with your app added to the README.