iOS SDK: In-stream аудио

Инициализация
Использование плеера приложения
Протокол MTRGInstreamAudioAdPlayer
Протокол MTRGInstreamAudioAdPlayerDelegate
Загрузка рекламных объявлений
Проигрывание рекламных объявлений

Доступные свойства рекламного аудио
Работа с баннерами-компаньонами
Управление состоянием
Пользовательские данные
Примеры

myTarget SDK предоставляет возможность проигрывать in-stream аудио-рекламу в своем приложении во время прослушивания аудио.

Реклама может быть запущена перед началом проигрывания аудио (preroll), во время проигрывания (midroll) и после проигрывания (postroll). SDK загружает данные и предоставляет приложению возможность проигрывать рекламу в плеере приложения.

Инициализация

Для проигрывания рекламного аудио в вашем приложении необходимо создать экземпляр класса MTRGInstreamAudioAd.

Для создания экземпляра MTRGInstreamAudioAd необходимо указать ваш slotId. Для каждого аудио в приложении требуется создавать свой экземпляр класса MTRGInstreamAudioAd.

@interface YourViewController : UIViewController
@end
  
@implementation YourViewController
{
  MTRGInstreamAudioAd *_ad;
}
  
- (void)initAd
{
    // Включение режима отладки
    // [MTRGInstreamAudioAd setDebugMode:YES];
    // Создаем экземпляр MTRGInstreamAudioAd
    _ad = [MTRGInstreamAudioAd instreamAudioAdWithSlotId:YOUR_SLOT_ID];
}

Использование плеера приложения

Для проигрывания рекламы в плеере приложения, он должен реализовывать протокол MTRGInstreamAudioAdPlayer и уведомлять установленный ему делегат MTRGInstreamAudioAdPlayerDelegate.

Для использования своего плеера надо установить его в свойство player у созданного экземпляра MTRGInstreamAudioAd.

@interface YourViewController : UIViewController
@end
  
@implementation YourViewController
{
  MTRGInstreamAudioAd *_ad;
}
  
- (void)initAd
{
    // Создаем экземпляр MTRGInstreamAudioAd
    _ad = [MTRGInstreamAudioAd instreamAudioAdWithSlotId:YOUR_SLOT_ID];
      
    // Устанавливаем плеер
    _ad.player = YOUR_PLAYER;
}

Протокол MTRGInstreamAudioAdPlayer

Методы протокола MTRGInstreamAudioAdPlayer вызываются экземпляром MTRGInstreamAudioAd. Вызывать их самостоятельно не требуется.

@property(nonatomic, readonly) NSTimeInterval adAudioDuration;

Длительность рекламного аудио

@property(nonatomic, readonly) NSTimeInterval adAudioTimeElapsed;

Текущая позиция рекламного аудио. Метод вызывается многократно во время проигрывания рекламного аудио и должен отдавать актуальное значение в секундах.

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

Устанавливает делегат плеера

@property(nonatomic) float volume;

Текущий контекст.

void setVolume(float volume);

Устанавливает громкость от 0 до 1.

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

Запускает воспроизведение рекламного аудио.

uri — путь к аудио

- (void)pauseAdAudio;

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

- (void)resumeAdAudio;

Возобновляет проигрывание рекламного аудио.

- (void)stopAdAudio;

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

Протокол MTRGInstreamAudioAdPlayerDelegate

Методы обратного вызова протокола MTRGInstreamAudioAdPlayerDelegate для установленного делегата должны быть вызваны плеером в ответ на вызовы методов протокола MTRGInstreamAudioAdPlayer при наступлении определенных событий.

- (void)onAdAudioStart;

Метод должен быть вызван после успешного начала воспроизведения рекламного аудио, как ответ на вызов метода playAdAudioWithUrl..

- (void)onAdAudioPause;

Метод должен быть вызван после приостановки проигрывания рекламного аудио, как ответ на вызов метода pauseAdAudio.

- (void)onAdAudioResume;

Метод должен быть вызван после возобновления проигрывания рекламного аудио, как ответ на вызов метода resumeAdAudio.

- (void)onAdAudioStop;

Метод должен быть вызван после остановки проигрывания рекламного аудио, как ответ на вызов метода stopAdAudio.

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

