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 initializedstartAutoRequestAd
shall be called before video content is played, otherwise ad breaks in the beginning of the video, pre-roll ad especially, will be wastedPlease called
startAutoRequestAd
only one time.
mInStreamAd.startAutoRequestAD();
Implement CEContentProgressProvider to update Video Content Status
isContentPlayerReady
,getContentCurrentPosition
andgetContentTotalDuration
must be implemented otherwise InStream ad will not be servedPlease 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
Put the AdProperty to
HIDE_NON_SKIPPLE_BUTTON
or the customized skip button will overlap with default one.Please pass any views that overlap ad view by
registerFriendlyObstruction
for the completeness of viewability tracking.Customized view must be passed by
registerFriendlyObstruction
if it is on top of and overlap InStream ad.[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.
Last updated