iOS SDK: In-stream video

Help
/
Partners
/
iOS SDK: In-stream video

Initialization
Using the application player
Protocol MTRGInstreamAdPlayer
Protocol MTRGInstreamAdPlayerDelegate
Using the SDK player
Download ads

Display ads
Available ad video properties
Click processing
Condition management
User data
Samples

myTarget SDK provides the ability to show in-stream video ads in your app while watching videos. Ads can be shown before a video (preroll), during a show (midroll), and after a show (postroll).

The SDK downloads the data and gives the app the ability to display ads both in its video player and in the app's player.

Initialization

To display an ad video in your app, you must create an instance of the MTRGInstreamAd class. To create an instance of MTRGInstreamAd, you must specify your slotId. For each video in the application, you need to create your own instance of the MTRGInstreamAd class.

@interface YourViewController : UIViewController
@end
 
@implementation YourViewController
{
  MTRGInstreamAd *_ad;
}
 
- (void)initAd
{
    // Enable debug mode
    // [MTRGInstreamAd setDebugMode:YES];
    // Create an instance of MTRGInstreamAd
    _ad = [MTRGInstreamAd instreamAdWithSlotId:YOUR_SLOT_ID];
}

Using the application player

To play ads in the application player, it must implement the MTRGInstreamAdPlayer Protocol and notify the MTRGInstreamAdPlayerDelegate delegate installed by it.

To use your player you need to install it to the created player instance MTRGInstreamAd.

@interface YourViewController : UIViewController
@end
 
@implementation YourViewController
{
  MTRGInstreamAd *_ad;
}
 
- (void)initAd
{
    // Create an instance of MTRGInstreamAd
    _ad = [MTRGInstreamAd instreamAdWithSlotId:YOUR_SLOT_ID];
     
    // Install the player
    _ad.player = YOUR_PLAYER;
}

Protocol MTRGInstreamAdPlayer

The MTRGInstreamAdPlayer Protocol methods are called by the MTRGInstreamAd instance. You do not need to call them yourself.

@property(nonatomic, readonly) NSTimeInterval adVideoDuration;

The duration of the promotional video.

@property(nonatomic, readonly) NSTimeInterval adVideoTimeElapsed;

The current position of the promotional video. The method is called multiple times during ad video playback and should return the actual value in seconds.

@property(nonatomic, weak) id <MTRGInstreamAdPlayerDelegate> adPlayerDelegate;

Sets the delegate of the player.

@property(nonatomic, readonly) UIView *adPlayerView;

Visual representation of the player, usually self.

@property(nonatomic) float volume;

Sets the volume from 0 to 1.

- (void)playAdVideoWithUrl:(NSURL *)url;

Starts playback of the promotional video.

url - path to the video

- (void)pauseAdVideo;

Pauses the playback of the advertising video.

- (void)resumeAdVideo;

Resumes playing the promotional video.

- (void)stopAdVideo;

Stops the playback of the advertising video.

Protocol MTRGInstreamAdPlayerDelegate

The MTRGInstreamAdPlayerDelegate Protocol callback methods for the installed delegate must be called by the player in response to calls to the MTRGInstreamAdPlayer Protocol methods when certain events occur.

- (void)onAdVideoStart;

Method should be invoked after a successful start of playback of the advertising video as a response to the call playAdVideo.

- (void)onAdVideoPause;

The method should be called after pausing ad video playback as a response to the pauseAdVideo method call.

- (void)onAdVideoResume;

Method should be invoked after the resumption of the playback of the advertising video as a response to the call resumeAdVideo.

- (void)onAdVideoStop;

The method should be called after the ad video playback stops, as a response to the stopAdVideo method call.

- (void)onAdVideoErrorWithReason:(NSString *)reason;

Method should be invoked upon the occurrence of any error during the playback of the advertising video.

- (void)onAdVideoComplete;

The method must be called when the ad video is finished playing.

Using the SDK player

myTarget SDK provides a ready-made player for playing ads. To use the SDK player, simply call the useDefaultPlayer method on the created MTRGInstreamAd instance and add the player to the application screen.

