IOS SDK
Contents |
Adfonic iOS SDK Integration
The Adfonic iOS SDK contains the code required to integrate Adfonic ads within your application.
The iOS SDK supports iPhone, iPod Touch and iPad development on all Apple devices running iOS 4.0 or above.
Getting Started
To get live ads in your app you just need to:
- Download the iOS SDK and follow the integration steps below
- Sign up for an account on the main Adfonic site
- Add your app to your Adfonic account by going to the Add site or app page
- You can now get your unique adfonic_adslot_id or slotIdentifier from the Ad Integration page and replace the test ID in your code - this looks like 22222222-2222-2222-2222-222222222222
Sample Project
The SDK also contains Ad Gallery, a sample Xcode project. This is a stand-alone project, demonstrating how you can integrate Adfonic banner views into your projects. The project is created from a standard Xcode project template, which can be modified following the instructions below. See the implementation of the App Delegate, which demonstrates how banner views can be used.
Resources, Libraries & Frameworks
In the SDK's 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.
Before you can use the library in your project, you should make sure that -ObjC and -all_load linker flags are set. The library also needs to link with the following frameworks:
- CoreLocation.framework
- MediaPlayer.framework
- QuartzCore.framework
- SystemConfiguration.framework
- CoreTelephony.framework (If your app supports iOS versions before 4.0, you can add this as an optional framework.)
- EventKit.framework
- MessageUI.framework
- CoreMotion.framework
- libsqlite3.a
- libz.a
- MobileCoreServices.framework
- CFNetwork.framework
Using Xcode 3
Right-click on your project in the navigation bar and select "Get Info"
A new window will appear. Select the “Build” tab. Use the search bar to find the setting named “Other Linker Flags” and make sure its value contains “-all_load” and “-ObjC”.
Right-click on Frameworks in the navigation bar and select “Add” then “Existing Frameworks…”.
From the list that appears, choose CoreLocation.framework. Repeat this procedure for all the other required frameworks.
Using Xcode 4
Click on the project in the navigator snd select “Build Settings” in the view that appears in the editor. Find the setiting named “Other Linker Flags” and make sure that -ObjC and -all_load linker flags are set.
Click on the project in the navigator. In the target list, select the target that’s using Adfonic library. Select the “Build Phases” tab and expand the phase named “Link Binary With Libraries.” Choose the plus button, and from the list that appears, choose CoreLocation.framework. Use the same method to add the other required frameworks.
Adding Banner Views
Using the Adfonic static library, you can create banner views (instances of ADFBannerView class) that automatically load and display advertisment banners. The library’s classes and definitions can be accessed by including Adfonic.h header file in your code.
You should use a configuration file to provide the banner view with the information it needs to identify your app. The configuration file can also be used to provide more information about your target audience to help show advertisements that are most relevant to them. See Customising Banner Views for more details on the paramaters you can include in configuration files.
Creating Banner Views
Banner views are created by calling +bannerViewWithType:. You can pass nil as the parameter to use the default banner setting from the configuration file. Configuration Files discusses in more details the value you can pass to this function. The banner view will be sized automatically according to your configurations, and will take all other configurations from the configuration file. Default will be used where none are specified.
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 should never change the size of banner views manually, nor should you subclass ADFBannerView.
By default, the banner view will load a new advertisment based on the value of its bannerViewAutorefreshTime property. You can change the frequency of automatic refresh by changing this property. Setting it to 0 stops automatic updates. 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.
Example:
// 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;
}
Banner Actions
When a user taps on a banner, it may 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 should 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.
Configuration Files
When using Adfonic library, your app bundle should have a property list named AdfonicConfigurations.plist. This is used by the banners to identify your app and configure themselves. The configuration property list should have at least two keys:
- slotIdentifier: Your Adfonic slot identifier. You can get your slot identifiers from your Adfonic account.
- sizeIdentifier: The size identifier associated with your slot identifier. The size identifier should be equal to one of the following strings:
- iphonePortrait: for banners of size {320, 50}
- mpu: for banners of size {300, 250}
- leaderboard: for banners of size {728, 90}
- skyscraper: for banners of size {120, 600}
- banner: for banners of size {468, 60}
When you create a new banner by calling method +bannerViewWithType: with a nil argument, these values are used for configuring the banner.
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 should be an array of dictionaries. In each of the dictionaries, you can set the slotIdentifier and sizeIdentifier of your other banners.
To be able 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 argumet when calling +bannerViewWithType:. Note that the value for type of each dictionary should be unique.
Customising Banner Views
To help Adfonic provide advertisments that are more relevant to your app's users, you can provide more information about the context in which the banner view is used and the user of the application. This will enhance the user experience, and may result in higher advertisment revenue from your app. 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.
A sample configuration file is included in the SDK as part of Ad Gallery sample project.
Additional Configuration Properties
In addition to the required properties described in Configuration Files, Adfonic's configuration file may include the following properties:
- isTest: A boolean value indicating whether the banner is in test mode. You should set this to YES during development, and NO for shipping ** apps.
- colorScheme: The background color to use when serving enhanced text ads on high-end devices. This should be string equal to one of blue, green, orange, purple, red, or yellow.
- ageLow and ageHigh: Expected age range for the users of the app, each as an integer value.
- allowLocationLookup: A boolean value indicating whether user’s location, if known should be submitted to the server.
Note that Adfonic library never enables location services on its own. It will only submit location information if 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).
Adding Multiple Custom Dictionaries
As discussed in Configuration Files, you can include multiple slotIdentifiers by adding dictionaries to the applicable slots array property. 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's enough to create configuration dictionaries that define the necessary tags. Note, however, that the type property should be uniquely set for each dictionary.
Banner View Properties
You may have more information about the user and the banner’s context in the app during launch time. For example, you might know the user’s gender, or prefer a different color scheme based on active settings. You can pass on this information to the banner view by setting its properties. See ADFBannerView class reference in the SDK's Xcode help package for complete list of supported properties.