Метод должен быть вызван при возникновении какой-либо ошибки при проигрывании рекламного аудио.

- (void)onAdAudioComplete;

Метод должен быть вызван при завершении проигрывания рекламного аудио.

Загрузка рекламных объявлений

Для получения уведомлений (таких как успешная загрузка данных или ошибка загрузки) необходимо установить созданному экземпляру MTRGInstreamAudioAd делегат, реализующий протокол MTRGInstreamAudioAdDelegate, после чего можно запустить загрузку данных.

interface YourViewController : UIViewController <MTRGInstreamAudioAdDelegate>
@end
  
@implementation YourViewController
{
  MTRGInstreamAudioAd *_ad;
}
  
- (void)initAd
{
    // Создаем экземпляр MTRGInstreamAudioAd
    _ad = [MTRGInstreamAudioAd instreamAudioAdWithSlotId:YOUR_SLOT_ID];
      
    // Устанавливаем делегат
    _ad.delegate = self;
  
    // Запускаем загрузку данных
    [_ad load];
}
  
- (void)onLoadWithInstreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
   // Данные успешно загружены
}
  
- (void)onNoAdWithReason:(NSString *)reason instreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
   // Данные не получены
}
  
- (void)onErrorWithReason:(NSString *)reason instreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
   // При проигрывании рекламного видео произошла ошибка
}
  
- (void)onBannerStart:(MTRGInstreamAudioAdBanner *)banner instreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
   // Началось проигрывание рекламного видео
}
  
- (void)onBannerComplete:(MTRGInstreamAudioAdBanner *)banner instreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
   // Проигрывание рекламного видео завершено
}
  
- (void)onBannerTimeLeftChange:(NSTimeInterval)timeLeft duration:(NSTimeInterval)duration instreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
   // Вызывается многократно во время воспроизведения рекламного видео, используется для обновления таймера до окончания показа рекламного видео
}
  
- (void)onCompleteWithSection:(NSString *)section instreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
   // Проигрывание всех рекламных видео в рекламной секции завершено
}
  
- (void)onShowModalWithInstreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
}
  
- (void)onDismissModalWithInstreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
}
  
- (void)onLeaveApplicationWithInstreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
}

Проигрывание рекламных объявлений

После успешной загрузки данных вы можете запустить проигрывание рекламных секций. Каждая секция секция может содержать несколько рекламных аудио, после начала проигрывания каждого будет вызван метод onBannerStart в установленном делегате MTRGInstreamAudioAdDelegate, после завершения проигрывания каждого аудио будет вызван метод onBannerComplete.

После завершения проигрывания всех рекламных аудио в запущенной секции будет вызван метод onComplete — именно его вы должны использовать для дальнейших действий. Он будет вызван даже если в процессе проигрывания произошла ошибка и был вызван метод onError.

Показ preroll и postroll секций

Для проигрывания preroll секции необходимо перед началом проигрывания аудио вызвать метод startPreroll у экземпляра MTRGInstreamAudioAd.

Для проигрывания postroll секции необходимо после окончания проигрывания аудио вызвать метод startPostroll.

// Перед началом показа основного видео
[_ad startPreroll];
  
// После показа основного видео
[_ad startPostroll];

Показ midroll секции

Для проигрывания midroll секции в какой-то позиции аудио необходимо после создания экземпляра MTRGInstreamAudioAd задать массив позиций, на которых планируется проигрывание midroll секции. Позиции можно задавать как в секундах, так и в процентах от длительности аудио.

После успешной загрузки данных станет доступен массив позиций, для которых есть рекламные аудио. То есть если были заданы позиции на первой и пятой секунде, а рекламные аудио в загруженных данных есть только для первой, то в доступном массиве будет только одна первая позиция. Если позиции не были заданы приложением, они будут установлены сервером.

Если массив позиций после загрузки оказался пустой, значит данных для проигрывания midroll секции нет.

@interface YourViewController : UIViewController <MTRGInstreamAudioAdDelegate>
@end
  
@implementation YourViewController
{
    MTRGInstreamAudioAd *_ad;
    NSArray <NSNumber *> *_adPositions;
}
  
