Archived‎ > ‎

Integrating iOS SDK (pre V4)



Integrating

iVdopia provides a library that you can integrate into your application by writing few lines of code. Please download the latest iVdopia developer kit from here
Currently this library allows you to add the following ad formats.
  • Pre-App Videos: 5 to 15 sec video advertisement (with a SKIP AD option after 5 sec of video ad) runs while the application loads.
  • In-App Videos: 5 to 15 sec video advertisement (with a SKIP AD option after 5 sec of video ad) runs during the application play. You can call this advertisement anytime during the application play such as in between game levels, before any video/audio etc. Typical use of In-App video advertisements is as follows:
    • Between Game Levels
    • As a preroll video (before a video playback)
    • As a postroll video (after a video playback)
  • Banner Ads: 320px*48px banner advertisement that changes every 30 sec. Banner ads displaying the same brand message reinforcing the advertiser brand. These can be placed on the top or bottom of the application screen.
  • In-App Interstitial Ads: 5 to 15 sec web advertisement (with a SKIP AD option after 5 sec of ad) runs during the application play. You can call this advertisement anytime during the application play such as in between game levels, before any video/audio etc.
With version 2.1.0 iVdopia revolutionized advertising with the very popular Talk2meTM. This format appears after the regular Pre-app/In-app video advertising providing sevaral options to the user thereby increases his interest in advertising.

    What do you get in this library?

    With iVdopia library you get the following files:

    • VDOAds.h
    • libVDOAdsDevice.a
    • libVDOAdsSimulator.a

    VDOAds.h: Header file with the following class and instance functions:

    Class: VDOAds

-(void)openWithAppKey:(NSString*)applicationKey useLocation:(BOOL)use withFrame:(CGRect) frame;
-(void)openWithAppKey:(NSString*)applicationKey useLocation:(BOOL)use withFrame:(CGRect) frame startWithBanners:(BOOL) start;
Added in 1.3.7
-(void)openWithAppKey:(NSString*)applicationKey useLocation:(BOOL)use withFrame:(CGRect) frame startWithBanners:(BOOL) start startWithPreApp:(BOOL) startPreApp
Added in 3.3.1
-(void)playVDOAd;
-(void)playVDOAd:(NSString*)message; Added in 1.3.9
-(void)playInApp; Added in 2.2.4
-(void)pauseBanners;
-(void)resumeBanners;
-(void)playPreApp; Added in 3.3.1
-(void)getBannerOfSize:(NSString*) size; Added in 3.4.1
-(void)close;

    Starting with SDK version 2.2.4, the API playInApp enables to play all in-app formats with a single call. This means that one can call the API playInApp at appropriate times in the application and the SDK will start to choose between and serve in-app Videos and in-app Interstitial web based ads using its randomization algorithm.

    Please note that if you require the exclusive use of in-app videos, the API playVDOAd continues to work as before.

    This class has a gettable property VDOAds which extends UIView and needs to be added as a subview to a visible 320x48 view.


    Protocol: VDOAdsDelegate

