IPhone SDK

From QuattroWiki

Contents 1 Implementing the Quattro iPhone SDK 1.1 Important Updates 1.2 What’s New in Quattro iPhone SDK Version 3.1.0 1.3 Deciding Which Version to Use 1.4 Implementing Your Code 1.4.1 Setting Up Your Project 1.4.2 Editing Your Code 1.4.3 Sample Autorotating Ad 1.5 QWAdViewDelegate Protocol 1.5.1 Required Methods 1.5.2 Optional Methods 1.5.3 Callback Methods 2 Using the Sample Application 3 For More Information

Implementing the Quattro iPhone SDK

Quattro offers an easy-to-use SDK to help you get ads up and running on your iPhone application. Simple ads can be displayed with only a few lines of code, and can be easily customized to fit your specific needs.

Important Updates

Quattro automatically supports the use of the MapKit framework to build ad units that depend on passing location information. If you determine that you need to turn off location support services in the Quattro Wireless Ad SDK based on the February 3 Apple App Store Submission Tip, or you have received feedback from the App Store Review team to disable this feature, please do the following:

Call void QWEnableLocationServicesForAds(BOOL on); with NO in your application or view loaded methods. Do this before any QW call to create an adView.

What’s New in Quattro iPhone SDK Version 3.1.0

The latest release of the Quattro iPhone SDK contains a number of changes:

• Enhancements for rich media ads: With the introduction of iPhone OS 3, the Quattro 3.x SDK is able to take advantage of new iPhone features such as in-place maps and new messaging APIs.
• Removal of the requirement to use the ObjC flag: This flag is no longer needed to implement the Quattro iPhone SDK and can be removed.
• Quattro iPhone SDK libraries no longer require libxml2.2: If you added it to your project to support the Quattro iPhone SDK, you should remove it. If you don’t remove it, applications compiled with the iPhone SDK OS 3.0 may not properly deploy on a 2.2 device.

Deciding Which Version to Use

You choose which version of the Quattro iPhone SDK to use based on:

• The Xcode base SDK for which you are targeting your application: The Xcode base is the version of the Apple OS framework in which your application is built, and defines the maximum set of features available for your application.
• The iPhone OS deployment target to support: The minimal iPhone OS on which your application can be deployed and run, and defines the minimum set of features required for your application.
• The iPhone OS versions to support: Applications built with iPhone SDK 2.2 will run on any device with OS 2.2 and greater but do not have access to the latest features of the device. Applications built for 3.x with a deployment target of OS 2.2 can run on the same set of devices, but will also have access to the enhancements that iPhone OS 3.0 provides when running on a 3.x device.

3.1.0 is the recommended option; however, you can use 2.1.0 if needed. Use the following table to decide which version best suits your needs.

Xcode Base SDK	iPhone OS Deployment Target	Supported iPhone OS Versions	Quattro SDK
2.2	2.2	2.2 up to 3.x	2.1.0
3.0	3.0	3.x	3.1.0
3.0	2.2	2.2 up to 3.x	3.1.0

If you are you are upgrading your Quattro iPhone SDK:

• In order to reach the greatest population of users while being able to host the richest ad content, upgrade to the 3.x version of the Quattro iPhone SDK. Set your application base SDK to 3.0 and deployment target to 2.2.
• If you need to operate on older 2.2.x variants of the iPhone OS, (with an Xcode base of 2.2) it is recommended to upgrade to Quattro iPhone SDK 2.1.0.

Quattro iPhone SDK libraries no longer require libxml2.2. If you added it to your project to support the Quattro iPhone SDK, you should remove it. If you don’t remove it, applications compiled with the iPhone SDK OS 3.0 may not properly deploy on a 2.2 device.

Implementing Your Code

To get going, you'll first need to setup your project in Xcode and then implement at least two methods on your controller. If you need help, there are also some examples below to show you more about what to do.

Once you’ve implemented your code, you can begin testing your site. When you're ready, you can request to go live by clicking the "Submit for Approval" tab in the Manage Sites area. If you have any questions, you can contact your Quattro Account Manager to assist you.

