Menu

In-Stream Video Ads

1. Integration Suggestions

Video streaming ads are played in a separate video player that sits on top of the app's content video player. You control the content video playback, while the TopOn SDK handles the ad playback. The specific rendering style is as follows:

  • Through ATAdInfo#getUrlTagParams(), you can obtain the custom Tag Key-Value Map passed in when the ad cache was requested
  • The ad cache MediaVideoAd obtained through ATMediaVideo#getMediaVideoAd() is bound to the ATVideoAdPlayer passed in at request time
  • Please refer to here for more information about the IMA SDK
  • Through TUAdInfo#getUrlTagParams(), you can obtain the custom Tag Key-Value Map passed in when the ad cache was requested
  • The ad cache TMediaVideoAd obtained through TUMediaVideo#getMediaVideoAd() is bound to the TUVideoAdPlayer passed in at request time
  • Please refer to here for more information about the IMA SDK

java Copy
ATMediaVideoConfig.Builder atMediaVideoConfigBuilder = new ATMediaVideoConfig.Builder();
ATMediaVideo mATMediaVideo = new ATMediaVideo(activity, "your placement id", 
         mVideoPlayerWithAdPlayback.getVideoAdPlayer(), atMediaVideoConfigBuilder.build());
mATMediaVideo.setAdListener(new ATMediaVideoEventListener() {
    @Override
    public void onMediaVideoAdLoaded() { }

    @Override
    public void onMediaVideoAdLoadFailed(AdError adError) { }

    @Override
    public void onMediaVideoAdClick(ATAdInfo adInfo) { }

    @Override
    public void onMediaVideoAdResume(ATAdInfo adInfo) { }

    @Override
    public void onMediaVideoAdPause(ATAdInfo adInfo) { }

    @Override
    public void onMediaVideoAdStart(ATAdInfo adInfo) { }

    @Override
    public void onMediaVideoAdEnd(ATAdInfo adInfo) { }

    @Override
    public void onMediaVideoAdPlayError(AdError adError, ATAdInfo adInfo) { }

    @Override
    public void onMediaVideoAdSkiped(ATAdInfo adInfo) { }

    @Override
    public void onMediaVideoAdTapped(ATAdInfo adInfo) { }

    @Override
    public void onMediaVideoAdProgress(float v, double v1) { }
});
//IMA Event Listener
mATMediaVideo.setIMAEventListener(new OnIMAEventListener() {
    @Override
    public void onEvent(Object adEvent) { }
});
mATMediaVideo.loadAd();
java Copy
TUMediaVideoConfig.Builder tuMediaVideoConfigBuilder = new TUMediaVideoConfig.Builder();
TUMediaVideo mTUMediaVideo = new TUMediaVideo(activity, "your placement id", 
         mVideoPlayerWithAdPlayback.getVideoAdPlayer(), tuMediaVideoConfigBuilder.build());
mTUMediaVideo.setAdListener(new TUMediaVideoEventListener() {
    @Override
    public void onMediaVideoAdLoaded() { }

    @Override
    public void onMediaVideoAdLoadFailed(AdError adError) { }

    @Override
    public void onMediaVideoAdClick(TUAdInfo adInfo) { }

    @Override
    public void onMediaVideoAdResume(TUAdInfo adInfo) { }

    @Override
    public void onMediaVideoAdPause(TUAdInfo adInfo) { }

    @Override
    public void onMediaVideoAdStart(TUAdInfo adInfo) { }

    @Override
    public void onMediaVideoAdEnd(TUAdInfo adInfo) { }

    @Override
    public void onMediaVideoAdPlayError(AdError adError, TUAdInfo adInfo) { }

    @Override
    public void onMediaVideoAdSkiped(TUAdInfo adInfo) { }

    @Override
    public void onMediaVideoAdTapped(TUAdInfo adInfo) { }

    @Override
    public void onMediaVideoAdProgress(float v, double v1) { }
});
//IMA Event Listener
mTUMediaVideo.setIMAEventListener(new OnIMAEventListener() {
    @Override
    public void onEvent(Object adEvent) { }
});
mTUMediaVideo.loadAd();

  • Before displaying a VMAP ad, you need to call MediaVideoAd#setContentProgressProvider(Object contentProgressProvider) to pass the IMA SDK ContentProgressProvider object, to avoid affecting the VMAP ad display.
  • Before displaying a MediaVideoAd, you need to call MediaVideoAd#setContainer(ViewGroup container) to pass the ad display container. It is recommended that this container overlays the PlayerView to avoid affecting ad clicks.
  • VMAP ads need to wait for the IMA Event AD_BREAK_READY to be triggered before calling MediaVideoAd#start() to display the ad.
