Instream Video Ads - adform/adform-ios-sdk GitHub Wiki
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:
- Use SDK player to show content video and ads;
- Use external (standard iOS or third party), video player, to show content video and use the SDK player only to show ads;
To implement instream video ads using only SDK player you have to follow these steps:
- 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];
- 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;
- Start the playback.
Swift
videoPlayer.play()
Objective-C
[self.videoPlayer play];
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:
- 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];
- 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];
- 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];
- 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;
- 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];
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:
- 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.
- 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.
- Also, the content playback object must post notifications when content playback starts and finishes. You need to use these notification names kAFContentPlaybackStartedNotificaiton, kAFContentPlaybackFinishedNotificaiton.
Adform Advertising SDK can show three types of in-stream video ads: pre-roll, mid-roll and post-roll.
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 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 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]];