Android Advanced Topics

Ad rules

IMA Android SDK v3 supports fully automated ad playlists. This feature will insert ad breaks into the content as specified in Doubleclick for Publishers when trafficking your ads. It also greatly simplifies the video player code necessary to support ad breaks, including pre-rolls, mid-rolls and post-rolls.

  • When trafficking the ads in DFP, it is possible to specify various ad rules like "always play ad break at the beginning of the content" or "play a one minute ad break every 30 minutes of content".
  • When ads are requested, the ad server can return an ad playlist. The SDK processes the playlist and automatically schedules the ad breaks that have been specified.
  • Since Android uses the same video player for both ad and content playback, if you plan to implement ad rules, you must save the playhead position of your content when an ad starts, then seek to that position when the ad finishes. Be sure to implement the VideoAdPlayer interface in your video player. This will ensure that ad breaks are automatically inserted at the times specified in DFP.
    private boolean playingContent = true;
    private int contentPosition = -1;
    private List callbacks =
        new ArrayList();
    
    @Override
    public void addCallback(VideoAdPlayerCallback callback) {
      callbacks.add(callback);
    }
    
    @Override
    public void removeCallback(VideoAdPlayerCallback callback) {
      callbacks.remove(callback);
    }
    
    public void loadContent()
      playingContent = true;
      load(CONTENT_URL);
    }
    
    @Override
    public void loadAd(String mediaUrl) {
      playingContent = false;
      load(mediaUrl);
    }
    
    public void pauseContent() {
      savePosition();
      pause();
    }
    
    @Override
    public void pauseAd() {
      pause();
    }
    
    private void pause() {
      myVideoView.pause();
      for (VideoAdPlayerCallback callback : callbacks) {
        callback.onPause();
      }
    }
    
    public void resumeContent() {
      loadContent();
      if (contentPosition > 0) {
        restorePosition();
      }
      resume();
    }
    
    @Override
    public void resumeAd() {
      resume();
    }
    
    private void resume() {
      myVideoView.start();
      for (VideoAdPlayerCallback callback : callbacks) {
        callback.onResume();
      }
    }
    
    public void savePosition() {
      contentPosition = myVideoView.getCurrentPosition();
    }
    
    public void restorePosition() {
      myVideoView.seekTo(contentPosition);
    }
    
  • The CONTENT_PAUSE_REQUESTED and CONTENT_RESUME_REQUESTED events are used to pause and resume the content when ad breaks are played. Refer to the relevant API documentation for details on these events.

Note: When the content has finished playing or the user has stopped playback, be sure to call AdsLoader.contentComplete in order to signal to the SDK that the content is done. The SDK will then play the post-roll ad break, if one has been scheduled. The ALL_ADS_COMPLETED event will be raised when ALL ad breaks have been played. In addition, note that content tracking begins when init() is called and you should always call init() before playing content.

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.

Implementation notes

  • The SDK is compatible with Android versions 2.3 and higher.
  • Be sure to disable seeking in your video player while ads are being played. If the SDK detects seeking during an ad, it will throw an error.

Reducing Latency - Best Practices

The key to reducing latency in your IMA-enabled app is to do as much IMA-related set up as early as possible. You can do all of the following in your app as early as you like before playing ads:

  • Define your content playhead tracker.
  • Create your AdDisplayContainer.
  • Create your ImaSdkFactory.
  • Create your AdsLoader.
  • Create your AdsManager.
  • Request ads.
  • Obtain your AdsManager instance and register event handlers.
Doing all of the above will initialize the IMA SDK and request and parse your ads response all before your user even clicks play on your video. When you're ready to play the ads, call AdsManager.init() and wait for the LOADED event to play ads. For more information on making your entire page more responsive, see the tips on evaluating network performance in the Chrome documentation.

Send feedback about...

IMA SDK for Android
Need help? Visit our support page.