- (void)initAd
{
    // Создаем экземпляр MTRGInstreamAudioAd
    _ad = [MTRGInstreamAudioAd instreamAudioAdWithSlotId:YOUR_SLOT_ID];
  
    // Устанавливаем позиции на первой и пятой секунде аудио
    [_ad configureMidpoints:@[@1, @5] forVideoDuration:_videoDuration];
    // или в процентах, на 10% и 50% аудио
    // [_ad configureMidpointsP:@[@10, @50] forVideoDuration:_videoDuration];
      
    // Устанавливаем делегат
    _ad.delegate = self;
   
    // Запускаем загрузку данных
    [_ad load];
}
   
- (void)onLoadWithInstreamAudioAd:(MTRGInstreamAudioAd *)instreamAudioAd
{
    // Данные успешно загружены
    // Массив позиций (в секундах), доступных для показа midroll секции
    _adPositions = _ad.midpoints;
}

При достижении основным аудио одной из позиций для midroll секции, необходимо вызвать метод startMidroll и передать в него в качестве параметра эту позицию.

// Аудио доигралось до 5-й секунды и для неё есть позиция в массиве adPositions
[_ad startMidrollWithPoint:_adPositions[1]];

Доступные свойства рекламного аудио

В методы onBannerStart и onBannerComplete делегата MTRGInstreamAudioAdDelegate передается экземпляр MTRGInstreamAudioAdBanner, содержащий информацию о текущем рекламном аудио, которая может быть использована приложением.

@property(nonatomic) NSTimeInterval duration;

Длительность текущего рекламного аудио в секундах.

@property(nonatomic) BOOL allowSeek;

Разрешено ли прокручивать рекламное аудио.

@property(nonatomic) BOOL allowSkip;

Разрешено ли пропускать рекламное аудио.

@property(nonatomic) BOOL allowTrackChange;

Разрешено ли переходить к следующему треку.

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

Список баннеров-компаньонов.

@property(nonatomic, copy) NSString *adText;

Рекламный текст.

Работа с баннерами-компаньонами

Приложение должно самостоятельно отслеживать показы и клики по баннерам-компаньонам и вызывать методы handleCompanionShow и handleCompanionClick в экземпляре MTRGInstreamAudioAd для обработки показа и клика и перехода на рекламируемый сайт или приложение.

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

Управление состоянием

У экземпляра MTRGInstreamAudioAd доступны следующие методы управления.

- (void)pause;

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

- (void)resume;

Возобновляет проигрывание рекламного аудио.

- (void)stop;

Останавливает показ рекламной секции.

- (void)skip;

Останавливает показ рекламной секции, если это было сделано пользователем (нажатие на кнопку «Пропустить» или «Закрыть»).

- (void)skipBanner;

Останавливает текущее рекламное аудио и переходит к следующему, если это было сделано пользователем (нажатие на кнопку «Пропустить» или «Закрыть»).

@property(nonatomic) float volume;

Устанавливает громкость от 0 до 1.

@property(nonatomic) NSUInteger loadingTimeout;

Устанавливает таймаут на загрузку рекламы в секундах. В случае если по истечению указанного интервала не удалось получить баннеры, будет вызван коллбек onNoAd. Значение по умолчанию — 10 секунд, минимальное значение — 5 секунд.

Пользовательские данные

Для лучшего подбора рекламных объявлений, вы можете дополнительно задать пол и возраст пользователя. Если ваше приложение использует собственную модель локализации, вы также можете указать язык выбранной локализации в формате ISO 639-1 ("ru", "en", "fr" и т.д.).

Для задания пользовательских данных вам нужно воспользоваться свойством customParams.

@interface YourViewController : UIViewController
@end
 
@implementation YourViewController
{
  MTRGInstreamAudioAd *_ad;
}
 
-(void) initAd
{
    // Создаем экземпляр MTRGInstreamAudioAd
    _ad = [MTRGInstreamAudioAd instreamAudioAdWithSlotId:YOUR_SLOT_ID];
  
    // Задаем возраст
    _ad.customParams.age = [NSNumber numberWithInt:25];
    // Задаем пол
    _ad.customParams.gender = MTRGGenderMale;
}

Примеры

Примеры интеграции доступны в нашем демоприложении на Github.

Вам помогла эта статья?

Да

Нет