CEInStreamAD

Characteristics

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

  • Pre-roll ads

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

  • Post-roll ads

    Post-roll ads are displayed after the content video finished playing. Ads are played once the content video finished playing.

  • Mid-roll ads

    Mid-roll ads are served in the middle of content video at each cue points. Multiple mid-roll ads can be arranged in single video.

    • Cue points at which to show ads are defined in 3 different policies, Every N Seconds, Fixed Time or Fixed Percentage.

    • Ad break at each cue point manages duration and number of video ad to be played in 3 different rules, Single, Fixed time or Multi Ad.

Integration

Add Files for InStream Ad Integration

Add CEInStreamAD.h to app's build target.

Declare InStream Ad

• Import CEInStreamAD.h

• Set up CEInStreamADDelegate and CEContentProgressProvider protocol in view controller's extension.

• Create a CEInStreamAD instance and keep its reference.

// MyViewController.m

#import "CEInStreamAD.h"
@interface MyViewController() <CEInStreamADDelegate, CEContentProgressProvider>

@property (nonatomic, strong) CEInStreamAD *inStreamAD;
@end

Initialize InStream Ad

• Initialize CEInStreamAD instance and necessary properties.

- (void)viewDidLoad {  
    // [NOTE]
    // It is recommended to initialize as early as possible.
    //
    CERequestInfo *info = [CERequestInfo new];
    info.placement = @“PUT_YOUR_PLACEMENT_ID_HERE”; 
    self.inStreamAD = [[CEInStreamAD alloc] initWithRequestInfo:info
                                                    adContainer:self.videoView
                                             videoViewProfile:CEVideoViewProfileInStreamDefaultProfile];
    // [NOTE]
    // To set up CERequestInfo for InStream AD, the only property required
    // is "placement". Setting up "place", "timeout", "localExtra",
    // "adWidth" are unnecessary.
    //
    // ***DEPRECATED*** //
    // self.inStreamAD = [[CEInStreamAD alloc] initWithPlacement:@"PUT_YOUR_PLACEMENT_ID_HERE"
    //                                              adContainer:self.videoView
    //                                         videoViewProfile:CEVideoViewProfileInStreamDefaultProfile];
    // **************** //
    self.inStreamAD.delegate = self;
    self.inStreamAD.progressProvider = self;
}

Request InStream Ad

• startAutoRequestAD must be called after CEInStreamAD 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 call startAutoRequestAD for only one time for each CEInStreamAd instance.

  **

- (void)viewDidAppear:(BOOL)animated{

    [self.inStreamAD startAutoRequestAD];
}

Implement CEInStreamADDelegate to handle InStream Ad Event

- (void)inStreamADDidFail:(CEInStreamAD *)inStreamAD 
                withError:(NSError *)error{
    // [NOTE]
    // Callback if fail to load an InStream ad from Intowow SDK
    //
}

-(void)inStreamADRequestContentPause:(CEInStreamAD *)inStreamAD 
                         adBreakType:(CEADBreakType)adBreakType 
                            cuePoint:(CEMilliSec)cuePoint{
    // [NOTE]
    // After inStreamADRequestContentPause, ad is ready
    // and can be played after video player is paused.
    //
    // [Pre-roll]
    // Pre-roll ad might be prepared later than video content start playing.
    // In this case, SDK will still callback to this function with
    // cuePoint equal to 0. Please mind this scenario and do not
    // start InStream ad if you only wish pre-roll ad to be played before
    // video content start playing.
    //
    [self.yourVideoPlayer pause];
    [self.inStreamAD play];
}

- (void)inStreamADRequestContentResume:(CEInStreamAD *)
                              duration:(CEMilliSec)totalDuration
               inStreamAD adRemainTime:(CEMilliSec)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]
    // inStreamADRequestContentResume is best for resume playing video
    // content if InStream ad finished playing.
    //
    [self.inStreamAD stop];
    [self.yourVideoPlayer play];
}

- (void)inStreamProgress:(CEInStreamAD *)inStreamAD 
                duration:(CEMilliSec)totalDuration
                position:(CEMilliSec)currentPosition{
    // [NOTE]
    // inStreamProgress is best for monitoring
    // e.g.
    // [self.inStreamAD getCurrentADNum];
    // [self.inStreamAD getTotalADNum];
    // [self.inStreamAD getADRemainTime];
    // [self.inStreamAD getADBreakRemainTime];
    //
}

