iOS SDK: In-stream видео

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

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

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

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

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

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

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

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

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

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

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

Протокол MTRGInstreamAdPlayer

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

@property(nonatomic, readonly) NSTimeInterval adVideoDuration;

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

@property(nonatomic, readonly) NSTimeInterval adVideoTimeElapsed;

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

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

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

@property(nonatomic, readonly) UIView *adPlayerView;

Визуальное представление плеера, обычно self.

@property(nonatomic) float volume;

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

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

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

url — путь к видео

- (void)pauseAdVideo;

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

- (void)resumeAdVideo;

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

- (void)stopAdVideo;

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

Протокол MTRGInstreamAdPlayerDelegate

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

- (void)onAdVideoStart;

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

- (void)onAdVideoPause;

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

void onAdVideoResumed();

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

- (void)onAdVideoResume;

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

- (void)onAdVideoStop;

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

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

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

- (void)onAdVideoComplete;

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

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

myTarget SDK предоставляет готовый плеер для проигрывания рекламы. Для использования плеера SDK достаточно вызвать метод useDefaultPlayer у созданного экземпляра MTRGInstreamAd и добавить плеер на экран приложения.

@interface YourViewController : UIViewController
@end
 
@implementation YourViewController
{
  MTRGInstreamAd *_ad;
}
 
- (void)initAd
{
    // Создаем экземпляр MTRGInstreamAd
    _ad = [MTRGInstreamAd instreamAdWithSlotId:YOUR_SLOT_ID];
     
    // Устанавливаем плеер SDK
    [_ad useDefaultPlayer];
    // Добавляем плеер на экран
    [self.view addSubview:_ad.player.adPlayerView];
}

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

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


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

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

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

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

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

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

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

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

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

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

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

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

Если позиции не были заданы приложением, они будут установлены сервером.

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

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

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

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

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

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

@property(nonatomic) NSTimeInterval duration;

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

@property(nonatomic) BOOL allowClose;

Разрешено ли закрывать рекламное видео во время проигрывания. Используется для управления показом кнопки «Закрыть» или «Пропустить».

@property(nonatomic) NSTimeInterval allowCloseDelay;

Время в секундах, через которое рекламное видео может быть закрыто. Используется для управления показом кнопки «Закрыть» или «Пропустить».

@property(nonatomic) CGSize size;

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

@property(nonatomic, copy) NSString *ctaText;

Текст для call-to-action кнопки.

Обработка кликов

Приложение должно самостоятельно отслеживать клики по рекламному видео (как правило, по cta кнопке) и вызывать метод handleClickWithController в экземпляре MTRGInstreamAd для обработки клика и перехода на рекламируемый сайт или приложение.

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

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

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

- (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
{
  MTRGInstreamAd *_ad;
}
 
- (void)initAd
{
    // Создаем экземпляр MTRGInstreamAd
    _ad = [MTRGInstreamAd instreamAdWithSlotId:YOUR_SLOT_ID];
  
    // Задаем возраст
    _ad.customParams.age = [NSNumber numberWithInt:25];
    // Задаем пол
    _ad.customParams.gender = MTRGGenderMale;
}

Примеры

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

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

Да

Нет