iOS SDK: In-stream audio

Help
/
Partners
/
iOS SDK: In-stream audio

Initialization
Using the application player
Protocol MTRGInstreamAudioAdPlayer
Protocol MTRGInstreamAudioAdPlayerDelegate
Download ads
Playing ads

Available ad audio properties
Work with companion banners
Condition management
User Data
Samples

myTarget SDK provides the ability to play in-stream audio ads in your app while listening to audio.

Ads can be run before audio playback (preroll), during playback (midroll), and after playback (postroll). The SDK downloads the data and gives the app the ability to play ads in the app's player.

Initialization

To play ad audio in your application, you must create an instance of the MTRGInstreamAudioAd class.

To create an instance of MTRGInstreamAudioAd, you must specify your slotId. For each audio in your application, you need to create your own instance of the MTRGInstreamAudioAd class.

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

Using the application player

To play ads in the application player, it must implement the MTRGInstreamAudioAdPlayer protocol and notify the delegate MTRGInstreamAudioAdPlayerDelegate set to it.

To use your player, you need to set it in the player property of the created instance MTRGInstreamAudioAd.

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

Protocol MTRGInstreamAudioAdPlayer

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

@property(nonatomic, readonly) NSTimeInterval adAudioDuration;

The duration of the promotional audio

@property(nonatomic, readonly) NSTimeInterval adAudioTimeElapsed;

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

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

Sets a listener to the player

@property(nonatomic) float volume;

Current context

void setVolume(float volume);

Sets the volume from 0 to 1

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

Starts the playback of audio advertising.

uri — the path to the audio

- (void)pauseAdAudio;

Pauses the playback of audio advertising.

- (void)resumeAdAudio;

Resumes the playback of audio advertising.

- (void)stopAdAudio;

Stops the playback of audio advertising.

Protocol MTRGInstreamAudioAdPlayerDelegate

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

- (void)onAdAudioStart;

Method should be invoked after a successful start of playback of audio advertising, as a response to the call playAdAudioWithUrl.

- (void)onAdAudioPause;

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

- (void)onAdAudioResume;

Method should be invoked after the resumption of the playback of audio advertising, as a response to the call resumeAdAudio.

- (void)onAdAudioStop;

The method should be called after stopping the playback of advertising audio, as an answer to the stopAdAAudio method call.

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

The method must be called when any error occurs when playing advertising audio.

- (void)onAdAudioComplete;

The method must be called when the ad audio has been played.

Download ads

To receive notifications (such as a successful data download or a download error), you must install the MTRGInstreamAudioAd delegate that implements the MTRGInstreamAudioAdDelegate Protocol on the created instance, and then you can start the data download.

interface YourViewController : UIViewController <MTRGInstreamAudioAdDelegate>
@end
  
@implementation YourViewController
{
  MTRGInstreamAudioAd *_ad;
}
  
- (void)initAd
{
    // Create an instance of MTRGInstreamAudioAd
    _ad = [MTRGInstreamAudioAd instreamAudioAdWithSlotId:YOUR_SLOT_ID];
      
    // Set the delegate
    _ad.delegate = self;
  
    // Start loading data
    [_ad load];
}
  
- (void)onLoadWithInstreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
   // The data was successfully loaded
}
  
- (void)onNoAdWithReason:(NSString *)reason instreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
   // No data received
}
  
- (void)onErrorWithReason:(NSString *)reason instreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
   // An error occurred while playing the promotional video
}
  
- (void)onBannerStart:(MTRGInstreamAudioAdBanner *)banner instreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
   // Began playing the promotional video
}
  
- (void)onBannerComplete:(MTRGInstreamAudioAdBanner *)banner instreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
   // Ad video playback completed
}
  
- (void)onBannerTimeLeftChange:(NSTimeInterval)timeLeft duration:(NSTimeInterval)duration instreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
   // 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 instreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
   // Playback of all promotional videos in the advertising section is completed
}
  
- (void)onShowModalWithInstreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
}
  
- (void)onDismissModalWithInstreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
}
  
- (void)onLeaveApplicationWithInstreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
}

Playing ads

