instream video ads

Instream video ads implementation

Adform Advertising SDK can also be used to show in-stream video ads. There are two ways of playing instream video ads with our SDK:

1. Use SDK player to show content video and ads;
2. Use external (standard iOS or third party), video player, to show content video and use the SDK player only to show ads;

1. Using SDK player

To implement instream video ads using only SDK player you have to follow these steps:

1. You must create an AFVideoPlayerController and pass the content URL to it. This player will be used to play content video and ads.

Swift

let contentUrl = URL(string: "http://www.url.to.your.video.content")
videoPlayer = AFVideoPlayerController(url: contentUrl)
videoPlayer.view.frame = CGRect(x: 0, y: 20, width: 320, height: 200)
view.addSubview(videoPlayer.view)

Objective-C

NSURL *contentVideoURL = [NSURL URLWithString:@"http://www.url.to.your.video.content"];
self.videoPlayer = [[AFVideoPlayerController alloc] initWithURL:contentVideoURL];
self.videoPlayer.view.frame = CGRectMake(0, 20, 320, 200);
[self.view addSubview:self.videoPlayer.view];

2. Set master tags provided by Adform. You may set up up to three master tags one for each ad type: pre-roll, mid-roll and post-roll. Pre-roll ads are showed before content video, mid-roll ads are displayed during content playback and post-roll ads are shown after the content video.

Swift

videoPlayer.preRollMId = masterTag
videoPlayer.midRollMId = masterTag
videoPlayer.postRollMId = masterTag

Objective-C

self.videoPlayer.preRollMId = kPreRollMasterTagId;
self.videoPlayer.midRollMId = kMidRollMasterTagId;
self.videoPlayer.postRollMId = kPostRollMasterTagId;

3. Start the playback.

Swift

videoPlayer.play()

Objective-C

[self.videoPlayer play];

2. Using an external video player

If you wish to use one of the standard iOS, a third-party, or even your own video player you can do so. To use instream video ads with an external video player you need to:

1. FIrst of all create a video player of your choice. We are going to use AVPlayerViewController for the example.

Swift

let contentUrl = URL(string: "http://www.url.to.your.video.content")!
contentViewController = AVPlayerViewController()
contentViewController.player = AVPlayer(url: contentUrl)

Objective-C

NSURL *contentVideoURL = [NSURL URLWithString:@"http://www.url.to.your.video.content"];
self.contentVideoPlayer = [AVPlayerViewController new];
self.contentVideoPlayer.player = [[AVPlayer alloc] initWithURL:contentVideoURL];

2. Then you need to create an instance of the adapter that will be used to connect the external player with the SDK player. This adapter is a simple class that implements AFContentPlayback protocol. Adform Advertising SDK already contains the adapters for standard iOS video players (AVPlayerViewController and MPMoviePlayerController), so if you are using these players you just need to create an instance of AFMPMoviePlayerContentPlayback or AFAVPlayerViewControllerPlayback. In the example, we are going to use AFAVPlayerViewControllerPlayback. If you are using a third-party video player you will need to implement this adapter yourself, instructions on how to do it can be found here.

Swift

let playback = AFAVPlayerViewControllerPlayback(player: contentViewController)

Objective-C

AFAVPlayerViewControllerPlayback *playback = [[AFAVPlayerViewControllerPlayback alloc] initWithMoviePlayer:self.contentVideoPlayer];

3. Now it is time to create the AFVideoPlayerController that will be used to display ads on top of an external video player.

Swift

adsVideoPlayer = AFVideoPlayerController(container: contentViewController.view, andContentPlayback: playback)

Objective-C

self.adsVideoPlayer = [[AFVideoPlayerController alloc] initWithContainer:self.contentVideoPlayer.view andContentPlayback:playback];

4. We also need to set master tag ids for ads.

Swift

adsVideoPlayer.preRollMId = masterTag
adsVideoPlayer.midRollMId = masterTag
adsVideoPlayer.postRollMId = masterTag

Objective-C

self.adsVideoPlayer.preRollMId = kPreRollMasterTagId;
self.adsVideoPlayer.midRollMId = kMidRollMasterTagId;
self.adsVideoPlayer.postRollMId = kPostRollMasterTagId;

5. Present AVPlayerViewController and play its content. That's it.

Swift

present(contentViewController, animated: true, completion: nil)

Objective-C

[self presentViewController:self.contentVideoPlayer animated:true completion:nil];

How to create an adapter for a third-party video player?

To play video ads AFVideoPlayerController needs to access the third-party video player. To do so AFContentPlayback protocol is used used. This protocol describes the interaction between AFVideoPlayerController and your video player. To create a custom content playback class you need to:

1. Provide these properties:

• duration - the duration of content video;
• currentTime - current time of the video playback, this property must be KVO.
• mute - identifies if the content video player is muted. If your video player cannot be muted, just return false from this property.
• fullscreen - identify if the video player is playing content in fullscreen mode.

2. Implement these methods:

• setFullscreen:animated: - enables or disables full-screen mode of the content video player.
• play - starts or resumes content video playback.
• pause - pauses content video playback.

3. Also, the content playback object must post notifications when content playback starts and finishes. You need to use these notification names kAFContentPlaybackStartedNotificaiton, kAFContentPlaybackFinishedNotificaiton.

Ad types

Adform Advertising SDK can show 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. To use this type of ads you need to set pre-roll master tag id on AFVideoPlayerController. These ads are played only once when the user starts the playback of the content video if the user replays the video the ad will not be shown again.

Swift

adsVideoPlayer.preRollMId = masterTag

Objective-C

self.adsVideoPlayer.preRollMId = kPreRollMasterTagId;

Post-roll ads

Post-roll ads are displayed after the content video has finished playing. To use this type of ads you need to set post-roll master tag id on AFVideoPlayerController. These ads are played only once when the content video has finished playing, if the user replays the video the ad will not be shown again.

Swift

adsVideoPlayer.postRollMId = masterTag

Objective-C

self.adsVideoPlayer.postRollMId = kPostRollMasterTagId;

Mid-roll ads

Mid-roll ads are shown in the middle of content videos at breakpoints. To use this type of ads you need to set mid-roll master tag id on AFVideoPlayerController. Mid-roll ads may be shown multiple times during a single video.

Swift

adsVideoPlayer.midRollMId = masterTag

Objective-C

self.adsVideoPlayer.midRollMId = kMidRollMasterTagId;

Breakpoints at which to show ads may be defined in several ways in Adform UI. You can display ads at fixed times and time intervals, at time in percentage relative to content duration or at cue points. Cue points must be defined not only on the UI side but on the SDK player too. Each cue point must have a time offset when an ad should be shown and an identifier. The identifier is used to connect cue points defined in Adform UI to cue points set to the video player. Example bellow shows you how to set cue points to AFVideoPlayerController:

Swift

let cuePoint = AFCuePoint(time: 30, identifier: 1)
adsVideoPlayer.registerCuePoints([cuePoint])

Objective-C

AFCuePoint *cuePoint = [[AFCuePoint alloc] initWithTime:30 identifier:1];
[self.adsVideoPlayer registerCuePoints:@[cuePoint]];