Integration‎ > ‎

iOS SDK V4+

The ad formats available through the library are:
  • Banner Ads: The SDK can place rich-media banners inside views defined by the app. Rich-media banners can include animation and expansion effects. Banners open an in-app full-screen web-view when tapped.
  • Interstitial Ads: The SDK also makes available full-screen interstitial ads which take over the app when called. The app can choose to play such ads when it starts up or at different points within the app's e.g.on game level completion or before any video/audio content play etc.

Ad Format details

Banner Ads 

iVdopia's new SDK serves banner ads in the following sizes:
  • 320 X 75 (mini VDO Banner)
  • 320 X 48 (standard iPhone banner)
  • 768 X 90 (standard iPad banner size 1)
  • 728 X 90 (standard iPad banner size 2)
  • 300 X 250 (rectangle banner)
The banner ads can include video (through Vdopia's proprietary .vdo technology) and HTML5 animation. Various actions are available to advertisers when a user chooses to interact with a banner ad -- most common being a full page takeover that displays the advertiser's landing page. Other actions like click-to-video, click-to-download, click-to-call etc. are also possible.



Interstitial Ads

An insterstitial ad temporarily takes control from the app to display advertising content. The interstitial can appear over part of the app as a transparent overlay or a full-screen takeover in a webview.



SDK components

The SDK bundle which can be downloaded from http://wiki.ivdopia.com/file-cabinet  includes the following files that need to be included into apps:

NOTE: The SDK has been built using iOS SDK 4.3 as Base SDK.
  • VDOAds.h
  • libVDOAdsDevice.a
  • libVDOAdsSimulator.a
The header file has the following class and instance functions:

Class: VDOAds

This class manages the overall session of the ads per application. There can be only one instance of this object per application.

@interface VDOAds : NSObject {
    id<VDOAdsDelegate> delegate;
}

@property (readwrite,assign) id<VDOAdsDelegate> delegate;

- (void)openWithAppKey:(NSString*)applicationKey useLocation:(BOOL)use;
- (VDOAdObject*) requestBannerOfSize:(NSString *) bannerSize : (int)location;
- (VDOAdObject*) requestPreApp;
- (VDOAdObject*) requestInApp;
- (void)close;

Class: VDOAdObject

This class manages the load and display of a single ad. There can be multiple instances of this object and the parameter "type" specifies the adFormat associated with it. The gettable property adObject should be added as a subview to a UIView in case of the banner ad format.
@interface VDOAdObject : NSObject {
    UIView *adObject;
    int type;
    VDOAdObjectController *vdoAdController;
}

@property (readonly) UIView *adObject;
@property (readonly) int type;
@property (readonly) VDOAdObjectController *vdoAdController;
@property (assign, readwrite) NSString *reason;

-(vdoApiStatus) loadAd:(float)timeout;
-(void) displayAd;
-(vdoApiStatus) loadAndDisplayAd:(UIImage*)splashscreen : (float) timeout;
-(BOOL) isReady;
-(void) closeAd;

Protocol: VDOAdsDelegate

The delegate functions mentioned here are optional and it is not necessary to implement all of these.
- (void) displayedBanner:(VDOAdObject*)object;
- (void) noBanner:(VDOAdObject*)object;
- (void) playedInApp:(VDOAdObject*)object;
- (void) playedPreApp:(VDOAdObject*)object;
- (void) noInApp:(VDOAdObject*)object;
- (void) noPreApp:(VDOAdObject*)object;


- (void) bannerTapStarted:(VDOAdObject*)object;
- (void) bannerTapEnded:(VDOAdObject*)object;
- (void) interstitialWillShow:(VDOAdObject*)object;
- (void) interstitialDidDismiss:(VDOAdObject*)object;

Integration Steps

Adding the SDK to a project

  • Drag-Drop both libVDOAdsDevice.a and libVDOAdsSimulator.a to frameworks folder in Xcode.


  • Drag-Drop VDOAds.h to the Classes folder in Xcode.


  • Add the following frameworks to the project
  • CFNetwork.framework
  • MessageUI.framework
  • SystemConfiguration.framework
  • QuartzCore.framework
Please note: These libraries are dynamic, and do not result in increased executable size.

SDK initialization

  • In the applicationDidFinishLaunching function add the following code.Create and allocate Object then Initialize the object as done below.
    VDOAdObject *vdoAds = [VDOAds alloc];   
    [vdoAds openWithAppKey:@YOUR_APP_KEY useLocation:YES];
  • Create a delegate that implements the protocol VDOAdsDelegate.
  • In the applicationWillTerminate function add the following code:
    [vdoAds close];

  • In the dealloc function:
    [vdoAds release];

Requesting Ads

This new version of SDK allows a publisher to request an ad object of the required type and load the object with the ad data asynchronously. The ad object can be queried and then displayed appropriately.

Interstitial ads

There are 2 ways to display interstitial ads inside the application. We will discuss both the approaches in detail.

  • Approach 1: Load the ad to display later on your own.
    -(vdoApiStatus) loadAd:(float)timeout;
    -(BOOL) isReady; -(void) displayAd;
In this approach, you need to create an object of the required type and then call the function loadAd. The parameter timeout is an indication to the SDK to wait for the maximum time after which the ad will not be attempted to load.

You should query the status of the ad Object using the API. isReady. If this returns a value YES, then you should display the ad using the API displayAd.

  • Approach 2: Load and display ad in a single call
    -(vdoApiStatus) loadAndDisplayAd:(UIImage*)splashscreen : (float) timeout;
In this approach, you need to create an object of the required type and then call the function loadAndDisplayAd.
The parameter splashscreen takes a UIImage object and it allows to display a splash screen before the ad inside the application before the ad is ready to serve itself. If this parameter is set as NULL, no splash screen is shown before the ad.
The parameter timeout is an indication to the SDK to wait for the maximum time after which the ad will not be attempted to load.

NOTE: The minimum timeout required by the SDK is 3 seconds.


Pre-App ad
To play a pre-app ad after the application has finished launching, do the following
  • In the applicationDidFinishLaunching function add the following code.
VDOAdObject *preApp = [vdoAds requestPreApp];
vdoApiStatus error = [preApp loadAndDisplayAd:[UIImageimageNamed:@"Splash.PNG"] :5.0]; //  This is one way of playing a pre-app ad. You can also you the load and display later approach

  The above sequence of calls are doing the following:
  • Requesting a preApp ad Object.
  • Initiating a call to load a pre-app ad and display it along with the splash screen.
In-App ad
To play an in-app ad between various points of interest in the application
  • Add the following code.
VDOAdObject *inApp = [vdoAds requestInApp];
vdoApiStatus error = [inApp loadAd:3.0];

// After 3 seconds , query the ad status.
BOOL isAdReady = [
inApp isReady];
if(isAdReady)
    [inApp displayAd];

//  This is one way of playing an in-app ad. You can also you the loadAndDisplayAd approach (with or without splashscreen).

  The above sequence of calls are doing the following:
  • Requesting a InApp ad Object.
  • Initiating a call to load an In-app ad.
  • Queries the ad status after the timeout. You can poll and check the ad status any time.
  • If the ad is ready, displays it.

Banner ads

To show a banner ad:
  • Add the following code.
VDOAdObject *ban = [vdoAds requestBannerOfSize:banSize :location];
 
if([ban isReady])
{
   [self.view addSubview:ban.adObject];
}

In order for banners to be visible and working, once the banner is ready, you need to  add ban.adObject as a subview to view of your choosing:
E.g In a table cell you add the adObject as a subview to the cell
[cell addSubview:ban.adObject];

The parameter banSize specifies the size of the banner that is requested.
The parameter location specifies how the banner needs to be place with respect to the webview in which it is placed. Its location can be - top or bottom.

Ad Event notification

During the process of serving the ads, the SDK informs the application about various events that ensures that the application can respond appropriately. Vdopia's iOS SDK gives out these events in the form of callbacks that should be implemented by the delegate. (Recommended).

The events can be broadly classified as :
  • UI events - These events are given out when the SDK makes some changes in the UI of the application. It is highly recommended that the application responds to these events so that the application UI and ad UI do not have conflicts. The following events are given out by the SDK.
- (void) bannerTapStarted:(VDOAdObject*)object;
- (void) bannerTapEnded:(VDOAdObject*)object;
- (void) interstitialWillShow:(VDOAdObject*)object;
- (void) interstitialDidDismiss:(VDOAdObject*)object;


  • bannerTapStarted - This event is called when a banner ad is clicked. The ad expands itself into a full screen view.
  • bannerTapEnded - This event is called when an expanded banner ad is dismissed.
  • interstitialWillShow - This event is called when an interstitial ad is about to take over the screen. This happens just before the splash screen is shown (in case the loadAndDisplayAd API is called with a splash screen param). Otherwise, when the ad is ready to be rendered. The app must not perform any UI operations once this call is received until the intersitialDidDismiss event is received.
  • interstitialDidDismiss - This event is called when the interstitial ad is about to be removed from the screen. This callback should be treated as a signal to the application to resume its UI operations.
  • Non-UI events - These events are given out to indicate the ad serving status to the application.
- (void) displayedBanner:(VDOAdObject*)object;
- (void) noBanner:(VDOAdObject*)object;
- (void) playedInApp:(VDOAdObject*)object;
- (void) playedPreApp:(VDOAdObject*)object;
- (void) noInApp:(VDOAdObject*)object;
- (void) noPreApp:(VDOAdObject*)object;
           
    • displayedBanner - This event is called when a banner is served by the SDK and it becomes visible.
    • noBanner - This event is called when no banner is available to serve.
    • playedInApp - This event is called when an in-app interstitial ad is served by the SDK.
    • noInApp - This event is called when no in-app ad is available to serve.
    • playedPreApp - This event is called when a pre-app interstitial ad is served by the SDK.
    • noPreApp - This event is called when no pre-app ad is available to serve.

Integration Checklist

Ad Formats

Pre-App

  1. Programming: Please make sure

    [vdoAds openWithAppKey:@MY_APP_KEY  useLocation: FALSE/TRUE ];
     
    was called correctly with the apikey mentioned in the portal

  2. Portal: Integrate Ads Tab > View App > Format-Pre App Video is checked.

In-App

  1. Programming: In addition to the openWithAppKey call, please make sure the sequence of calls mentioned in the Section 5.4 is called at the appropriate time

  2. Portal: Integrate Ads Tab > View App > Format-In App Video is checked.

Banner

  1. Programming: In addition to the openWithAppKey call, please make sure the adObject is added to the correct view at the correct location using a call similar to: [cell addSubview:ban.adObject];.
  2. Portal: Integrate Ads Tab > View App > Format-Banner Ads is checked

Remnant Ad networks

If you are already integrated with other ad networks or aggregators such as mobclix, admob, adwhirl etc, you can use the provided APIs to maximize your inventory utilization. In particular, the 'noBanner' call made by the SDK can be used to load ads from other sources into the banner view.

Testing

No programming is complete without testing, so here are suggestions for testing the API in the test mode (Please Note:if you are in Live mode it is best to create an App/API key that is in the test mode). Even if you plan not to enable Pre-App advertisements you should test that they work perfectly with your application.
Cases:
  1. On the portal please enable all advertisements, and disable Advanced Targeting
    Once you have installed the SDK and ready for testing it on device. Delete the entire installation of your application on the device, and then install the application through Xcode on your device

    Expected behavior:
    1. Depending on the network strength on your device, you will or will not see the ads within the given "timeout" at the time of the API 
    2. Some test  advertisements are frequency capped at 10 in which case you need to delete the application and redo the test case.


    On portal disable all advertisements, do not delete the application from the device.
    Expected behavior:
    Within couple of minutes no advertising will be served, it will stop within couple of minutes on the client side as

Requesting Live Ads

Once you complete the testing for the first time, and submit the application to apple. Write to support@ivdopia.com. To change your application status to "Live Mode". Please note that once live mode is enabled you will no longer see test ads on your application.

If you need to test your application with test ads again you will need to create another API key for testing purposes.

Call order

  1. Complete all the setup work for your app.
  2. Call makeKeyAndVisible on the application Window
  3. Call openWithAppKey of iVdopia SDK
  4. Call requestPreApp to request an adObject instance.
  5. Call loadAd followed by displayAd or call loadAndDisplayAd on the adObject instance.
  6. Call requestBannerOfSize API with the appropraite size and location
  7. Query the status of the banner object, if it is ready, add the adObject to a visible UIView. The banner should display itself.

Moving to a new Vdopia SDK

Whenever there is a iVdopia SDK update, please go through the RELEASE notes to see if there is any API update. In case of an API update, you may have to implement a few more functions in your delegate method. However, if there is no API update, a simple drag drop of the new libraries into the project folders will suffice.

In either case, since your original APP key is running Live Ads we recommend you test with a separate APP Key that you use for test mode.

If you are having any difficulty integrating the code, please email us at mobile-developers@vdopia.com


Comments