Instream video ads implementation

Adform Advertising SDK can also be used to show instream videos ads. There are two ways of playing instream video ads with our SDK:

• Use SDK player to show content video and ads;
• Use external(third party) video player to show content video and use the SDK player only to show ads;

Ad types

Adform Advertising SDK can show three types of instream video ads: pre-roll, mid-roll and post-roll.

Pre-roll ads

Pre-roll ads are displayed before the content video. To use this type of ads you need to set pre-roll master tag id in Builder object. These ads are played only once when user starts the playback of content video, if user replays the video the ad will not be shown again.

Post-roll ads

Post-roll ads are displayed after the content video has finished playing. To use this type of ads you need to set post-roll master tag id in Builder object. These ads are played only once when the content video has finished playing, if user replays the video the ad will not be shown again.

Mid-roll ads

Mid-roll ads are shown in the middle of content video at breakpoints. To use this type of ads you need to set mid-roll master tag id in Builder object. Mid-roll ads may be shown multiple times during single video.

Breakpoints at which to show ads may be defined in several ways in Adform UI. You can display ads at fixed times and time intervals, at time in percentage relative to content duration or at cue points.

Using SDK player

To implement instream video ads using only SDK player you have to follow these steps:

In order to create Adform VideoPlayer, you must use VideoPlayer.Builder() object. Use build method to get VideoPlayer. At bare minimum, a Builder object must include the following:

• Context
• Container
• VideoUrl
• At least one master tag

In the code snippet, it looks like following:

    mVideoPlayer = new VideoPlayer.Builder()
        .setContext(this) //set context for player. It's mandatory.
        .setContainer(frameLayout) //set layout where player should be placed. It is mandatory mandatory property in builder.
        .setVideoUrl("http://your-video-domain.com/video_file.mp4") // URL of video content, it is mandatory for internal player.
        .setPreRollMasterTag(PREROLL_MASTER_TAG) //preroll master tag.
        .setMidRollMasterTag(MID_MASTER_TAG) //midroll master tag. To setup fully, you need to set up breakpoints in Adform UI.
        .setPostRollMasterTag(POSTROLL_MASTER_TAG) //postroll master tag.
        .setMidRollShowControl(new MidRollShowControl() { //It is optional builder method.
            @Override
            public boolean showMidRoll() {
                return true; //if it returns true player should show mid roll ad, if false mid roll ad would not be shown. 
            }
        })
        .setCuePoints(cuePoints) // Set cue points to player. It's optional.
        .setPreloadAds(true) // If true tries to fetch ad data before its showing time. It's optional property. Default is set to false. 
        .setContentPlayerPreparedListener(new VideoPlayer.ContentPlayerPreparedListener() {
            @Override
            public void onPrepared() {
                mVideoPlayer.playContent(); // in order to automatically start playing the video
            }
        })
        .build();

Also, VideoPlayer needs methods that would indicate of application activity, such as onResume, onPause, onDestroy, onSaveInstanceState and onRestoreInstanceState .

    @Override
    protected void onResume() {
        super.onResume();
        if(mVideoPlayer != null){
            mVideoPlayer.onResume();
        }
    }

    @Override
    protected void onPause() {
        super.onPause();
        if(mVideoPlayer != null) {
            mVideoPlayer.onPause();
        }
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        if(mVideoPlayer != null) {
            mVideoPlayer.onDestroy();
        }
    }
    
    @Override
    public void onSaveInstanceState(Bundle outState) {
        super.onSaveInstanceState(outState);
        if(mVideoPlayer != null){
            mVideoPlayer.onSaveInstanceState(outState);
        }
    }


    @Override
    protected void onRestoreInstanceState(Bundle savedInstanceState) {
        super.onRestoreInstanceState(savedInstanceState);
        if(mVideoPlayer != null){
            mVideoPlayer.onRestoreInstanceState(savedInstanceState);
        }
    }

In order to play content, use the following method

	mVideoPlayer.playContent();

To pause the content player

	mVideoPlayer.pauseContent();

Using external video player

If you wish to use a third-party or even your own video player you can do so. To use instream video ads with external video player you need to:

1. First of all create a video player of you choice. We are going to use EMVideoView for the example.

	mEmVideoView = (EMVideoView)findViewById(R.id.video_play_activity_video_view);

2. Then you need to create an instance of VideoPlayer.ExternalBuilder() and use it to create Adform VideoPlayer object.

