IOS SDK

Contents 1 About the SDK 2 Setup Guide 2.1 Setting up 2.2 Integrating 3 Reference Guide 3.1 The Sample Project 3.2 Configuration Files 3.3 Multiple Slot Identifiers 3.4 ADFBannerViews 3.4.1 Creating 3.4.2 Refreshing 3.5 Adding Multiple Custom Dictionaries 3.6 Banner Actions 4 Appendix: Adding frameworks using Xcode 3 5 Appendix: Contents of Adfonic’s iOS SDK Folder

About the SDK

Adfonic’s iOS SDK supports iPhone, iPod Touch and iPad development on all Apple devices running iOS 4.3 or above.

Setup Guide

This Setup Guide explains how to get started with the Adfonic iOS SDK. It takes you through adding the required frameworks, requesting a test ad and then requesting a live ad.

After following these steps, please refer to the Reference Guide below which explains how to use the sample Adfonic project, and how to customise your project.

Setting up

Follow these steps to set up your Adfonic iOS project:

1. Open your project and add frameworks

Follow these steps to add frameworks using Xcode 4 (Refer to the alternative instructions if you’re using Xcode 3.):

1. Open your project
2. Click Show Project Navigator.
3. In the navigation bar, click your project.
4. At the top of the large central window, click the Build Setting tab.
5. In the search bar at the top of the screen, search for Other Linker Flags.
6. When you have located this setting, make sure it contains these values:
   • –all_load
   • –ObjC
7. Click your project in the navigator.
8. In the Targets list, click the target that is using the Adfonic library.
9. Click the Build Phases tab.
10. Expand the phase ‘Link Binary With Libraries’.
11. Click the plus button.
12. Find CFNetwork.framework
13. Click Add
14. Repeat steps 11 to 13 above for the following frameworks:
    • CoreLocation.framework
    • CoreMotion.framework
    • CoreTelephony.framework
    • EventKit.framework
    • libsqlite3.dylib
    • libz.dylib
    • MediaPlayer.framework
    • MessageUI.framework
    • MobileCoreServices.framework
    • QuartzCore.framework
    • SystemConfiguration.framework
    • AdSupport.framework (new for version 2.2.3)

2. Download the iOS SDK and unzip it

3. Drag the Adfonic folder from the unzipped SDK into your project

4. Compile and run

Integrating

Follow these steps to integrate Adfonic ads into your project.

1. Create a Banner View

A banner view is a portion of your app’s screen that you reserve to display advertisements.

Before you create a banner view, the following must be in place:

• You have imported Adfonic.h
• You have a property called BannerView of type ADFBannerView
• The class you’re in implements the ADFBannerView delegate protocol

To create a banner view, you use the Adfonic library to create instances of the ADFBannerView class. This automatically loads and displays banners.

There are many different approaches to creating a banner view. Here is one example of code:

    // Create a banner view using the default slot identifier from the configuration file.
	ADFBannerView * bannerView = [ADFBannerView bannerViewWithType: nil];
        ADFRequest * request = [ADFRequest requestForType: nil];
    // Become the delegate of the banner
	self.bannerView.delegate = self;
    // Add the banner to the view
        // Uncomment the line below if using the bannerViewDidLoadAd callback
   	//self.bannerView.hidden = YES;
   	[self.view addSubview: self.bannerView];	
    // Finally, load the request
   	[self.bannerView loadRequest: request];

- (void)bannerViewDidLoadAd:(ADFBannerView *)banner 
{
   	self.bannerView.hidden = NO;
}

Please note that this is just sample code for creating a banner view. For more information on using configuration files, for example to provide more information about your audiences for better targeting, refer to the ADFBannerViews section of the Reference Guide below.

2. Compile and run your project

You should now see a test ad.

3. Obtain your unique Ad Slot ID

1. Sign up for an account on the Adfonic website
2. Add your app
3. Find your unique Ad Slot ID at the Ad Integration page
4. Replace the test ID in your project’s plist. The test ID has the format 22222222-2222-2222-2222-222222222222