@interface YourViewController : UIViewController
@end
 
@implementation YourViewController
{
  MTRGInstreamAd *_ad;
}
 
- (void)initAd
{
    // Create an instance of MTRGInstreamAd
    _ad = [MTRGInstreamAd instreamAdWithSlotId:YOUR_SLOT_ID];
     
    // Install the player SDK
    [_ad useDefaultPlayer];
    // Add player to the screen
    [self.view addSubview:_ad.player.adPlayerView];
}

Download ads

To receive notifications (such as a successful data download or a download error, an ad impression), you must install a delegate that implements the MTRGInstreamAdDelegate Protocol on the created instance of MTRGInstreamAd, and then you can start the data download.

@interface YourViewController : UIViewController <MTRGInstreamAdDelegate>
@end
 
@implementation YourViewController
{
  MTRGInstreamAd *_ad;
}
 
- (void)initAd
{
    // Create an instance of MTRGInstreamAd
    _ad = [MTRGInstreamAd instreamAdWithSlotId:YOUR_SLOT_ID];
     
    // Set the delegate
    _ad.delegate = self;
 
    // Start loading data
    [_ad load];
}
 
- (void)onLoadWithInstreamAd:(MTRGInstreamAd *)instreamAd
{
   // The data was successfully loaded
}
 
- (void)onNoAdWithReason:(NSString *)reason instreamAd:(MTRGInstreamAd *)instreamAd
{
   // No data received
}
 
- (void)onErrorWithReason:(NSString *)reason instreamAd:(MTRGInstreamAd *)instreamAd
{
   // An error occurred while playing the promotional video
}
 
- (void)onBannerStart:(MTRGInstreamAdBanner *)banner instreamAd:(MTRGInstreamAd *)instreamAd
{
   // Began playing the promotional video
}
 
- (void)onBannerComplete:(MTRGInstreamAdBanner *)banner instreamAd:(MTRGInstreamAd *)instreamAd
{
   // Ad video playback completed
}
 
- (void)onBannerTimeLeftChange:(NSTimeInterval)timeLeft duration:(NSTimeInterval)duration instreamAd:(MTRGInstreamAd *)instreamAd
{
   // Is called multiple times during playback of the promotional video is used to update the timer before the end of the show promotional video
}
 
- (void)onCompleteWithSection:(NSString *)section instreamAd:(MTRGInstreamAd *)instreamAd
{
   // Playback of all promotional videos in the advertising section is completed
}
 
- (void)onShowModalWithInstreamAd:(MTRGInstreamAd *)instreamAd
{
}
 
- (void)onDismissModalWithInstreamAd:(MTRGInstreamAd *)instreamAd
{
}
 
- (void)onLeaveApplicationWithInstreamAd:(MTRGInstreamAd *)instreamAd
{
}

Display ads

After the data has been successfully uploaded, you can start displaying ad sections.

Each partition section can contain multiple ad video, after the playing of each method will be called onBannerStart in the prescribed delegate MTRGInstreamAdDelegate, after playing each video method will be called onBannerComplete.

After the playback of all advertising videos in the running section is completed, the onComplete method will be called — this is what you should use for further actions, it will be called even if an error occurred during playback and the onError method was called.

Display of preroll and postroll sections

To display preroll section must before you start showing the video to invoke a method startPreroll instance InstreamAd.

To show the postroll section is necessary after the end of the video to call the method startPostroll.

// Before starting the main video
[_ad startPreroll];
 
// After showing the main video
[_ad startPostroll];

Showing the midroll section

To display midroll section in any position of the video, you can create an instance MTRGInstreamAd ask an array of positions, which is planned to show the midroll section.

Positions can be set in seconds or as a percentage of the video duration. After successful data loading, an array of positions for which there are promotional videos will be available. That is, if positions were set at the first and fifth seconds, and advertising videos in the downloaded data are only for the first, then only one first position will be available in the array.

If the positions were not set by the application, they will be set by the server.

