InStreamAd

package com.intowow.sdk

public class InStreamAd

Characteristics

• There are three types of in-stream video ads: pre-roll, mid-roll and post-roll.

  • Pre-roll ads

    Pre-roll ads are displayed before the content video. These ads are played only once when user starts the playback of content video.

  • Post-roll ads

    Post-roll ads are displayed after the content video has finished playing. These ads are played only once when the content video has finished playing.

  • Mid-roll ads

    Mid-roll ads are shown in the middle of content video at breakpoints. Mid-roll ads may be shown multiple times during single video. Mid-roll ad can be served depends on cue points.

    • Cue points at which to show ads may be defined in several ways in Mid-roll ads. You can display ads by Every n seconds, Fixed time or Fixed percentage.

    • Ad break at each cue point can choose the following rule to play video ad in the Ad break, Single, Fixed time or Multi Ad.

Integration

Declare InStreamAd

• Create a InStreamAd instance and keep its reference.

import com.intowow.sdk.InStreamAd;

private final static String PLACEMENT = "Obtain from your Intowow account manager";
private InStreamAd mInStreamAd = null;

Initialize InStreamAd

// [NOTE]
// It is recommended to initialize as early as possible.
// You can send more information to custom event if necessary through requestInfo. (optional)

Map<String, Object> adProps = new HashMap<>();
adProps.put(AdProperty.HIDE_COUNTDOWN, false);
adProps.put(AdProperty.HIDE_SPEAKER, false);
adProps.put(AdProperty.HIDE_AD_ICON, false);
adProps.put(AdProperty.SILENT_START, false);
adProps.put(AdProperty.HIDE_NON_SKIPPABLE_BUTTON, false);
adProps.put(AdProperty.HIDE_AD_COUNT_VIEW, false);

final RequestInfo requestInfo = new RequestInfo();
JSONObject localExtra = new JSONObject();
try {
    localExtra.put("more_info", "Your extra information");
} catch (JSONException e) {
    e.printStackTrace();
}
requestInfo.setLocalExtra(localExtra);

mInStreamAd = new InStreamAd(this, PLACEMENT, adProps, mContainer, requestInfo);
// ***DEPRECATED*** //
// mInStreamAd = new InStreamAd(this, PLACEMENT, adProps, mContainer);
// **************** //

Implement InStreamAdListener to handle InStreamAd Event

