Wiki

Search this site
Integration‎ > ‎

Android SDK V2+

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 Android SDK serves banner ads in the following sizes:
  • 320 X 75 (Mini VDO Banner)
  • 320 X 48 (Standard banner)
  • 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 interstitial 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.

Creating an iVdopia-enabled Android app involves the following steps:

  • Obtain the SDK from iVdopia.
  • Integrate the SDK with your Application.
  • Obtain an API key for your application and configure ads using iVdopia's publisher portal.
  • Test ad delivery to your application using an Android device.
  • Distribute your application on the Android marketplace.
  • Monitor your application's performance and earnings using iVdopia's publisher portal.

    Note that the Android emulator does not display videos well, so you will need to use a real device for testing.

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:

 iVdopia_Android_SDK_v2.0.1.jar

Integration Steps

Set up the project

  • Add iVdopia_Android_SDK_v2.0.1.jar to your build path.
  • Modify your projects AndroidManifest.xml file to include iVdopia elements.
    • Include a description of the Activity that will display video ads.   
   <activity android:name="com.vdopia.client.android.VDOWebActivity"
                   android:theme="@android:style/Theme.Translucent"
                   android:configChanges="orientation|keyboardHidden">
   </activity> 
  • Request the INTERNET permission for the application.
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /

SDK Initialization

List of APIs and their usage

Class VDO - // This class manages the overall session of the Ads. There should be a single instance of this object per application

public static void initialize(String key, Context ctx);
public static VDOAdObject requestPreApp(Context ctx);
public static VDOAdObject requestInApp(Context ctx);
public static void closeAd();
public static setListener(AdEventListener l);

Class VDOAdObject - // This class manages the load and display of an ad. There can be multiple instances of this object and the function returnAdtypeForObject() specifies the adFormat associated with it

public int loadAd(double inTimeout);
public void displayAd();
public int loadAndDisplayAd(Bitmap bm, double inTimeOut);
public boolean isAdReady();
public int returnAdtypeForObject();

Class VDOBannerView

public VDOBannerView(Context context, String size, int location);

/* Values for the AD_TYPE key */
public static final int AD_TYPE_PRE_APP_VIDEO = 0xAD01;
public static final int AD_TYPE_IN_APP_VIDEO = 0xAD02;
public static final int AD_TYPE_BANNER = 0xAD03;
   
/* Return values for the APIS */
public static final int VDO_API_SUCCESS = 0x00;
public static final int VDO_API_LOADING = 0x01;    
public static final int VDO_API_INCORRECT_TIMEOUT = 0x02;
   
/* Banner constants */
public static final String STANDARD_BANNER = "320X48";
public static final String RECTANGLE_BANNER = "300X250";
public static final String MINI_VDO_BANNER = "320X75";


  • For fetching ads , the SDK context must be initialized by calling the following API.
VDO.initialize("AX123", this);

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.
inAppObject = VDO.requestInApp(this.getApplicationContext());
int returnVal = inAppObject.loadAd(3.0); // 3.0 seconds is the timeout value

if(inAppObject.isAdReady())
{
    inAppObject.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. isAdReady. 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
inAppObject = VDO.requestInApp(this.getApplicationContext());
int returnVal = inAppObject.loadAndDisplayAd(bm, inTimeOut);

The parameter bm takes a Bitmap 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 launcher activity has finished launching, do the following

In the function  public void onCreate(Bundle savedInstanceState) add the following code.

VDOAdObject preApp = VDO.requestPreApp(this.getApplicationContext());
Bitmap mBitmap = BitmapFactory.decodeResource(getResources(),
                   R.drawable.splash);
int retval = preApp.loadAndDisplayAd(mBitmap, 8.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.
    inAppObject = VDO.requestInApp(this.getApplicationContext());
    int returnVal = inAppObject.loadAd(3.0); // 3.0 seconds is the timeout value

    if(inAppObject.isAdReady()) // Query the status after 3.0 seconds atleast
    {
        inAppObject.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.
VDOBannerView banObject = null;
String bannerSize = new String(MINI_VDO_BANNER);
int location = 0; // Placing the banner that expands from top to bottom
banObject =  new VDOBannerView(this.getApplicationContext(), bannerSize, location);
if (banObject == null)
{
    System.out.println("No banner of the requested size found");
    return;
}

Handler refresh = new Handler();
refresh.postDelayed(new Runnable() {
public void run()
{
    RelativeLayout.LayoutParams p =               (RelativeLayout.LayoutParams)banObject.getLayoutParams();
    if(location == 1)
        p.addRule(RelativeLayout.ALIGN_PARENT_BOTTOM);
    else
        p.addRule(RelativeLayout.ALIGN_PARENT_TOP);
               
       myLayout = (RelativeLayout)findViewById(R.id.layout_banner);
        myLayout.addView(banObject, p);
          }
      }, 3000);

In order for banners to be visible and working, once the banner is ready, you need to  add banObject as a subview to view of your layout:

The parameter bannerSize 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 notifications and listeners

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 Android SDK gives out these events in the form of callbacks that can be received by implememting functions of VDO.AdEventListener interface.

Following is the interface definition:
        
        public static interface AdEventListener {
        public void displayedBanner(VDOBannerView object);
        public void noBanner(VDOBannerView object);
       
        public void playedInApp(VDOAdObject object);
        public void playedPreApp(VDOAdObject object);
        public void noInApp(VDOAdObject object);
        public void noPreApp(VDOAdObject object);
       
        public void bannerTapStarted(VDOBannerView object);
        public void bannerTapEnded(VDOBannerView object);
        public void interstitialWillShow(VDOAdObject object);
        public void interstitialDidDismiss(VDOAdObject object);
       
    }

For example you can create a class VdopiaEventListener which implements this interface:
class VdopiaEventListenr implements VDO.AdEventListener {
 public void interstitialWillShow(VDOAdObject object) {
    //do something
  } 
  public void interstitialDidDismiss(VDOAdObject object) {
    //do  something
  }
  public void noInApp(VDOAdObject object) {
    //do something
  }
}

Then you can create an instance of this class and call setListener on VDO:
VDO.setListener(new VdopiaEventLister());

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. UI events are:
public void bannerTapStarted(VDOBannerView object);
public void bannerTapEnded(VDOBannerView object);
public void interstitialWillShow(VDOAdObject object);
public 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.
        public void displayedBanner(VDOBannerView object);
        public void noBanner(VDOBannerView object);
       
        public void playedInApp(VDOAdObject object);
        public void playedPreApp(VDOAdObject object);
        public void noInApp(VDOAdObject object);
        public 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

    VDO.initialize(key, context);
     
    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 initialize call, please make sure the sequence of calls mentioned in the Section 4.1.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 initialize call, please make sure the bannerView is added to the correct view at the correct location.
  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 Eclipse 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.

Moving to a new Vdopia SDK

Whenever there is a iVdopia Android 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 the listener class. However, if there is no API update, a simple update of the .jar file in your build path should 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

Sign in|Report Abuse|Print Page|Remove Access|Powered By Google Sites