In-stream Video Ad

1、Integration Reference#

TP version	illustrate
V9.3.0.1	Support Vast (Google Ad Manager interstitial ads)
V9.9.0.1	Optimize the callback mechanism. You will receive a loaded callback only after calling loadAd() once.
V10.1.0.1	Support Adx insertion.
V10.3.0.1	Support VMAP.
V10.5.0.1	Added TPMediaVideo.setIMAEventListener(TPMediaVideoAdapter.OnIMAEventListener listener) to listen to all AdEvent events in VMAP
V12.5.0.1	Added new API to support Vast multi-cache.

Ads play in a separate video player positioned on top of the app's content video player. Refer to the picture below:
Create an ad display container when requesting the ads.

NOTES#

It is not recommended to perform ad loading methods in oneLayerLoadFailed and onAdFailed callbacks. For the advertising platform, multiple requests in a short period of time are not easy to be filled, and it will also cause multiple invalid requests and may also cause application lag; if the product logic wants to initiate requests here, the developer needs to control the time interval. and times, such as initiating requests after 10S, 30S, and 60S respectively.
【V10.3.0.1 +】Start to support VMAP of Google IMA
Using VMAP requires setting the ContentProgressProvider before loading the advertisement (in compliance with IMA's IMAContentPlayhead protocol)
After receiving the AD_BREAK_READY callback of onEvent, the developer manually calls the tpCustomMediaVideoAd.start("") method to play the advertisement.

2、API introduction#

TPMediaVideo#

method	illustrate
TPMediaVideo(Context context, String adUnitId)	Create a mid-roll ad object. adUnitId is the advertising slot ID created on the TP platform.
loadAd(ViewGroup container，TPVideoAdPlayer tpVideoAdPlayer)	Request an ad. `container` Pass in the container required to display ads. It is required and cannot be null. It is recommended to use RelativeLayout to facilitate the control of video playback in the center. `TPVideoAdPlayer` is an interface class adapted to Adx and IMA and must be passed.
loadAd(Object objectVideo)	Request an ad. (supports Vast multi-buffer). V12.5.0.1 New API. objectVideo needs to be passed into the listening callback of TPVideoPlayerListener.
setCustomParams`(Map<String, Object>` map)	Custom key-value. Needs to be called before loadAd.
isReady()	Check if ads are available. Returned `true` to indicate that ads are available.
getVideoAd()	After the advertisement is loaded successfully, obtain the advertisement cache `TPCustomMediaVideoAd`.
setAdListener(MediaVideoAdListener listener)	Set ad listening callback.
setIMAEventListener (TPMediaVideoAdapter.OnIMAEventListener listener)	V10.5.0.1 adds callback monitoring. Used when VMAP (multi-map). Set up the listener through the TpMediaVideo object, and you can get all the AdEvent events in the callback. Replaced the deprecated listener `TPCustomMediaVideoAd.setIMAEventListener()`.
onDestroy()	Destroy and release `TPMediaVideod` related objects.

TPCustomMediaVideoAd#

TPCustomMediaVideoAd is the advertising cache object

API	illustrate
pause()	Pause after playing.
resume()	Continue playing ads after pausing.
start(String adSceneId)	Play ads. `adSceneId` advertising scene ID, if not used, you can pass null directly.
setCustomShowData(`Map<String,Object>` customShowData)	Custom data, called before displaying ads.
getCustomNetworkObj()	Get the IMA advertising object AdsManager.`AdsManager adsManager =(AdsManager)tpCustomMediaVideoAd.getCustomNetworkObj();`
getAdDisplayContainer()	Get the ad display container (supports Vast multi-cache). V12.5.0.1 adds new API.
getTPAdVideoPlayer()	Get the TPAdVideoPlayer passed in when requesting ads (supports Vast multi-cache). V12.5.0.1 adds new API.
setIMAEventListener (TPMediaVideoAdapter.OnIMAEventListener listener)	V9.7.10.1 adds a new callback listener (V10.5.0.1+ is obsolete) Through the listener set by the ad cache object TPCustomMediaVideoAd, all AdEvent events can be obtained in the callback.
onDestroy()	Destroy and release IMA related objects.