-(void)playedVDOAd;
-(void)noVDOAd;
-(void)noBanner; Added in 2.2.0
-(void)displayedBanner; Added in 2.2.0
-(void)playedInApp; Added in 2.2.4
-(void)noInApp; Added in 2.2.4
-(void) bannerTapStarted; Added in 3.0.0
-(void) bannerTapEnded; Added in 3.0.0
-(void) playedPreApp; Added in 3.3.1
-(void) noPreApp; Added in 3.3.1

    This class has a gettable property VDOAds which extends UIView and needs to be added as a subview to a visible 320x48 view.

    All delegate functions are now optional and need not be implemented starting from version 3.0.0.


    Integration Steps:

    • 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
    MediaPlayer.framework
    CFNetwork.framework
    MessageUI.framework
    SystemConfiguration.framework
    Please note: These libraries are dynamic, and do not result in increased executable size.
    CoreLocation.framework's dependency was removed starting 2.1.2


  • In the applicationDidFinishLaunching function add the following code:
    vdoAds=[VDOAds alloc];
    CGRect frame=CGRectMake(0, 0, 320, 48);
    [vdoAds openWithAppKey:@MY_APP_KEY useLocation:TRUE withFrame: frame];



    In case you want to have finer grained control on banner ads you may use the API instead:
    [vdoAds openWithAppKey:@MY_APP_KEY useLocation:TRUE withFrame: frame startWithBanners:TRUE];
  • Create a delegate that implements the protocol VDOAdsDelegate
    Please Note:
    Either playedVDOAd or noVDOAd will be called at any given time. Both will not be called for any particular invocation.

  • In the applicationWillTerminate function add the following code:
    [vdoAds close];


  • In the dealloc function:
    [vdoAds release];

  • Once the above steps are accomplished and Pre-App advertisements are enabled through the portal. We should start seeing the Pre-App advertisements.

  • Banner Advertisements
    • In order for banners to be visible and working, once your application loads properly, you need to add vdoAds.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:vdoAds.adObject];


    • In case the view to which banner advertisements are attached become hidden you will need to EXPLICITLY call pauseBanners. Invocation is explained below. This particular call needs to be made in conjunction with resumeBanners.

    • iVdopia additionally provides you option to pause the currently playing banner advertisements using the following methods
      [vdoAds pauseBanners];// Use this whenever any action you are performing obscures the banner advertisements from being visible.
      [vdoAds resumeBanners];// You may resume display of more banner advertisements using the resumeBanners api.

    • In the sample code please have a look at startBanners and stopBanners functions to understand how to start and stop banners in the middle of an application. You may copy and modify these functions as per your requirements. 
    • With the release of the SDK version 3.4.1 a new API is available to request banners on-demand.
    • The new API getBannerOfSize can be called with any of the following constants, and it will return the banner of the requested size , if available.
      [vdoAds getBannerOfSize:STANDARD_IPHONE_BANNER]; // Returns a 320 X 48 pixels banner if available 
      or 
      [vdoAds getBannerOfSize:STANDARD_IPAD_BANNER];// Returns a 728 X 90 pixels banner if available  
      [vdoAds getBannerOfSize:RECTANGLE_BANNER];// Returns a 300 X 250 pixels banner if available  

  • Video Advertisements
    • Run the game once. You will not see any Pre-App at this time, the Pre-App are optimized and cached before they are played. VDOAds is optimized for outstanding video experience and therefore implements caching and cache replacement algorithms that help in improving that experience. This feature also ensures that the users are not shown any advertisement units that disrupt their gaming experience.

    • In-App videos can be invoked on demand using the API: playVDOAds. This api can be called many times during the run of the application.
      [vdoAds playVDOAds];
      or
      [vdoAds playVDOAds:@"Message"];(Added 1.3.9)


  • Interstitial Advertisements
    • This ad format can be used to show a web based advertisement at chosen time in the application. A UIWebView of the specific dimension becomes visible in the application and allows the user to engage with the advertisement using the web experience.

    • This ad format ensures that the application remains visible in the background so that the user does not feel being taken away from the application context.
    • In-App Interstitials can be invoked on demand using the API: playInApp. This api can be called many times during the run of the application.
      [vdoAds playInApp];

    • playInApp API actually plays any in-app format in the application. This could be an in-app video or an in-app web view based ad.


  • When you run the application for the first time, video ad units are not displayed immediately. The caching algorithms inside the components work to create a flawless video ad experience for the user.

    This and several other features make iVdopia solution the most unique brand advertising opportunity that developers have.

  • Note: Version 1.3.5 adds support for the iPhone OS3.

  • Note: Prior to version 1.3.4 you need to call
    [self.view.window makeKeyAndVisible]
    or any other appropriate call when playedVDOAd delegate method is called.

The sample iTennis.zip that implements this API is included for reference.

Integration with remnant Ad networks

If you are already integrated with low CPM ad networks, or adaggregators such as mobclix, admob, adwhirl etc, you may still utilize iVdopia API's to maximize your inventory utilization at the same time meeting the high level SLAs iVdopia maintains with its advertisers. To that end iVdopia provides APIs that you may utilize in your applications

iVdopia SDK determines if the requested Ad has been served or not. If you implement the functions of the protocol, VDOAdsDelegate you can effectively track whether the ad was served or not.


