InStream Ad

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 and CEInStreamAD.m 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.
    //
    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 *)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) 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;
    }
}

Please refer to CEInstreamAd, CEInstreamAdDelegate and CEContentProgressProvider for more information in detail.