Google Interactive Media Ads

Working with Ads (Deprecated)

This section explains how publishers can request and display ads using the IMA SDK for Android. For a working example refer to the sample application on the Google IMA SDK for Android download page.

Request Ads

The following steps enable you to request ads from any VAST-compliant ad server:

  1. Create an instance of AdsLoader to load your ads
  2. Add event listeners
  3. Request ads from the various networks

  1. Create an instance of AdsLoader to load your ads

    The AdsLoader class is the entry point to the IMA SDK.

      @Override
      public void onCreate(Bundle savedInstanceState) {
        ...
        adsLoader = new AdsLoader(this);
        ...
      }
  2. Add event listeners

    Register listeners for ad load success and failure.

      @Override
      public void onCreate(Bundle savedInstanceState) {
        ...
        adsLoader.addAdErrorListener(this);
        adsLoader.addAdsLoadedListener(this);
        ...
      }
    
      @Override
      public void onAdError(AdErrorEvent event) {
        // An error occurred.
      }
    
      @Override
      public void onAdsLoaded(AdsLoadedEvent event) {
        // Ads were successfully loaded
      }
  3. Request ads from the various networks

    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() {
        SimpleAdsRequest request = new SimpleAdsRequest();
        request.setAdTagUrl(TAG_URL);
        request.setAdType(AdType.VIDEO);
        adsLoader.requestAds(request);
      }

    If your application has slots for companion ads, add a list of CompanionAdSlot objects to the request. 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 are supported.

    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() {
        ...
        request.setAdType(AdType.VIDEO);
        
        CompanionAdSlot companionAdSlot = new CompanionAdSlot();
        companionAdSlot.setContainer(companionView);
        companionAdSlot.setSize(300, 50);
        List<CompanionAdSlot> companionAdSlots = new ArrayList<CompanionAdSlot>();
        companionAdSlots.add(companionAdSlot);
        request.setCompanions(companionAdSlots);
        
        adsLoader.requestAds(request);
      }

Back to top

Display ads

After a successful ad request, the SDK will provide you with an ads manager you can use to display ads. For video ads, the ads manager is an instance of VideoAdsManager.

The following steps enable you to display your ads:

  1. Get the ads manager
  2. Handle ad events
  3. Set up and play the ads

  1. Get the ads manager

    Once the ad loads successfully, the onAdsLoaded method of your AdsLoadedListener is called. Get an ads manager from the event you received by calling AdsLoadedEvent.getManager and use that instance to display ads and add event listeners for ad playback events and errors. You can reuse your existing error listener or create a new one.

      @Override
      public void onAdsLoaded(AdsLoadedEvent event) {
        adsManager = (VideoAdsManager) event.getManager();
        adsManager.addAdErrorListener(this);
        adsManager.addAdEventListener(this);
      }
  2. Handle ad events

    The SDK will send various events to your listener which you need to handle.

    For video ads, you will receive AdEventType.CONTENT_PAUSE_REQUESTED 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 sent to indicate that the content should begin playing again. You will also receive events that inform you of progress through the ad, such as AdEventType.MIDPOINT and AdEventType.COMPLETE.

    The SDK will also notify you 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.

      @Override
      public void onAdEvent(AdEvent event) {
        switch (event.getEventType()) {
          case CONTENT_PAUSE_REQUESTED:
            videoPlayer.pauseContent();
            break;
          case CONTENT_RESUME_REQUESTED:
            videoPlayer.resumeContent();
            break;
          case CLICK:
            adsManager.unload();
            break;
        }
      }
  3. Set up the ads manager and play the ads

    To play video ads, you will first need a compatible VideoAdPlayer implementation. Building a compatible player is described in a separate tutorial.

    Once you have a compatible player, just call VideoAdsManager.play to play the ad. Your player is responsible for notifying the SDK when a user clicks an ad by firing the onClick callback.

      protected void playAd() {
        log("Playing ads");
        adsManager.play(videoPlayer);
      }
  4. Back to top

    VAST event compatibility

    Fully supported

    All video players must fire the callbacks that trigger the following events:

    complete, creativeView, firstQuartile, impression, midpoint, pause, resume, rewind, start, thirdQuartile.

    Optionally supported

    Because Android applications do not typically control the device's volume, the mute and unmute events will generally not be fired.

    Back to top

    Implementation notes

    The SDK is compatible with Android versions 2.1 and higher.

    Back to top

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.