MediaVideoAdListener#

method	illustrate
onAdLoaded(TPAdInfo tpAdInfo)	After one loadAd, the ad is loaded successfully. V9.9.0.1 optimizes the callback mechanism. Only when the developer actively calls load will the corresponding callback be loaded. If no callback is made, there will be no callback.
onAdFailed(TPAdError error)
onAdClicked(TPAdInfo tpAdInfo)	The jump button is clicked.
onAdResume(TPAdInfo tpAdInfo)	After pausing, the ad continues to play.
onAdPause(TPAdInfo tpAdInfo)	After being shown, the ad is paused.
onAdVideoStart(TPAdInfo tpAdInfo)	Advertisement starts playing.
onAdVideoEnd(TPAdInfo tpAdInfo)	Advertisement ends.
onAdVideoError(TPAdInfo tpAdInfo, TPAdError error)	Advertisement failed to play.
onAdSkiped(TPAdInfo tpAdInfo)	Jumpable ads, users click to skip.
onAdTapped(TPAdInfo tpAdInfo)	The video area is clicked.
onAdProgress(TPAdInfo tpAdInfo, float progress, double totaltime)	Playback progress. progress is the current playback progress and totaltime is the total duration of the advertisement.

Other API#

Custom key-value: setCustomParams (Map<String, Object>map) configuration
Set before requesting advertising loadAd(ViewGroup container，TPVideoAdPlayer tpVideoAdPlayer)API

Parameter key	type	Description value
ima_ui_countdown	int	The UI countdown is displayed by default. 1 is shown; others are hidden.
ima_setting_language	String	Customize the local language to specify the language used when localizing advertisements and player interface controls. The supported codes can be found in the Localization guide。For example: "en" sets the local language to English.
ima_load_video_timeout	int	Custom timeout. V9.9.0.1+ supported. Unit: milliseconds. The default time is 8000 milliseconds.
platform_ID	`Map<String, String>`	Parameters are passed by different platforms. V11.1.10.1+supported.

Sample code：

Take setting a custom timeout as an example

private int mLoadVideoTimeout = 8000;
...
Map<String, Object> mLocalExtras = new HashMap<>();
mLocalExtras.put("ima_load_video_timeout", mLoadVideoTimeout);
tpMediaVideo.setCustomParams(mLocalExtras);

tpMediaVideo.loadAd(mContainer,tpVideoAdPlayer);

Parameters are passed by different platforms

Map<String, Object> mLocalExtras = new HashMap<>();

Map<String, String> paramsGAM = new HashMap<>();
Map<String, String> paramsPremiumAds = new HashMap<>();
Map<String, String> paramsBeesAds = new HashMap<>();
Map<String, String> paramsMangoX = new HashMap<>();

Map<String, Map<String, String>> networkParams = new HashMap<>();
networkParams.put("platform_48",paramsGAM);
networkParams.put("platform_64",paramsPremiumAds);
networkParams.put("platform_69",paramsBeesAds);
networkParams.put("platform_71",paramsMangoX);

mLocalExtras.put("ima_url_parameters", networkParams);

tpMediaVideo.setCustomParams(mLocalExtras);

3、Vast Ads#

The container for displaying ads needs to be passed in when loading.
tpCustomMediaVideoAd.pause() Interstitial advertisements will be paused when the program switches to the background. If you need to switch to the foreground to continue playing advertisements, you can call and methods in the life cycle onPause() and onResume() respectively for tpCustomMediaVideoAd.resume() control.
V10.1.0.1 start support Adx MediaVideo.Create a NewVideoAdPlayerAdapter class with the VideoView, and adapt it to IMA's & Adx's VideoAdPlayer interface. This class will handle content and ad playback, and will contain the set of methods that a video player must implement to be used by the IMA SDK.For the specific implementation of NewVideoAdPlayerAdapter, please refer to Demo