4. Request a live ad

After you compile and run your app with the unique Ad Slot ID, you will see the pending approval ad.

This is because we approve your app before it can receive live ads, to ensure that we maintain quality standards that protect developers, publishers and advertisers alike.

This usually happens within one business day and we will notify you by email when it is approved.

Reference Guide

This section explains how to use older versions of Xcode, how to use the sample Adfonic project, and how to customise your project.

Before using the Reference Guide you must already have set up your project, as explained in the Setup Guide.

The Sample Project

The Adfonic iOS SDK contains a sample Xcode project, called Ad Gallery. This is a stand-alone project, demonstrating how you can integrate Adfonic banner views into your projects.

You can use it as a basis from which to create your own projects.

Configuration Files

To enable the advertising banners to identify your app and configure themselves, your app bundle must have a property list called AdfonicConfigurations.plist

The configuration property list must have at least two keys:

• adSlotId: Your Adfonic ad slot identifier. You can obtain your slot identifiers from your Adfonic account.
• sizeIdentifier: The size identifier associated with your slot identifier. The value you assign to this string depends on the banner size, as shown in the table below.

Banner size up to	String value
320 x 50	iphonePortrait
300 x 250	mpu
728 x 90	leaderboard
120 x 600	skyscraper
468 x 60	banner
[TBC]	interstitial

When you create a new banner by calling method +bannerViewWithType: with a nil argument, these values are used for configuring the banner.

Key	Type	Value
sizeIdentifier	String	iphonePortrait
adSlotID	String	22222222-2222-2222-2222-222222222222

When using these configuration dictionaries, you don’t necessarily have to define new slotIdentifiers. You can just define additional properties that override the default values.

For example, a magazine app might use the same slot identifier for ads in its news page as the one used in its sports page. To customise the banner, it is sufficient to create configuration dictionaries that define the necessary tags. Note, however, that the type property should be uniquely set for each dictionary.

Here is an example of tag definitions:

Key	Type	Value
sizeIdentifier	String	iphonePortrait
adSlotID	String	abcdef-c4a5-4c6f-8d4a-0629eeb0e85a
Slots	Array	(2 items)
item 0	Dictionary	(4 items)
sizeIdentifier	String	Mpu
adSlotID	String	123456-9d55-415e-b28c-bbb1199e93a7
Tags	Array	(3 items)
Type	String	Ipad
item 1	Dictionary	(3 items)
allowLocationLookup	Boolean	YES
Tags	Array	(3 items)
item 0	String	tennis
item 1	String	Golf
item 2	String	sports
Type	String	sports

Multiple Slot Identifiers

You may want to use more than one slot identifier in one app.

In this case, you can add another property to the configuration file with key slots. The value for slots must be an array of dictionaries. In each of the dictionaries, you can set the adSlotID and sizeIdentifier of your other banners.

To identify these configuration dictionaries, each of them should have a type property.

The value of type can be any non-empty string.

To create a banner with a specific configuration, you pass its type as the argument when calling +bannerViewWithType:

Note that the value for type of each dictionary must be unique.

Key	Type	Value
sizeIdentifier	String	iphonePortrait
adSlotID	String	abcdef-c4a5-4c6f-8d4a-0629eeb0e85a
Slots	Array	(1 item)
item 0	Dictionary	(3 items)
sizeIdentifier	String	mpu
adSlotID	String	123456-9d55-415e-b28c-bbb1199e93a7
Type	String	iPad

ADFBannerViews

Whereas the Setup Guide takes you through creating a standard banner view, if you provide more information about where the banner will be used, and who will be viewing it, then you can improve the ad targeting. This will both enhance the experience for the user, and potentially yield higher revenue from your app.

Creating

You create banner views by calling +bannerViewWithType:

You can pass nil as the parameter to use the default banner setting from the configuration file.

The Configuration Files section above shows the values you can pass to this function.