If the array of positions after loading is empty, then there is no data to show the midroll section.

@interface YourViewController : UIViewController <MTRGInstreamAdDelegate>
@end
 
@implementation YourViewController
{
    MTRGInstreamAd *_ad;
    NSArray <NSNumber *> *_adPositions;
}
 
- (void)initAd
{
    // Create an instance of MTRGInstreamAd
    _ad = [MTRGInstreamAd instreamAdWithSlotId:YOUR_SLOT_ID];
 
    // Set positions on the first and fifth seconds of the video
    [_ad configureMidpoints:@[@1, @5] forVideoDuration:_videoDuration];
    // or percentage, 10% and 50% video
    // [_ad configureMidpointsP:@[@10, @50] forVideoDuration:_videoDuration];
     
    // Set the delegate
    _ad.delegate = self;
  
    // Start loading data
    [_ad load];
}
  
- (void)onLoadWithInstreamAd:(MTRGInstreamAd *)instreamAd
{
    // The data was successfully loaded
    // Array of positions (in seconds) available to display the midroll section
    _adPositions = _ad.midpoints;
}

When the main video reaches one of the positions for the midroll section, it is necessary to call the startMidroll method and pass this position to it as a parameter.

// The video was played to the 5th second and it has a position in the array adPositions
[_ad startMidrollWithPoint:_adPositions[1]];

Available ad video properties

The onBannerStart and onBannerComplete methods of the MTRGInstreamAdDelegate delegate pass an instance of MTRGInstreamAdBanner that contains information about the current promotional video that can be used by the application.

@property(nonatomic) NSTimeInterval duration;

The duration of the current promotional video in seconds.

@property(nonatomic) BOOL allowClose;

Is it allowed to close the advertising video during playback. Used to control the display of the "Close" or "Skip" button.

@property(nonatomic) NSTimeInterval allowCloseDelay;

The time in seconds after which the ad video can be closed. Used to control the display of the "Close" or "Skip" button.

@property(nonatomic) CGSize size;

Ширина и высота рекламного видео.

@property(nonatomic, copy) NSString *ctaText;

Text for call-to-action buttons.

Click processing

The application should independently track clicks on the advertising video (usually on the cta button) and call the handleClickWithController method in the MTRGInstreamAd instance to process the click and go to the advertised site or application.

- (void)onAdClick
{
    [_ad handleClickWithController:self];
}

Condition management

The following control methods are available on the MTRGInstreamAd instance.

- (void)pause;

Pauses the playback of the advertising video.

- (void)resume;

Resumes playing the promotional video.

- (void)stop;

Stops the display of the ad section.

- (void)skip;

Stops the display of the advertising section, if it was done by the user (pressing the "Skip" or "Close" button).

- (void)skipBanner;

Stops the current promotional video and moves on to the next one if it was made by the user (click on the "Skip" or "Close"button).

@property(nonatomic) float volume;

Sets the volume from 0 to 1.

@property(nonatomic) NSUInteger loadingTimeout;

Sets the timeout for loading ads in seconds. If at the expiration of the specified interval failed to get the banners will be triggered callback onNoAd. The default value is 10 seconds and the minimum value is 5 seconds.

User data

For the best selection of advertisements, you can optionally specify the gender and age of the user. If your application uses its own localization model, you can also specify the language of the selected localization in ISO 639-1 format ("ru", "en", "fr", etc.).

To set custom data, you need to use the customParams property.

@interface YourViewController : UIViewController
@end
 
@implementation YourViewController
{
  MTRGInstreamAd *_ad;
}
 
- (void)initAd
{
    // Create an instance of MTRGInstreamAd
    _ad = [MTRGInstreamAd instreamAdWithSlotId:YOUR_SLOT_ID];
  
    // Set the age
    _ad.customParams.age = [NSNumber numberWithInt:25];
    // Set gender
    _ad.customParams.gender = MTRGGenderMale;
}

Samples

Examples of integration are available in our demo application on Github.

Was this article helpful?

Yes

No