mInStreamAd.setAdListener(new InStreamAd.InStreamAdListener() {

    @Override
    public void onAdError(InStreamAd ad, AdError error) {
        // [NOTE]
        // Callback if fail to load an InStream ad from Intowow SDK
        //
    }

    @Override
    public void onVideoStart(InStreamAd ad) {
    }

    @Override
    public void onVideoEnd(InStreamAd ad) {
    }

    @Override
    public void onAdClicked(InStreamAd ad) {
    }

    @Override
    public void onAdMute(InStreamAd ad) {
    }

    @Override
    public void onAdUnmute(InStreamAd ad) {
    }

    @Override
    public void onAdImpression(InStreamAd ad) {
    }

    @Override
    public void onProgress(InStreamAd ad, long totalDuration, long currentPosition) {
        // [NOTE]
        // onProgress is best for monitoring
        // e.g.
        //ad.getAdBreakRemainTime();
        //ad.getAdRemainTime();
        //ad.getCurrentAdNum();
        //ad.getTotalAdNum();
        //
    }

    @Override
    public void onRequestContentPause(InStreamAd ad, int adBreakType,
                                                  long cuePointTime) {
        // [NOTE]
        // After onRequestContentPause, ad is ready
        // and can be played after video player is paused.
        // 
        // [Pre-roll]
        // When the ad arrives late, please aware that Preroll ad
        // will callback here after the content has started.
        // You need to handle this situation when cuePointTime = 0.
        //
        if(yourMediaPlayer != null && yourMediaPlayer.isPlaying()) {
            yourMediaPlayer.pause();
        }
        if (mInStreamAd != null) {
            mInStreamAd.play();
        }
    }

    @Override
    public void onRequestContentResume(InStreamAd ad, long adRemainTime) {
        // [NOTE]
        // Two scenario to trigger inStreamADRequestContentResume: 
        // (1) Video ad is finished (adRemainTime = 0)
        //    --> Please stop inStreamAD and resume Video Player
        // (2) Time requirement of ad break has been met (adRemainTime > 0)
        //    --> Resume Video Player or keep playing ad is up to you. 
        //        If you chose to complete playing video ad, inStreamADRequestContentResume
        //        will be called again once ad is finished(scenario (1)).
        //
        //
        // [Best Practice]
        // onRequestContentResume is best for resume playing video
        // content if InStream ad finished playing.
        //
        if (mInStreamAd != null && adRemainTime == 0) {
            mInStreamAd.stop();
        }
        yourMediaPlayer.start();
    }

    @Override
    public void onCuePointsReady(InStreamAd ad) {
        // [NOTE]
        // getCuePoint shall be called after onCuePointsReady
        // e.g.
        // ad.getCuePoints();
        //
    }
);

Request InStreamAd

• startAutoRequestAd must be called after InStreamAd instance is initialized

• startAutoRequestAd shall be called before video content is played, otherwise ad breaks in the beginning of the video, pre-roll ad especially, will be wasted

• Please called startAutoRequestAd only one time.

mInStreamAd.startAutoRequestAD();

Implement CEContentProgressProvider to update Video Content Status

• isContentPlayerReady, getContentCurrentPosition and getContentTotalDuration must be implemented otherwise InStream ad will not be served

• Please read this carefully: During the time user is seeking the video, APP should always return the progress time that user start seeking instead of the current time that user has sought to. Once user stop seeking, please return the progress time that user stopped at.

  

mInStreamAd.setContentProgressProvider(new InStreamAd.CEContentProgressProvider() {

    @Override
    public long getContentCurrentPosition() {
        if (yourMediaPlayer == null) {
            return 0;
        } else if (isSeeking) {
            return mLastPosition;
        }
        return yourMediaPlayer.getCurrentPosition();
    }

    @Override
    public long getContentTotalDuration() {
        if (yourMediaPlayer == null) {
            return 0;
        }

        return yourMediaPlayer.getDuration();
    }

    @Override
    public boolean isContentPlayerReady() {
        return yourMediaPlayerReady;
    }
});

Release InStreamAd

• InStream ad shall at least be released along with the life cycle of video content

@Override
protected void onDestroy() {
    if (mInStreamAd != null) {
        mInStreamAd.destroy();
        mInStreamAd = null;
    }

    if (yourMediaPlayer != null) {
        yourMediaPlayer.release();
        yourMediaPlayer = null;
    }
    super.onDestroy();
}

Advance Integration

Note

• You could use setAdSize(CEAdSize adSize) to instruct SDK to set an expected width and height of the ad, and SDK will rescale the ad automatically and keeps the aspect ratio.
• If you want to resize the ad, please use resize(CEAdSize adSize).

AdProperty

• You could use AdProperty to configure your ad if necessary:

Map<String, Object> adProps = new HashMap<String, Object>();
adProps.put(AdProperty.HIDE_COUNTDOWN, trueOrFalse);
adProps.put(AdProperty.HIDE_SPEAKER, trueOrFalse);
adProps.put(AdProperty.HIDE_AD_ICON, trueOrFalse);
adProps.put(AdProperty.SILENT_START, trueOrFalse);
adProps.put(AdProperty.HIDE_NON_SKIPPABLE_BUTTON, trueOrFalse);
adProps.put(AdProperty.HIDE_AD_COUNT_VIEW, trueOrFalse);

InstreamAd mInStreamAd = new InstreamAd(context, placement, adProps, container);

(A)AdProperty.HIDE_SPEAKER: if need to hide the speaker on top left corner, the default value is false.

(B) AdProperty.HIDE_AD_COUNT_VIEW: if need to hide the ad count view on bottom left corner, the default value is false.

(C) AdProperty.HIDE_AD_ICON: if need to hide the ad icon on top right corner, the default value is false.

(D) AdProperty.HIDE_COUNTDOWN: if need to hide the count down timer on top right corner, the default value is false.

(E) AdProperty.HIDE_NON_SKIPPABLE_BUTTON: if need to hide skippable button on bottom right corner, the default value is false.

(F) AdProperty.SILENT_START: auto silent play, the default value is true.

Customized Skip Button

1. Put the AdProperty to HIDE_NON_SKIPPLE_BUTTON or the customized skip button will overlap with default one.

2. Please pass any views that overlap ad view by registerFriendlyObstruction for the completeness of viewability tracking.
3. Customized view must be passed by registerFriendlyObstruction if it is on top of and overlap InStream ad.

4. [Recommended] Mechanism to show and hide customized Skip button need to be handled by APP. Default Skip button from Intowow SDk needs no effort from APP and is recommended.

// Sample for Setting up Customized Skip button
mCustomNonSkipableButton = new CustomNonSkipableButton(InStreamAdActivity.this);

// [Notice] remember to register custom non-skippable button.
mInStreamAd.registerViewForDismiss(mCustomNonSkipableButton);
List<View> obstructionViews = new ArrayList<View>();
obstructionViews.add(mCustomNonSkipableButton);

// [Notice] remember to register custom non-skippable button to obstruction.
mInStreamAd.registerFriendlyObstruction(obstructionViews);

API Reference

Public constructors
InStreamAd(Context context, String placement, Map adProps, ViewGroup adContainer, RequestInfo requestInfo) Instantiates a new InStream ad.
InStreamAd(Context context, String placement, Map adProps, ViewGroup adContainer) (Deprecated)Instantiates a new InStream ad.

Public methods
void	registerViewForDismiss(View view) Register view as Skip button.
void	registerFriendlyObstruction(List views) Please pass any views that overlap ad view so that viewability tracking can be completed.
void	setAdListener(final InStreamAdListener listener) Set ad listener to InStream ad.
void	setContentProgressProvider(CEContentProgressProvider contentProgressProvider) Set contentProgressProvider to InStream ad.
void	setAdSize(CEAdSize adSize) Set adSize to InStream ad.
void	startAutoRequestAd() Request in-stream ads automatically. It shall only be called once after InStreamAd is intialized.
void	contentComplete() Notification of the end of video content. It is critical to ensure Post-roll ad being served. If it is called in the middle of video content and there is ad to be served, post-roll ad will be served.
void	play() Play InStream ad.
void	stop() Stop InStream ad. Once certain InStream video ad is stopped, it cannot resumes playing.
void	destroy() Release InStream ad. InStream Ad shall at least be released along with video player.
List< Long >	getCuePoints() Return a list of cue points in Long representing milli-second. Return null if total duration of content video is not available.
int	getCurrentAdNum() Return the index(Start from 1) of InStream ad that is playing out of the number of ad should be served in current ad break. It should be called during ad break, otherwise it will return CE_CURRENT_AD_NUM_INVALID.
int	getTotalAdNum() Return the total number of InStream that is expected to be played within current ad break. If it is not called in ad break or it is called in ad break but the total number of ad is not predictable, CE_TOTAL_AD_NUM_INVALID will be returned.
long	getAdBreakRemainTime() Return the time left for current ad break. If it is not called in ad break or it is called in ad break but the remaining time of ad break cannot be calculated, CE_AD_BREAK_REMAIN_TIME_INVALID will be returned.
long	getAdRemainTime() Return the time left for current playing InStream ad. It should be called during ad break, otherwise it will return CE_AD_REMAIN_TIME_INVALID.
JSONObject	getExtra() Return the extra info that is set in custom event. Receiving null is expected if no object is set.

Public Constructors

InStreamAd

InStreamAd(Context context, String placement, Map<String, Object> adProps, ViewGroup adContainer, RequestInfo requestInfo)

Instantiates a new InStream ad.

Parameters
context	Context
placement	String: A specific group of ad units on which an advertiser can choose to place their ads using placement targeting
adProps	Map: the ad property
adContainer	ViewGroup: ViewGroup that Ad belongs to
RequestInfo	RequestInfo: Extra info for requesting AD. If no additional info is needed, APP can pass either null or the requestInfo instance.

InStreamAd(Deprecated)

InStreamAd(Context context, String placement, Map<String, Object> adProps, ViewGroup adContainer)

Instantiates a new InStream ad.

Parameters
context	Context
placement	String: A specific group of ad units on which an advertiser can choose to place their ads using placement targeting
adProps	Map: the ad property
adContainer	ViewGroup: ViewGroup that Ad belongs to

Public Methods

registerViewForDismiss

void registerViewForDismiss(View view)

Register view as Skip button.

Parameters
view	View: The View to be registered for skip event.

registerFriendlyObstruction

void registerFriendlyObstruction(List<View> views)

Please pass any views that overlap ad view so that viewability tracking can be completed.

Parameters
views	List: List of View storing all views overlapping InStream ad

setAdListener

void setAdListener(final InStreamAdListener listener)

Set ad listener to InStream ad.

Parameters
listener	InStreamAdListener

setContentProgressProvider

void setContentProgressProvider(CEContentProgressProvider contentProgressProvider)

Set contentProgressProvider to InStream ad.

Parameters
contentProgressProvider	CEContentProgressProvider

setAdSize

void setAdSize(CEAdSize adSize)

Set adsize to InStream ad.

Parameters
adSize	CEAdSize

startAutoRequestAd

void startAutoRequestAd()

Request in-stream ads automatically. It shall only be called once after InStreamAd is intialized.

contentComplete

void contentComplete()

Notification of the end of video content. It is critical to ensure Post-roll ad being served. If it is called in the middle of video content and there is ad to be served, post-roll ad will be served.

play

void play()

Play InStream ad.

stop

void stop()

Stop InStream ad. Once certain InStream video ad is stopped, it cannot resume playing.

destroy

void destroy()

Release InStream ad. InStream Ad shall at least be released along with the life cycle of video content.

getCuePoints

List<Long> getCuePoints()

Return a list of cue points in Long representing milli-second. Return null if total duration of content video is not available.

Returns
List< Long >	List with all cue points in Long representing milli-second

getCurrentADNum

int getCurrentADNum()

Return the index(Start from 1) of InStream ad that is playing out of the number of ad should be served in current ad break. It should be called during ad break, otherwise it will return CE_CURRENT_AD_NUM_INVALID.

Returns
int	The index of InStream ad that is playing in current ad break

getTotalAdNum

int getTotalAdNum()

Return the total number of InStream ad that is expected to be played within current ad break. If it is not called in ad break or it is called in ad break but the total number of ad is not predictable, CE_TOTAL_AD_NUM_INVALID will be returned.

Returns
int	Total number of InStream ad that is expected to be played in current ad break

getAdBreakRemainTime

long getAdBreakRemainTime()

Return the time left for current ad break. If it is not called in ad break or it is called in ad break but the remaining time of ad break cannot be calculated, CE_AD_BREAK_REMAIN_TIME_INVALID will be returned.

Returns
long	The time left for current ad break

getAdRemainTime

long getAdRemainTime()

Return the time left for current playing InStream ad. It should be called during ad break, otherwise it will return CE_AD_REMAIN_TIME_INVALID.

Returns
long	The time left for current playing InStream ad

getExtra

JSONObject getExtra()

Return the extra info that is set in custom event. Receiving null is expected if no object is set.

Returns
JSONObject	The extra info that is set in custom event.