Friday, June 13, 2014

Google IMA( Interactive Media Ads) Android SDK



The Google Interactive Media Ads (IMA) SDKs enable publishers to display linear, non-linear, and companion ads in videos and games.
IMA SDKs provide a set of APIs to developers to:
The IMA SDKs Quick Start guides explain how to use the SDKs to display interactive media ads, such as pre-rolls and overlays, within video content players. You need to know:

Who use IMA SDKs?

  • DFP users
    Use IMA SDKs to serve video ads.
  • AdSense for Video (AFV) ads and AdSense for Games (AFG) ads
    Use IMA SDKs.
  • Publishers using VAST ads from a third-party ad server
    Book their VAST ads in DFP and use the IMA SDKs to request and display them.
  • AdExchange for Video
    Uses IMA SDKs.
     

    Android Quick Start (Beta)

    To get started, read:
    Note: For a working example, refer to the sample application. All code on this page is excerpted from the example.

    A note about the SDK architecture

    The Android SDK uses a WebView to load a JavaScript backend. This WebView is only used for making ad requests, parsing responses, and pinging tracking URLs. All video rendering is done natively in Android using your content video player.

    Dowloading, building, and running the sample application

    Note: Before building and running the sample application with Eclipse, you must download and reference the IMA Android SDK
    1. Obtain a copy of the sample application code from the downloads page.
    2. Create the Demo App V3 project in Eclipse.
      1. Start Eclipse.
      2. Click File > New > Project.
      3. Click Android.
      4. Select Android Project from Existing Code.
      5. Click Next.
      6. At Root Directory, enter the top level directory of the sample application.
        7. For example, /home/{username}/googleads-ima-android-master/.
      7. Click Finish.
    3. Download the IMA Android SDK jar file from the downloads page and add it to the libs/ directory in Eclipse.
    4. Include Google Play Services in your application following these instructions.
    5. Build and run the sample application.
      1. Right-click Demo App V3 > Run as > Android application.
      2. Click Req. ad.

    Your first ads request

    To request ads from any VAST-compliant ad server:
    1. Create an instance of AdsLoader to load your ads
      The ImaSdkFactory class is the entry point to the IMA SDK. It's a singleton, so even if you don't keep a reference to the instance, it will be the same instance every time. The first thing you should create is an AdsLoader, which will allow you to request ads. 
      ImaSdkFactory sdkFactory;
@Override
public void onCreate(Bundle savedInstanceState) {
  ...
  sdkFactory = ImaSdkFactory.getInstance();
  adsLoader = sdkFactory.createAdsLoader(this);
  ...
}
    2. Add event listeners
      Register listeners for ad load success and failure events.
      @Override
public void onCreate(Bundle savedInstanceState) {
  ...
  adsLoader.addAdErrorListener(this);
  adsLoader.addAdsLoadedListener(this);
  ...
}
@Override
public void onAdError(AdErrorEvent event) {
  // An error occurred.
}
@Override
public void onAdsManagerLoaded(AdsManagerLoadedEvent event) {
  // Ads were successfully loaded
}
    3. Create AdDisplayContainer to display your ads
      The AdDisplayContainer houses the following objects: VideoAdPlayer for linear ads, ViewGroup for non-linear ads and Collection<CompanionAdSlot> for companion ads.

      Note: Since non-linear ads have not yet been implemented, the ViewGroup is not currently used or required.
      Note: To play video ads, you will first need a compatible VideoAdPlayer implementation. Refer to this tutorial for instructions on how to build a compatible player.
      protected void requestAd() {
  container = sdkFactory.createAdDisplayContainer();
  container.setPlayer(videoPlayer);
  ...
}
      If your application has slots for companion ads, add a collection of CompanionAdSlot objects to the container. When you display the master ad, the ViewGroups you specify will automatically be cleared, then filled with Views to display the companion ads. Currently, only image companions (JPEG, PNG, non-animated GIF) are supported.
      Note: Companions will remain visible after the master is finished playing. If you want them to be hidden, you are responsible for clearing the ViewGroups yourself.
      protected void requestAd() {
  ...

  CompanionAdSlot companionAdSlot = sdkFactory.createCompanionAdSlot();
  companionAdSlot.setContainer(companionView);
  companionAdSlot.setSize(300, 50);

  Collection<CompanionAdSlot> companionAdSlots = new ArrayList<CompanionAdSlot>();
  companionAdSlots.add(companionAdSlot);
  container.setCompanionSlots(companionAdSlots);

  ...
}
    4. Request ads from the server
      Call the requestAds method on the AdsLoader to request an ad. After you request ads, the SDK will call your listeners to inform you of the result.
      protected void requestAd() {
  ...

  AdsRequest request = sdkFactory.createAdsRequest();
  request.setAdTagUrl(TAG_URL);
  request.setAdDisplayContainer(container);
  adsLoader.requestAds(request);
}
    Back to top

    Displaying ads

    After a successful ad request, the SDK will provide you with an ads manager you can use to display ads. Follow these steps to display your ads:
    1. Get the ads manager
      Once the ad loads successfully, the onAdsManagerLoaded method of your AdsLoadedListener is called. Get an ads manager from the event you received by calling AdsManagerLoadedEvent.getAdsManager and use that instance to display ads and add event listeners for ad playback events and errors.
      @Override
public void onAdsManagerLoaded(AdsManagerLoadedEvent event) {
  adsManager = event.getAdsManager();
  adsManager.addAdErrorListener(this);
  adsManager.addAdEventListener(this);
}
    2. Handle Ad Events
      The SDK will send various events to your listener, three of which you need to handle.
      • When an ad has been loaded, AdEventType.LOADED will be fired indicating that ads are ready to be played.
      • AdEventType.CONTENT_PAUSE_REQUESTED will be fired immediately before a video ad is played to indicate that you should pause your video content.
      • After the ad finishes playing, or you explicitly unload it, AdEventType.CONTENT_RESUME_REQUESTED will be fired to indicate that the content should begin playing again.
      You will also receive events indicating other occurrences during ad playback. These include events which indicate the position of the playhead within the ad, such as AdEventType.MIDPOINT and AdEventType.COMPLETE as well as AdEventType.CLICK which occurs when a user clicks on the ad. The SDK will handle opening a browser with the ad's clickthrough URL, but you may want to unload the ad or otherwise respond to the interaction yourself. For the list of all event types see AdEvent.AdEventType . 
      @Override
public void onAdEvent(AdEvent event) {
  switch (event.getType()) {
    case LOADED:
      adsManager.start();
      break;
    case CONTENT_PAUSE_REQUESTED:
      videoPlayer.pauseContent();
      break;
    case CONTENT_RESUME_REQUESTED:
      videoPlayer.resumeContent();
      break;
  }
}
    3. Initialize the ads manager
      Before ads can be played, the ads manager must be initialized by calling AdsManager.init. If an ad rules playlist is returned as the ad, the SDK will start executing the playlist. If there are pre-rolls scheduled within the ad rules playlist, they will start at this time. 
      @Override
public void onAdsManagerLoaded(AdsManagerLoadedEvent event) {
  adsManager = event.getAdsManager();
  adsManager.addAdErrorListener(this);
  adsManager.addAdEventListener(this);
  adsManager.init();
}
    4. Start the ads
      Call AdsManager.start to start ad playback. Video and overlay ads will start at this time. The ad rules playlist will ignore this call. AdsManager.start can be called any time after the AdEventType.LOADED event has been received.
    That's it! You're now requesting and displaying your first ads. To fine tune your implementation, read advanced topics.
    Back to top
     
Posted by at

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)