java Copy
if (mATMediaVideo.isAdReady()) {
    if (mMediaVideoAd != null) {
        //destroy showing media video ad
            mMediaVideoAd.onDestroy();
            mMediaVideoAd = null;
    }
    //reset player state and content video play position
    mVideoPlayerWithAdPlayback.resetInnerVideoPlayerAndParams();

    ATShowConfig showConfig = new ATShowConfig.Builder().scenarioId("your scenario id").build();
    mMediaVideoAd = mATMediaVideo.getMediaVideoAd(showConfig);
    
    mVideoPlayerWithAdPlayback.setReadyToPlayContent(true);
    //must setContainer(container) before start()
    if (mVideoPlayerWithAdPlayback.getAdUiContainer() != null) {
        mVideoPlayerWithAdPlayback.getAdUiContainer().removeAllViews();
    }
    //need setContainer
    mMediaVideoAd.setContainer(mVideoPlayerWithAdPlayback.getAdUiContainer());
    //setContentProgressProvider(VMAP need)
    mMediaVideoAd.setContentProgressProvider(mVideoPlayerWithAdPlayback.getContentProgressProvider());
    //Call setOnIMAEventListener to bind MediaVideoAd and OnIMAEventListener
    mMediaVideoAd.setOnIMAEventListener(new OnIMAEventListener() {
        @Override
        public void onEvent(Object adEvent) {
            /**
             * do content resume、pause and start、destroy MediaVideoAd
             */
            if (adEvent instanceof AdEvent) {
                switch (((AdEvent) adEvent).getType()) {
                    case LOADED:
                        // AdEventType.LOADED will be fired when ads are ready to be
                        // played. AdsManager.start() begins ad playback. This method is
                        // ignored for VMAP or ad rules playlists, as the SDK will
                        // automatically start executing the playlist.
                        break;
                    case CONTENT_PAUSE_REQUESTED:
                        // AdEventType.CONTENT_PAUSE_REQUESTED is fired immediately before
                        // a video ad is played.
                        mVideoPlayerWithAdPlayback.pauseContentForAdPlayback();
                        break;
                    case CONTENT_RESUME_REQUESTED:
                        // AdEventType.CONTENT_RESUME_REQUESTED is fired when the ad is
                        // completed and you should start playing your content.
                        mVideoPlayerWithAdPlayback.resumeContentAfterAdPlayback();
                        break;
                    case PAUSED:
                        break;
                    case RESUMED:
                        break;
                    case AD_BREAK_READY:
                        // AdEventType.AD_BREAK_READY will be fired when VMAP ads are ready to be played.
                        // For VAMP ads, mMediaVideoAd.start() must be called after AdEventType.AD_BREAK_READY
                        if (mMediaVideoAd != null) {
                            mMediaVideoAd.start();
                        }
                        break;
                    case ALL_ADS_COMPLETED:
                        if (mMediaVideoAd != null) {
                            mMediaVideoAd.onDestroy();
                            mMediaVideoAd = null;
                        }
                        mVideoPlayerWithAdPlayback.resumeContentAfterAdPlayback();
                        mVideoPlayerWithAdPlayback.setReadyToPlayContent(false);
                        break;
                    case AD_BREAK_FETCH_ERROR:
                        // A CONTENT_RESUME_REQUESTED event should follow to trigger content playback.
                        if (mMediaVideoAd != null) {
                            mMediaVideoAd.onDestroy();
                            mMediaVideoAd = null;
                        }
                        mVideoPlayerWithAdPlayback.resumeContentAfterAdPlayback();
                        mVideoPlayerWithAdPlayback.setReadyToPlayContent(false);
                        break;
                    default:
                        break;
                }
            }
        }
    });
    if (mMediaVideoAd != null) {
        if (!mMediaVideoAd.isVMAPOffer()) {
            //VAST just load start
            mMediaVideoAd.start();
        } else {
            //VAMP wait OnIMAEventListener#AD_BREAK_READY call
        }
    }
}
java Copy
if (mTUMediaVideo.isAdReady()) {
    if (mMediaVideoAd != null) {
        //destroy showing media video ad
            mMediaVideoAd.onDestroy();
            mMediaVideoAd = null;
    }
    //reset player state and content video play position
    mVideoPlayerWithAdPlayback.resetInnerVideoPlayerAndParams();

    TUShowConfig showConfig = new TUShowConfig.Builder().scenarioId("your scenario id").build();
    mMediaVideoAd = mTUMediaVideo.getMediaVideoAd(showConfig);
    
    mVideoPlayerWithAdPlayback.setReadyToPlayContent(true);
    //must setContainer(container) before start()
    if (mVideoPlayerWithAdPlayback.getAdUiContainer() != null) {
        mVideoPlayerWithAdPlayback.getAdUiContainer().removeAllViews();
    }
    //need setContainer
    mMediaVideoAd.setContainer(mVideoPlayerWithAdPlayback.getAdUiContainer());
    //setContentProgressProvider(VMAP need)
    mMediaVideoAd.setContentProgressProvider(mVideoPlayerWithAdPlayback.getContentProgressProvider());
    //Call setOnIMAEventListener to bind MediaVideoAd and OnIMAEventListener
    mMediaVideoAd.setOnIMAEventListener(new OnIMAEventListener() {
        @Override
        public void onEvent(Object adEvent) {
            /**
             * do content resume、pause and start、destroy MediaVideoAd
             */
            if (adEvent instanceof AdEvent) {
                switch (((AdEvent) adEvent).getType()) {
                    case LOADED:
                        // AdEventType.LOADED will be fired when ads are ready to be
                        // played. AdsManager.start() begins ad playback. This method is
                        // ignored for VMAP or ad rules playlists, as the SDK will
                        // automatically start executing the playlist.
                        break;
                    case CONTENT_PAUSE_REQUESTED:
                        // AdEventType.CONTENT_PAUSE_REQUESTED is fired immediately before
                        // a video ad is played.
                        mVideoPlayerWithAdPlayback.pauseContentForAdPlayback();
                        break;
                    case CONTENT_RESUME_REQUESTED:
                        // AdEventType.CONTENT_RESUME_REQUESTED is fired when the ad is
                        // completed and you should start playing your content.
                        mVideoPlayerWithAdPlayback.resumeContentAfterAdPlayback();
                        break;
                    case PAUSED:
                        break;
                    case RESUMED:
                        break;
                    case AD_BREAK_READY:
                        // AdEventType.AD_BREAK_READY will be fired when VMAP ads are ready to be played.
                        // For VAMP ads, mMediaVideoAd.start() must be called after AdEventType.AD_BREAK_READY
                        if (mMediaVideoAd != null) {
                            mMediaVideoAd.start();
                        }
                        break;
                    case ALL_ADS_COMPLETED:
                        if (mMediaVideoAd != null) {
                            mMediaVideoAd.onDestroy();
                            mMediaVideoAd = null;
                        }
                        mVideoPlayerWithAdPlayback.resumeContentAfterAdPlayback();
                        mVideoPlayerWithAdPlayback.setReadyToPlayContent(false);
                        break;
                    case AD_BREAK_FETCH_ERROR:
                        // A CONTENT_RESUME_REQUESTED event should follow to trigger content playback.
                        if (mMediaVideoAd != null) {
                            mMediaVideoAd.onDestroy();
                            mMediaVideoAd = null;
                        }
                        mVideoPlayerWithAdPlayback.resumeContentAfterAdPlayback();
                        mVideoPlayerWithAdPlayback.setReadyToPlayContent(false);
                        break;
                    default:
                        break;
                }
            }
        }
    });
    if (mMediaVideoAd != null) {
        if (!mMediaVideoAd.isVMAPOffer()) {
            //VAST just load start
            mMediaVideoAd.start();
        } else {
            //VAMP wait OnIMAEventListener#AD_BREAK_READY call
        }
    }
}