At bare minimum, a Builder object must include the following:

• Context
• Container
• VideoUrl
• At least one master tag
• Implement ContentPlayback interface

In the code snippet, it looks like following:

	mVideoPlayer = new VideoPlayer.ExternalBuilder()
        .setContext(this) //set context for player. It's mandatory.
        .setContainer(frameLayout) //set layout where player should be placed. It is mandatory mandatory property in builder.
        .setPreRollMasterTag(PREROLL_MASTER_TAG) //preroll master tag.
        .setMidRollMasterTag(MID_MASTER_TAG) //midroll master tag. To setup fully, you need to set up breakpoints in Adform UI.
        .setPostRollMasterTag(POSTROLL_MASTER_TAG) //postroll master tag.
        .setCuePoints(cuePoints) // Set cue points to player. It's optional.
        .setPreloadAds(true) // If true tries to fetch ad data before its showing time. It's optional property. Default is set to false. 
        .setContentPlayback(new ContentPlayback() { // set ContentPlayback implementation, it is mandatory.
            @Override
            public void playContent() {
                mEmVideoView.start(); //in this method you should start playback of your external player.
            }

            @Override
            public void pauseContent() {
                mEmVideoView.pause(); //in this method you should pause playback of your external player.
            }

            @Override
            public void setFullscreen(boolean isFullscreen) {
                //in this method you should change external player state to fullscreen or exit from fullscreen depending on isFullscreen flag.
                if (isFullscreen) {
                    goFullscreen();
                } else {
                    exitFullscreen();
                }
            }

            @Override
            public boolean isFullscreen() {
            	//in this method you should return external player fullscreen state.
                return false;
            }

            @Override
            public long getContentDuration() {
            	//in this method you should return your video content duration in miliseconds.
                return mEmVideoView.getDuration();
            }

            @Override
            public long getCurrentTimePosition() {
                //in this method you should return current time position of the video playback.
                return mEmVideoView.getCurrentPosition();
            }
        })
        .build();

Also, VideoPlayer needs methods that would indicate of application activity, such as onResume, onPause, onDestroy, onSaveInstanceState and onRestoreInstanceState .

    @Override
    protected void onResume() {
        super.onResume();
        if(mVideoPlayer != null){
            mVideoPlayer.onResume();
        }
    }

    @Override
    protected void onPause() {
        super.onPause();
        if(mVideoPlayer != null) {
            mVideoPlayer.onPause();
        }
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        if(mVideoPlayer != null) {
            mVideoPlayer.onDestroy();
        }
    }
    
    @Override
    public void onSaveInstanceState(Bundle outState) {
        super.onSaveInstanceState(outState);
        if(mVideoPlayer != null){
            mVideoPlayer.onSaveInstanceState(outState);
        }
    }


    @Override
    protected void onRestoreInstanceState(Bundle savedInstanceState) {
        super.onRestoreInstanceState(savedInstanceState);
        if(mVideoPlayer != null){
            mVideoPlayer.onRestoreInstanceState(savedInstanceState);
        }
    }

3. Also you must post notifications when content playback starts(mVideoPlayer.onPlayStart()) and finishes(mVideoPlayer.onVideoPlaybackCompleted()).

An example with EmVideoView player:

	mEmVideoView.addExoPlayerListener(new ExoPlayerListener() {
        @Override
        public void onStateChanged(boolean playWhenReady, int playbackState) {
            if (ExoPlayer.STATE_ENDED == playbackState) {
                mVideoPlayer.onVideoPlaybackCompleted();
            }
        }
    });
    
    mEmVideoView.setVideoViewControlsCallback(new EMVideoViewControlsCallback() {
        @Override
        public boolean onPlayPauseClicked() {
            if(!mEmVideoView.isPlaying() && mInitialStart){
                mInitialStart = false;
                mVideoPlayer.onPlayStart();
            }
            return false;
        }

    });

Setting cue points

Cue points must be defined not only on UI side but on the SDK player too. Each cue point must have a time offset when an ad should be shown and an identifier. The identifier is used to connect cue points defined in Adform UI to cue points set to video player.

You could add cue point to the player for mid roll ads at any time. Example bellow shows you how to set cue points to VideoPlayer:

	CuePoint cuePoint = new CuePoint(1, 20); //cue point with identifier 1 and 20 value.
	mVideoPlayer.addCuePoint(cuePoint);