- (void) inStreamADDidVideoStart:(nonnull CEInStreamAD *)inStreamAD{
}

- (void) inStreamADDidVideoEnd:(nonnull CEInStreamAD *)inStreamAD{
}

- (void) instreamADDidClick:(nonnull CEInStreamAD *)inStreamAD{
}

- (void) instreamADDidMute:(nonnull CEInStreamAD *)inStreamAD{
}

- (void) instreamADDidUnmute:(nonnull CEInStreamAD *)inStreamAD{
}

- (void) inStreamADWillTrackImpression:(nonnull CEInStreamAD *)inStreamAD{
}

- (void) inStreamADCuePointReady:(nonnull CEInStreamAD *)inStreamAD{
    // [NOTE]
    // getCuePoints shall be called after inStreamADCuePointReady
    // e.g.
    // [inStreamAD getCuePoints];
    //
}

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.

  

- (NSTimeInterval) getContentTotalDuration
{
    CMTime totalDuration = self.yourVideoPlayer.currentItem.asset.duration;
    return (NSTimeInterval)CMTimeGetSeconds(totalDuration);
}

- (NSTimeInterval) getContentCurrentPosition
{
    CMTime currentTime = self.yourVideoPlayer.currentItem.currentTime;
    if (!self.isPlayerSeeking) {
        self.lastCurrentPosition = currentTime;
    }

    return (NSTimeInterval)CMTimeGetSeconds(self.lastCurrentPosition);
}

- (BOOL) isContentPlayerReady
{
    return (self.yourVideoPlayer.status == PlayerStatusReadyToPlay);
}

Release InStream Ad

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

- (void)viewWillDisappear:(BOOL)animated
{
    if ([self.navigationController.viewControllers indexOfObject:self] == NSNotFound) {
        [self.inStreamAD destroy];
        self.yourVideoPlayer = nil;
    }
}

Advance Integration

• CEVideoViewProfileInStreamDefaultProfile can be configured base on your need on InStream ad:

CEVideoViewProfile videoViewProfile = 
    CEVideoViewProfileSpeaker |
    CEVideoViewProfileCountDown |
    CEVideoViewProfileSilentStart |
    CEVideoViewProfileAdIcon |
    CEVideoViewProfileSkipButton |
    CEVideoViewProfileAdCount;

self.inStreamAD = [[CEInStreamAD alloc] initWithPlacement:@"PUT_YOUR_PLACEMENT_ID_HERE"
                                              adContainer:self.videoView
                                         videoViewProfile:videoViewProfile];

• 7 properties in total for InStream ad. Properties in CEVideoViewProfile represent different elements on InStream ad UI. (Please refer to diagram above)

  • CEVideoViewProfileInStreamDefaultProfile: All elements included and volume on when InStream ad start playing

  • CEVideoViewProfileSilentStart: Volume off when InStream ad start playing

    (A) CEVideoViewProfileSpeaker: Top left speaker

    (B) CEVideoViewProfileAdCount: Bottom left AdCount

    (C) CEVideoViewProfileAdIcon: Top right ad icon

    (D) CEVideoViewProfileCountDown: Top right count down timer

    (E) CEVideoViewProfileSkipButton: Bottom right skip button

• Customized Skip Button 1. Please exclude CEVideoViewProfileSkipButton from CEVideoViewProfile instance otherwise customized view will be overlapped by default Skip view. 2. Pass the customized view throughregisterViewForDismiss to enable Skip function of customized view. Please call registerViewForDismiss before startAutoRequestAD in case Skip function did not work on InStream ad. 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
CEVideoViewProfile videoViewProfile = 
    (CEVideoViewProfileInStreamDefaultProfile &= ~CEVideoViewProfileSkipButton);

self.inStreamAD = [[CEInStreamAD alloc] initWithPlacement:@"PUT_YOUR_PLACEMENT_ID_HERE"
                                              adContainer:self.videoView
                                         videoViewProfile:videoViewProfile];
[self.inStreamAD registerViewForDismiss:yourCustomizedView];

• Please pass any views that overlap ad view by registerFriendlyObstruction for the completeness of viewability tracking

API Reference