Setting Up Your Project

1. Get your SDK after you create or login to your account. When you get your SDK, note your Publisher Account ID and Site ID, as you'll need them during implementation.
2. When you unzip your package, there are two other zip files included. The contents of the zip files are identical except for the actual library files themselves; the sample sources and project files are the same. Choose the correct library files according to the table above. Add the appropriate libraries and headers to your project.
   

   
   

   
   

   
   

   The actual library names that you see are dependent on the OS you are targeting and the SDK version you downloaded.
   

3. If they aren't already there, add the SystemConfiguration, libsqlite 3.0, and CoreLocation frameworks, libz.dylib. The following frameworks are required for Quattro iPhone SDK versions 3.x and 2.0.x:

   
   

   

   
   

   If you are using Quattro iPhone SDK version 3.x, you also must add:

   
   

   

   
   

   Quattro iPhone SDK libraries no longer require libxml2.2. If you added it to your project to support the Quattro iPhone SDK, you should remove it. If you don’t remove it, applications compiled with the iPhone SDK OS 3.0 will not properly deploy on a 2.2 device.

4. Import the .h files into the view controller for the application view which will display ads. If you have more than one view to display ads, you can include these files in a common header as needed.
5. Using the values that you noted when you downloaded the SDK, define your Publisher Account and Site IDs in a common include file or inline as needed.
   

   
   

   

      CODE SNIPPET FOR COPY/PASTE
      //AD Support changes and defines
      #import "QWAdView.h"
      #import "QWTestMode.h"
      #define PUBLISHER_ID @"xxxxxxxxxxxxxx"
      #define SITE_ID @"xxxxxxxxxxxxxxxxx"

      //AD SUPPORT
      @synthesize bannerAd = _bannerAd;

Editing Your Code

1. Implement the protocol defined by QWAdViewDelegate in your view controller.

   

2. The QWAdViewDelegate methods provide your application with controls on what ads are served, display of ads, etc. At a minimum, you must implement the following two methods in your controller:

    - (void)adView:(QWAdView *)adView displayLandingPage:(UIViewController *)controller;
    - (void)adView:(QWAdView *)adView dismiss:(UIViewController *)controller;

This is a sample implementation of the two delegate methods:

     //REQUIRED FOR AD SUPPORT (Use your own delegate in place of SLSMoleculeAppDelegate)
     - (void)adView:(QWAdView *)adView dismiss:(UIViewController *)controller
     {
           SLSMoleculeAppDelegate *delegate = [[UIApplication sharedApplication] delegate];
           [[delegate rootViewController] dismissModalViewControllerAnimated:YES];
     }

     //REQUIRED FOR AD SUPPORT (Use your own delegate in place of SLSMoleculeAppDelegate)
     - (void)adView:(QWAdView *)adView displayLandingPage:(UIViewController *)controller
     {
           SLSMoleculeAppDelegate *delegate = [[UIApplication sharedApplication] delegate];
           [[delegate rootViewController] presentModalViewController:controller animated:YES];
     }

Sample Autorotating Ad

In this example, an ad is placed at the default top/center position, autorotating every 60 seconds. The following illustrates the initialization of the adView; note that a reference to the adView is retained since it must be properly cleaned up when no longer needed.

       -(void) viewDidLoad
       {
         //AD SUPPORT (everything added in this method)
         QWSetLogging(TRUE)
         self.bannerAd = [QWAdView adViewWithtype:QWAdTypeBanner
                                   publisherID:PUBLISHER_ID
                                   siteID:SITE_ID
                                   orientation:UIInterfaceOrientationPortrait
                                   delegate:self];
         [self.bannerAd setBackgroundColor:[UIColor blackColor]];
         self.bannerAd.textColor = [UIColor whiteColor];
         [self.view addSubview:self.bannerAd];
         self.bannerAd.displayMode = QWDisplayModeRotation;
         self.bannerAd.adInterval = 60.0;
         [self.bannerAd displayNewAd];
       }

