Playback of linear adverts

Layout XML to support linear adverts

For each layout and screen density that needs to support adverts, you may need to edit the layout files.

The following example shows a layout identified as ad_container being allocated for the rendering of linear adverts.

...
<RelativeLayout
    android:id="@+id/player_container"
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    tools:context="com.nagra.example.dynamicima.MainActivity">

    <RelativeLayout
        android:id="@+id/ad_container"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:background="@null"/>

</RelativeLayout>
...

Player Java source code

  • Importing the IMAWrapper classes (adjust the package path if you changed the source code).

    Two additional attributes IMAWrapper and IMAWrapperDelegate are required in the code for the class that extends Activity:

    import com.nagra.example.dynamicima.adverts.IMAWrapper;
    import com.nagra.example.dynamicima.adverts.IMAWrapperDelegate;
    
  • Implementing the wrapper delegate.

    The delegate needs to implement functions for the following to handle the interactions between the adverts manager and the application.

    private IMAWrapperDelegate mIMADelegate = new IMAWrapperDelegate() {
      @Override
      public void resumeContent(IMAWrapperResumeType xResumeType) {
        // Warning: Consider whether it is appropriate to (re-)start here
        // It is advisable to check if the content has completed
        mVideoView.start();
      }
    
      @Override
      public void pauseContent() {
        mVideoView.pause();
      }
    
      @Override
      public long getContentPosition() {
        return mVideoView.getCurrentPosition();
      }
    
      @Override
      public long getContentDuration() {
        if (null != mVideoView) {
          return mVideoView.getDuration();
        }
        return 0;
      }
    
      @Override
      public void advertStarted() {
        ...
      }
    
      @Override
      public void completedCallback() {
        ...
      }
    
      @Override
      public void logEvent(Map<String, String> xAdData) {
        ...
      }
      ...
    }
    

    To ensure that pre-roll adverts play before the content, you are advised to hold back the mVideoView.start() method until the pre-roll adverts have played, and not played as soon as it would have been if there were no adverts. So that the content does not re-start after post-roll adverts play, it is advised that a check is made to see if the content has already completed.

    Between adverts in a pod, or just before the start of an advert, a freeze frame of the content will be seen unless action is taken to avoid it. If you prefer to display a black frame, remove the video view when adverts start and reinstate it on completion.

    Any latency with the Google IMA system starting playback of an advert may elongate the freeze frame or black screen. To reduce the black frame time, the remove action can be taken as late as possible, such as on receipt of the Ad Started event. You can do this by removing the view when the IMAWrapperDelegate advertStarted() method is called.

    To log more information about the Google IMA system, you can implement appropriate code in the logEvent() method.

    Google IMA reports errors via the IMAWrapper and this method in the IMAWrapperDelegate.

  • Instantiating the wrapper.

    During creation of this activity, such as within the onCreate() method, you must create and configure the IMAWrapper member and then call startAdsServices() on it, passing the user interface ViewGroup set aside for linear adverts as well as the configuration options selected.

    ViewGroup adUiContainerViewGroup = (ViewGroup) findViewById(R.id.ad_container);
    
    mIMAWrapper = new IMAWrapper(mContext);
    mIMAWrapper.startAdsServices(adUiContainerViewGroup);
    

    The call to startAdsServices() is slightly different if companion adverts are also used, see Playback of companion adverts.

  • Associating the delegate to the wrapper.

    The wrapper needs to be made aware of the delegate via the setDelegate() method.

    mIMAWrapper.setDelegate(mIMADelegate);
    

    Alternatively, you can pass the delegate to the wrapper's constructor when you create it:

    mIMAWrapper = new IMAWrapper(mContext, mIMADelegate);
    
  • Requesting the adverts.

    Pass the advert tag URI into the IMAWrapper via the requestAds() method.

    mIMAWrapper.requestAds(xAdvertTag);
    

    You should call requestAds() as early as possible to minimise latency in retrieving the ads.

Replacing playback content (Zapping)

Destroying the IMAWrapper instance cancels any scheduled adverts and terminates a playing advert if it exists.
If you keep the IMAWrapper instance, you must request a new advert session with requestAds() whenever the playback content changes. A stopIMAServices() method is provided in the IMAWrapper to clean up an old configuration and its associated instances.

For a better user experience, you are advised to explicitly pause the new content after the new URI is set to allow for pre-roll adverts to appear before any of the new content is shown

Next step: Enable playback of companion adverts