Public constructors
initWithRequestInfo:(nonnull CERequestInfo )requestInfo adContainer:(nonnull UIView)adContainer videoViewProfile:(CEVideoViewProfile)videoViewProfile Instantiates a new InStream ad.
initWithPlacement:(NSString )placement adContainer:(UIView)adContainer videoViewProfile:(CEVideoViewProfile)videoViewProfile (Deprecated) Instantiates a new InStream ad.

Public methods
void	registerViewForDismiss:(nonnull UIView *)view Register view as Skip button.
void	registerFriendlyObstruction:(nonnull NSArray*)views Please pass any views that overlap ad view so that viewability tracking can be completed.
void	startAutoRequestAD Request in-stream ads automatically. It shall only be called after CEInStreamAd is intialized. Please call startAutoRequestAD for only one time for each CEInStreamAd instance.
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.
nullable NSArray <NSNumber*> *	getCuePoints Return an array of cue points in NSNumber representing milli-second. Return nil 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 kCECurrentADNumInvalid.
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, kCEToTalADNumInvalid will be returned.
CEMilliSec	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, getADBreakRemainTime will be returned.
CEMilliSec	getADRemainTime Return the time left for current playing InStream ad. It should be called during ad break, otherwise it will return kCEADRemainTimeInvalid.

Public Properties
NSDictionary	customEventExtra Extra info that is passed in third-party custom event when InStream Ad is loaded. It is a nullable value, null is expected to receive if no key-value is set.

Public Constructors

initWithRequestInfo

initWithRequestInfo:(nonnull CERequestInfo *)requestInfo 
        adContainer:(nonnull UIView*)adContainer
    videoViewProfile:(CEVideoViewProfile)videoViewProfile

Instantiates a new InStream ad.

Parameters
info	Request information
adContainer	UIView that ad will be played on
videoViewProfile	CEVideoViewProfile to define elements to be shown on Video ad. CEVideoViewProfileInStreamDefaultProfile will include all supporting elements with auto volume control. (Supporting MACRO: CEVideoViewProfileSpeaker, CEVideoViewProfileCountDown, CEVideoViewProfileSilentStart, CEVideoViewProfileAdIcon, CEVideoViewProfileSkipButton, CEVideoViewProfileAdCount)

(Deprecated)initWithPlacement

initWithPlacement:(NSString *)placement
      adContainer:(UIView*)adContainer
 videoViewProfile:(CEVideoViewProfile)videoViewProfile

Instantiates a new InStream ad.

Parameters
placement	A specific group of ad units denoted in NSString, on which an advertiser can choose to place their ads using placement targeting
adContainer	UIView that ad will be played on
videoViewProfile	CEVideoViewProfile to define elements to be shown on Video ad. CEVideoViewProfileInStreamDefaultProfile will include all supporting elements with auto volume control. (Supporting MACRO: CEVideoViewProfileSpeaker, CEVideoViewProfileCountDown, CEVideoViewProfileSilentStart, CEVideoViewProfileAdIcon, CEVideoViewProfileSkipButton, CEVideoViewProfileAdCount)

Public Methods

registerViewForDismiss

- (void) registerViewForDismiss:(nonnull UIView *)view

Register view as Skip button.

Parameters
view	UIView to be registered for skip event.

registerFriendlyObstruction

- (void) registerFriendlyObstruction:(nonnull NSArray<UIView *>*)views

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

Parameters
views	UIView NSArray storing all views overlapping InStream ad

startAutoRequestAD

- (void) startAutoRequestAD

Request in-stream ads automatically. It shall only be called after CEInStreamAd is intialized. Please call startAutoRequestAD for only one time for each CEInStreamAd instance.

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

- (nullable NSArray<NSNumber *>*) getCuePoints

Return an array of cue points in NSNumber representing milli-second. Return nil if total duration of content video is not available.

Returns
NSArray<NSNumber *>*	NSNumber array with all cue points in NSNumber 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 kCECurrentADNumInvalid.

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, kCEToTalADNumInvalid will be returned.

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

getADBreakRemainTime

- (CEMilliSec) 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, getADBreakRemainTime will be returned.

Returns
CEMilliSec	The time left for current ad break

getADRemainTime

- (CEMilliSec) getADRemainTime

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

Returns
CEMilliSec	The time left for current playing InStream ad

Public Properties

customEventExtra

@property (nonatomic, strong, readonly, nullable) NSDictionary * customEventExtra;

Extra info that is passed in third-party custom event when InStream Ad is loaded.