When the adView is no longer needed, the reference to the delegate is first cleared, and then the adView resources are released.

       - (void) dealloc
       {
         //AD SUPPORT
         bannerAd.delegate = nil;
         [bannerAd release], _bannerAd = nil;
         [super dealloc];
       }

QWAdViewDelegate Protocol

The QWAdView communicates with its delegate through the QWAdViewDelegate protocol. The protocol has two required methods along with a list of optional methods that allow the application to provide information as well as react to certain important events throughout the life cycle of the QWAdView.

There are three things to keep in mind when implementing your QWAdViewDelegate methods:

• If you have set a delegate to QWAdView, then you must set the QWAdViewdelegate property to nil before releasing each QWAdView instance. This prevents any background threads from calling the delegate after it has been released and causing a crash.
• Make sure that any code executed inside your delegate method implementation is relatively quick. Many of these methods block further execution of ad requests until they return.
• Some of these methods are called from background threads. Therefore your method implementations need to be thread-safe and cannot communicate directly with classes that are required to run on the main thread only (i.e. UIKit user interface classes). If you need to interact with the main thread, make sure to use one of NSObject’s
  

  -performSelectorOnMainThread variances.

Required Methods

The following required delegate methods provide a view controller containing the web view for displaying an ad’s landing page. You need to add and remove this controller’s view to and from your application’s view hierarchy. This is normally done by passing the landing page controller to your UIViewController’s -presentModalViewController:animated: method.

- (void)adView:(QWAdView *)adView displayLandingPage:(UIViewController *)controller;

- (void)adView:(QWAdView *)adView dismiss:(UIViewController *)controller;

Optional Methods

This method allows you to provide a default ad or placeholder ad to be displayed before ads have been downloaded from the server or in cases when no ads are available:

-(QWAd *)defaultAd:(QWAdView *)adView;

This method is called when the device orientation changes. It lets the QWAdView web view know if it is allowed to change orientation:

-(BOOL)adView:(QWAdView *)adView 
	webViewShouldAutorotateToInterfaceOrientation: (UIInterfaceOrientation)interfaceOrientation;

Callback Methods

The Quattro iPhone SDK supports the callback methods listed here.

• This method is called just before rendering ads:

- (void)adView:(QWAdView *)adView willDisplayAd:(QWAd *)ad;

• This method is called immediately after rendering ads:

- (void)adView:(QWAdView *)adView didDisplayAd:(QWAd *)ad;

• This method is called just after the user clicks on the ad and before displaying the landing page:

- (void)adView:(QWAdView *)adView willFollowClick:(QWAd *)ad;

• This method is called after displaying the landing page:

- (void)adView:(QWAdView *)adView didFollowClick:(QWAd *)ad;

• This method is called just before closing the ad:

- (void)adView:(QWAdView *)adView willCloseAd:(QWAd *)ad;

• This method is called immediately after closing the ad:

- (void)adView:(QWAdView *)adView didCloseAd:(QWAd *)ad;

• This method is called when the ad request to the Quattro Ad Server returns an error. One of the error conditions include the case when no qualified ads are found at the time for a given publisher and site.

- (void)adView:(QWAdView *)adView failedWithError:(NSError *)error;

• This method is called when the prefetch request is completed:

- (void)adViewPrefetchCompleted:(QWAdView *)adView;

• This method is called before the SDK makes a network call to get a single ad:

- (void)willRequestAd:(QWAdView *)adView;

Using the Sample Application

If you like, you can look at some ads in action by using the sample application. When you do, make sure to choose the correct library files according to the operating system of the target device (OS 2.x or 3.x).

To see the sample application with ads:

1. Go into the sample application.
2. Edit Constants.h to use your own siteID and publisherID.
3. Pick the appropriate Active SDK (Simulator vs. real device, and the appropriate iPhone OS).
4. Click Build and Go.

For More Information

• Ad Request Configuration for iPhone
• iPhone Application Conversion Tracking
• Quattro iPhone SDK FAQs.
• Click here to log into your Quattro account for the latest SDK
• Quattro SDK License