Request an Ad#

private RelativeLayout mContainer;
private NewVideoAdPlayerAdapter newVideoAdPlayerAdpter;
private TPMediaVideo tpMediaVideo;
...

tpMediaVideo = new TPMediaVideo(context，"adUnitId created on the TP platform");
tpMediaVideo.setAdListener(new MediaVideoAdListener());
// It is recommended that the container use RelativeLayout to center the advertising videoview.
adContainer = new RelativeLayout(context);

AudioManager audioManager = (AudioManager) MediaVideoActiviy.this.getSystemService(Context.AUDIO_SERVICE);
VideoView videoView = new VideoView(MediaVideoActiviy.this);
// NewVideoAdPlayerAdapter class created to adapt to the TPVideoAdPlayer interface of Adx and IMA
newVideoAdPlayerAdpter = new VideoAdPlayerAdapter(videoView, audioManager, true);

// Container and NewVideoAdPlayerAdapter are required parameters
tpMediaVideo.loadAd(mContainer,newVideoAdPlayerAdpter);

Play an ad#

tpMediaVideo.setAdListener(new MediaVideoAdListener() {
     @Override
     public void onAdLoaded(TPAdInfo tpAdInfo) {
        // After receiving the successful loading callback
        boolean ready = tpMediaVideo.isReady();
        if (ready) {
            Log.i(TAG, "isReady: " + ready);
            // Get the ad cache tpCustomMediaVideoAd
            tpCustomMediaVideoAd = tpMediaVideo.getVideoAd();

            // Display through the ad cache object start()
            if (tpCustomMediaVideoAd != null) {
                tpCustomMediaVideoAd.start(null);
            }
        }
    }
});

V12.5.0.1+ Added API to support Vast multi-cache#

Request an Ad#

private RelativeLayout mContainer;
private TPMediaVideo tpMediaVideo;
...

public void loadMediaVideo() {
    tpMediaVideo = new TPMediaVideo(context，"adUnitId created on the TP platform");
    tpMediaVideo.setAdListener(new MediaVideoAdListener());

    TPVideoPlayerListener tpVideoPlayerListener = new TPVideoPlayerListener() {
            @Override
            public Object getTPVideoPlayer() {
                // Multiple caches need to be passed into multiple TPVideoPlayer
                return getVideoAdPlayer();
            }

            @Override
            public Object getContentProgressProvider() {
               // ContentProgressProvider
                return null;
            }
        };

    tpMediaVideo.loadAd(tpVideoPlayerListener);
}