So, one can check using the delegate function noBanners; this is called when either:
  • Banners are not served by iVdopia servers
  • Banners are served however they hit limits
These opportunities can be utilized to initialize and call remnant network inventory for banners. At this time however in-app videos may be available.

Integration Checklist

  • Pre-App
    1. Programming: Please make sure

      [vdoAds openWithAppKey:@MY_APP_KEY  withFrame: frame useLocation: FALSE/TRUE ];

      or

      [vdoAds openWithAppKey: @MY_APP_KEYTRUE withFrame: frame  useLocation: FALSE/TRUE startWithBanners: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.

    3. Behavior: You have given enough "game time" for the ad to cache

  • In-App Video
    1. Programming: In addition to the openWithAppKey call, please make sure

      [vdoAds playVDOAds];
      or
      [vdoAds playVDOAds:@"Message"];(Added 1.3.9)

      is called at the appropriate time

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

    3. Behavior: You have given enough "game time" for the ad to cache

  • 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:vdoAds.adObject];. If the advanced version of openWithAppKey is called please make sure you added code that starts the banner at the right time.

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

    3. Behavior: pauseBanners and resumeBanners are called at appropriate times

  • In-App Interstitial and Video
    1. Programming: In addition to the openWithAppKey call, please make sure the playInApp is made at the right time. For correct in-app behavior any successive invocation of API playInApp should be succeed by either API:playedInApp or API: noInApp.

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

    3. Behavior: pauseBanners and resumeBanners are called at appropriate times

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. The first time you start the app you should see a low quality ad depending on your network connection.
    2. If InApp calls are made in your program, you should start seeing Video advertisements while the application is playing, at the location where InApp calls are being made.
    3. Banner advertisements, if programmed, should be visible throughout the application run.
    4. Once you verify above, restart the application and you should see Pre-App video advertisements.
    5. Some test video advertisements are frequency capped at 10 in which case you need to delete the application and redo the test case.

  2. On the portal please enable all advertisements, enable Advanced Targeting
    Delete the entire installation of your application from your device and then install the application through Xcode on your device or simulator

    Expected behavior:
    1. Two video ad campaigns are enabled in test mode a) one campaign with frequency cap of 10 per day b) another campaign with Advanced targeting and no frequncy cap. The campaign with Advanced targeting shows a question only once on one device (for each application) if answered, else if the question is skipped it is shown every hour.
    2. The first time you start you should see no Video advertisement
    3. If In-App is called before video advertisments are cached, you should see an interface prompting the user for some information relating to the targeting advertiser selects for his campaign.
    4. If In-App is called afterward, however this interface will not show until the other campaign hits its maximum (10) in case of testing
    5. Banners should show through out the application execution
    6. Once the other video campaign hits day-max (10) the interface prompting the user for information will appear.
    7. If in the prompt you mention the information that the targeting requires to pass (Typically if DoB indicates that age > 21) new advertising will start to appear
    8. For re-test simply delete the application and test again

  3. 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 well.

Requesting for 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.

Updating Application with new iVdopia 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.

Order of calls to get the pre-app and banners working

  1. Complete all the setup work for your app.
  2. Call makeKeyAndVisible on the application Window
  3. Call openWithAppKey of iVdopia SDK
  4. Call addSubView on adView returned by iVdopia SDK

Rotating banner view in Landscape mode


To reposition the banner view after rotating your application , apply a transformation (rotation) to the banner view and set its frame again at the required position on the view.  

Something Like:

CGAffineTransform trans;

if (interfaceOrientation==UIDeviceOrientationLandscapeLeft ) {

trans=CGAffineTransformIdentity;

trans=CGAffineTransformRotate(trans, -(3*M_PI/2));

else if (interfaceOrientation==UIDeviceOrientationLandscapeRight) {

trans=CGAffineTransformIdentity;

trans=CGAffineTransformRotate(trans, (3*M_PI/2));

else 

{

trans=CGAffineTransformIdentity;

}


adView.transform = trans;

adView.center = self.view.center;

        adView.frame = CGRectMake(x,y,width, height);


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