4. Ad Scenario Statistics

Scenario Arrival Rate Statistics, presented in the dashboard's Data Reports -> Funnel Analysis Report -> Ad Scenario Arrival. It is recommended to call it in the correct place.

  1. First, call entryAdScenario()
  2. Then call isAdReady()
  3. Finally, call getMediaVideoAd()
Method Description
void entryAdScenario(String placementId, String scenarioId) Statistics of the current placement's cache status upon entering a business scenario. For specific usage, see Ad Scenario.
placementId: Placement ID.
scenarioId: Ad scenario ID (not required; passing null will count it under the default scenario).
java Copy
ATMediaVideo.entryAdScenario("your placement id", "your scenario id");
if (mATMediaVideo.isAdReady()) {
   ...
   ATShowConfig showConfig = new ATShowConfig.Builder()
                .scenarioId("your scenario id")
                .build();
    mMediaVideoAd = mATMediaVideo.getMediaVideoAd(showConfig);
   ...
}
java Copy
TUMediaVideo.entryAdScenario("your placement id", "your scenario id");
if (mTUMediaVideo.isAdReady()) {
   ...
   TUShowConfig showConfig = new TUShowConfig.Builder()
                .scenarioId("your scenario id")
                .build();
    mMediaVideoAd = mTUMediaVideo.getMediaVideoAd(showConfig);
   ...
}

5. Integration Reference

Sample Code: MediaVideoActivity.java in the Demo

Previous
Notes for Native Self-Rendering Ads
Next
Callback Information
Last modified: 2026-07-08Powered by