private VideoView videoView;
public TPVideoAdPlayer getVideoAdPlayer() {
    AudioManager audioManager = (AudioManager) MediaVideoActiviy.this.getSystemService(Context.AUDIO_SERVICE);
    videoView = new VideoView(MediaVideoActiviy.this);
    // NewVideoAdPlayerAdapter class created to adapt to the TPVideoAdPlayer interface of Adx and IMA
    VideoAdPlayerAdapter videoAdPlayer = new VideoAdPlayerAdapter(videoView, audioManager, true);
｝

Play an ad#

tpMediaVideo.setAdListener(new MediaVideoAdListener() {
     @Override
     public void onAdLoaded(TPAdInfo tpAdInfo) {
        // After receiving the successful loading callback
        boolean ready = tpMediaVideo.isReady();
        if (ready) {
            // Get the ad cache tpCustomMediaVideoAd
            tpCustomMediaVideoAd = tpMediaVideo.getVideoAd();
            // Get the TPAdVideoPlayer used by the current cache object
            Object tpAdVideoPlayerObj = tpCustomMediaVideoAd.getTPAdVideoPlayer();
            TPVideoAdPlayer tpAdVideoPlayer = null;
            if (tpAdVideoPlayerObj instanceof TPVideoAdPlayer) {
                tpAdVideoPlayer = (TPVideoAdPlayer)tpAdVideoPlayerObj;
            }

            // Get the ad display container of the current cache object
            Object adDisplayContainerObj = tpCustomMediaVideoAd.getAdDisplayContainer();
            if (adDisplayContainerObj instanceof AdDisplayContainer) {
                // Google IMA Vast
                AdDisplayContainer adDisplayContainer = (AdDisplayContainer) adDisplayContainerObj;
                if (adDisplayContainer != null) {
                    ViewGroup adContainer = adDisplayContainer.getAdContainer();
                    if (adContainer != null) {
                        if (videoView.getParent() != null) {
                            ((ViewGroup) videoView.getParent()).removeView(videoView);
                        }
                        mAdContainer.addView(videoView);
                        mAdContainer.addView(adContainer);
                        // Display through the ad cache object start()
                        tpCustomMediaVideoAd.start("");
                    }
                }
            }else if (adDisplayContainerObj instanceof FrameLayout) {
                // TP Exchange
                FrameLayout adContainer = (FrameLayout) adDisplayContainerObj;
                if (adContainer != null) {
                    if (videoView.getParent() != null) {
                        ((ViewGroup) videoView.getParent()).removeView(videoView);
                    }
                    mAdContainer.addView(videoView);
                    mAdContainer.addView(adContainer);
                    // Display through the ad cache object start()
                    tpCustomMediaVideoAd.start("");
                }
            }
        }
    }
});

4、VMAP Ads#

The container for displaying ads needs to be passed in when loading.
ContentProgressProvider needs to be passed in before requesting advertisements
Set up setIMAEventListener to monitor. Developers need to monitor the AD_BREAK_READY callback to control the playback timing.
For specific implementation, please refer to the code example in Demo VideoPlayerController
When creating an advertising slot, you need to select the VMAP protocol type, as shown in the figure:

Request an Ad#

private RelativeLayout mContainer;
private VideoAdPlayerAdapter newVideoAdPlayerAdpter;
private TPMediaVideo tpMediaVideo;
private ContentProgressProvider contentProgressProvider;

...

tpMediaVideo = new TPMediaVideo(context，"adUnitId created on the TP platform");
tpMediaVideo.setAdListener(new MediaVideoAdListener());
// It is recommended that the container use RelativeLayout to center the advertising videoview.
adContainer = new RelativeLayout(context);

AudioManager audioManager = (AudioManager) MediaVideoActiviy.this.getSystemService(Context.AUDIO_SERVICE);
VideoView videoView = new VideoView(MediaVideoActiviy.this);
newVideoAdPlayerAdpter = new VideoAdPlayerAdapter(videoView, audioManager, true);

// SDK implements the ContentProgressProvider interface for checking content progress
Map<String, Object> mLocalExtras = new HashMap<>();
mLocalExtras.put("ima_content_provider", contentProgressProvider);
tpMediaVideo.setCustomParams(mLocalExtras);

// Container and NewVideoAdPlayerAdapter are required parameters
tpMediaVideo.loadAd(mContainer,newVideoAdPlayerAdpter);

Play an ad#

V10.5.0.1 adds new callback monitoring, used when VMAP (multiple posts)

// Set up monitoring through the TpMediaVideo object, and you can get all the AdEvent events in the callback
tpMediaVideo.setIMAEventListener(new TPMediaVideoAdapter.OnIMAEventListener() {
    @Override
    public void onEvent(Object o) {
        AdEvent adEvent = (AdEvent)o;
        switch (adEvent.getType()) {
            case AD_BREAK_READY:
                // VMAP ads are loaded successfully, developers need to control the timing of calling playback by themselves
                // Get the ad cache tpCustomMediaVideoAd and display it through the ad cache object start()
                boolean ready = tpMediaVideo.isReady();
                if (ready) {
                    tpCustomMediaVideoAd = tpMediaVideo.getVideoAd();

                    if (tpCustomMediaVideoAd != null) {
                        tpCustomMediaVideoAd.start(null);
                    }
                }
            ...
            break;
        }
    }
});