The banner view is sized according to your configuration, and will take all other configurations from the configuration file. If you don’t specify a size, the default is automatically used.

After creating a banner view, you can use it like any other view. The banner view will automatically start loading and displaying advertisements.

WARNING: You must never change the size of banner views manually, nor must you subclass ADFBannerView.

Refreshing

By default, the banner view will load a new advertisement based on the value of its bannerViewAutorefreshTime property.

You can change the frequency of automatic refresh by changing this property. To stop automatic updates, you can set it to zero.

You can also explicitly request a refresh by calling -refresh. Note that this doesn’t guarantee an update. For example, the request might be rejected if the current advertisment has been on display less than +minimumRefreshTime, or there’s no network connectivity.

See the implementation of the App Delegate, which demonstrates how banner views can be used.

You can supply this information by either including additional properties in the configuration file, or by directly setting the properties of a banner view. The properties you can include in the configuration files are described below.

In addition to the required properties described in Configuration Files, you can add the following properties to Adfonic's configuration file:

Property	Comment	Values
isTest	Whether the banner is in test mode.	Boolean YES during development, or NO for shipping apps.
colorScheme	The background colour for serving enhanced text ads on high-end devices.	A string equal to blue, green, orange, purple, red, or yellow.
ageLow, ageHigh	The age range for the app’s users.	Integer values.
allowLocationLookup	Whether the user’s location is submitted to the server. Note that Adfonic’s library will only submit location information if all three of the following conditions are met: allowLocationLookup is set to YES; the user has explicitly granted location access to the app; and the system already knows the location, for example because another app requested it.	Boolean YES to submit the location, NO to ignore it.

Adding Multiple Custom Dictionaries

As discussed in Configuration Files, you can include multiple slotIdentifiers by adding dictionaries to the slots array property.

Banner Actions

When a user taps on a banner, it can perform an action to enrich the user's advertising experience. For example, it may play a video, or open a full-screen interactive ad.

Your app can provide a delegate for each banner view to be notified when these banner events occur. Your delegate must conform to ADFBannerViewDelegate protocol.

Any time a banner wants to perform an action, it calls bannerViewActionWillBegin:willLeaveApplication: method of its delegate (if implemented).

Your app should prepare itself for the banner action. For example it could save changes, or pause any activity.

After the banner action is completed, its delegate's -bannerViewActionDidFinish will be called.

Appendix: Adding frameworks using Xcode 3

Follow these steps to add frameworks to your project using Xcode 3:

1. Click Show Project Navigator.
2. In the navigation bar, click your project.
3. At the top of the large central window, click the Build Setting tab.
4. In the search bar at the top of the screen, search for Other Linker Flags.
5. When you have located this setting, make sure it contains these values:
   • –all_load
   • –ObjC
6. In the navigation bar, right-click Frameworks.
7. In the context-sensitive menu that appears, click Add.
8. In the secondary menu that appears click Existing Frameworks.
9. In the list displayed, click the following frameworks so that they are highlighted:
   • CFNetwork.framework
   • CoreLocation.framework
   • CoreMotion.framework
   • CoreTelephony.framework (if your app supports iOS versions before 4.0, you can add this as an optional framework)
   • EventKit.framework
   • libsqlite3.dylib
   • libz.dylib
   • MediaPlayer.framework
   • MessageUI.framework
   • MobileCoreServices.framework
   • QuartzCore.framework
   • SystemConfiguration.framework
   • AdSupport.framework (new for version 2.2.3)

You can now return to the Adfonic iOS Setup instructions.

Appendix: Contents of Adfonic’s iOS SDK Folder

In the SDK zip file, there is a folder called Adfonic SDK which contains all you need to use the Adfonic library:

• libAdfonic.a is the static library of the SDK. Make sure the library is added to all targets that intend to use it.
• ORMMA.bundle contains resources used by the library, and must be added to your project.
• The rest of the files in the directory are the header files of the library. Add this directory to your Xcode project.