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 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, hold back the mVideoView.start()method until the pre-roll adverts have played, and not as soon as if there were no adverts. So that the content does not re-start after post-roll adverts play, NAGRA advises 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. The removal action can be taken as late as possible, such as on receipt of the Ad Started event, to reduce the black frame time. 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 the 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.

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 callrequestAds()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, NAGRA advises you 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.