After the data has been successfully uploaded, you can start playing ad sections. Each section can contain several advertising audio, after the playback of each section will be called onBannerStart method in the installed delegate MTRGInstreamAudioAdDelegate, after the playback of each audio method will be called onBannerComplete.

After the playback of all advertising audio 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

For playing preroll section before playing audio to invoke a method startPreroll instance MTRGInstreamAudioAd.

To play the postroll section is necessary after the audio call method startPostroll.

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

Showing the midroll section

To play the midroll section in some audio position, after creating an instance of MTRGInstreamAudioAd, set an array of positions at which you plan to play the midroll section. Positions can be set in seconds or as a percentage of the audio duration.

After successful data loading, an array of positions for which there is advertising audio will be available. That is, if positions were set at the first and fifth seconds, and advertising audio in the loaded data is only for the first, then there will be only one first position in the available 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 for playing the midroll section.

@interface YourViewController : UIViewController <MTRGInstreamAudioAdDelegate>
@end
  
@implementation YourViewController
{
    MTRGInstreamAudioAd *_ad;
    NSArray <NSNumber *> *_adPositions;
}
  
- (void)initAd
{
    // Создаем экземпляр MTRGInstreamAudioAd
    _ad = [MTRGInstreamAudioAd instreamAudioAdWithSlotId:YOUR_SLOT_ID];
  
    // Set positions on the first and fifth second of audio
    [_ad configureMidpoints:@[@1, @5] forVideoDuration:_videoDuration];
    // or percentage, 10% and 50% audio
    // [_ad configureMidpointsP:@[@10, @50] forVideoDuration:_videoDuration];
      
    // Set the delegate
    _ad.delegate = self;
   
    // Start loading data
    [_ad load];
}
   
- (void)onLoadWithInstreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
    // The data was successfully loaded
    // Array of positions (in seconds) available to display the midroll section
    _adPositions = _ad.midpoints;
}

When the main audio 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.

// Audio play to 5 seconds and there position in the array adPositions
[_ad startMidrollWithPoint:_adPositions[1]];

Available ad audio properties

The onBannerStart and onBannerComplete methods of the MTRGInstreamAudioAdDelegate delegate are passed an instance of MTRGInstreamAudioAdBanner that contains information about the current ad audio that can be used by the application.

@property(nonatomic) NSTimeInterval duration;

The duration of the current ad audio in seconds.

@property(nonatomic) BOOL allowSeek;

Is it allowed to scroll through audio advertising.

@property(nonatomic) BOOL allowSkip;

Is it allowed to skip ad audio.

@property(nonatomic) BOOL allowTrackChange;

Is it allowed to move to the next track.

@property(nonatomic) NSArray<MTRGInstreamAdCompanionBanner *> *companionBanners;

List of companion banners.

@property(nonatomic, copy) NSString *adText;

Promotional text.

Work with companion banners

The application should independently monitor impressions and clicks on companion banners and call the handleCompanionShow and handleCompanionClick methods in the MTRGInstreamAudioAd instance to process the display and click and go to the advertised site or application.

- (void)onCompanionAdShow:(MTRGInstreamAdCompanionBanner *)companionBanner
{
    [_ad handleCompanionShow:companionBanner];
}
 
- (void)onCompanionAdClick:(MTRGInstreamAdCompanionBanner *)companionBanner
{
    [_ad handleCompanionClick:companionBanner withController:self];
}

Condition management

The following control methods are available on the MTRGInstreamAudioAd instance.

- (void)pause;

Pauses the playback of ad audio.

- (void)resume;

Resumes playing advertising audio.

- (void)stop;

Stops the advertising section.

- (void)skip;

Stops the advertising section display if it was done by the user (clicking on the "Skip" or "Close" button).

- (void)skipBanner;

Stops the current ad audio and proceeds to the next if it was done by the user (clicking 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 advertising loading in seconds. In case if after the expiration of the specified interval it was not possible to get banners, the onNoAd callback will be called. The default is 10 seconds, the minimum is 5 seconds.

User Data

For a better selection of advertisements, you can additionally 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 user data, you need to use the customParams property.

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

Samples

Integration examples are available in our demo application on Github.

Was this article helpful?

Yes

No