Начало работы с IMA DAI SDK

IMA SDK упрощают интеграцию мультимедийной рекламы на ваши веб-сайты и приложения. IMA SDK могут запрашивать рекламу с любого рекламного сервера , совместимого с VAST, и управлять воспроизведением рекламы в ваших приложениях. С помощью SDK IMA DAI приложения отправляют потоковый запрос на рекламу и видеоконтент — либо VOD, либо контент в реальном времени. Затем SDK возвращает объединенный видеопоток, так что вам не придется управлять переключением между рекламой и видеоконтентом в вашем приложении.

Выберите решение DAI, которое вас интересует

Полный сервис DAI

В этом руководстве показано, как интегрировать IMA DAI SDK в простое приложение видеоплеера. Если вы хотите просмотреть или проследить за завершенным примером интеграции, загрузите BasicExample с GitHub.

Обзор IMA DAI

Реализация IMA DAI включает в себя четыре основных компонента SDK, как показано в этом руководстве:

  • IMAAdDisplayContainer — объект-контейнер, который находится поверх элемента воспроизведения видео и содержит элементы пользовательского интерфейса рекламы.
  • IMAAdsLoader — объект, который запрашивает потоки и обрабатывает события, инициированные объектами ответа на запрос потока. Вам следует создать только один экземпляр загрузчика рекламы, который можно будет повторно использовать на протяжении всего срока службы приложения.
  • IMAStreamRequest — либо IMAVODStreamRequest , либо IMALiveStreamRequest . Объект, определяющий запрос потока. Запросы потока могут быть либо для видео по запросу, либо для живых потоков. Запросы в прямом эфире указывают ключ актива, в то время как запросы VOD указывают идентификатор CMS и идентификатор видео. Оба типа запроса могут дополнительно включать ключ API, необходимый для доступа к указанным потокам, и сетевой код Google Ad Manager для IMA SDK для обработки рекламных идентификаторов, как указано в настройках Google Ad Manager.
  • IMAStreamManager - объект, который обрабатывает динамические потоки вставки AD и взаимодействие с бэкэнд DAI. Manager Stream также обрабатывает отслеживание пингов и переходных потоков и рекламных событий для издателя.

Предварительные условия

Прежде чем начать, вам необходимо следующее:

Вам также нужны параметры, используемые для запроса вашего потока из IMA SDK. Для примеров параметров запроса см. Примерные потоки .

Параметры прямой трансляции
Ключ актива Ключ актива , определяющий вашу прямую трансляцию в Google Ad Manager .
Пример: c-rArva4ShKVIAkNfy6HUQ
Параметры VOD-потока
Идентификатор источника контента Идентификатор источника контента из Google Ad Manager.
Пример: 2548831
Идентификатор видео Идентификатор видео из Google Ad Manager.
Пример: tears-of-steel
Общие параметры (VOD и прямая трансляция)
Сетевой код Код вашей сети Google Ad Manager.
Пример: 21775744923 .

Создайте новый проект Xcode.

В Xcode создайте новый проект iOS с помощью Objective-C с именем «BasicExample».

Добавьте IMA DAI SDK в проект Xcode.

Используйте один из этих трех методов для установки IMA DAI SDK.

Установите SDK с помощью CocoaPods (предпочтительно)

Кокоподы являются менеджером зависимостей для проектов Xcode и является рекомендуемым методом для установки IMA DAI SDK. For more information on installing or using CocoaPods, see the CocoaPods documentation . После установки CocoaPods используйте следующие инструкции для установки IMA DAI SDK:

  1. В том же каталоге, что и файл BasicExample.xcodeproj , создайте текстовый файл с именем Podfile и добавьте следующую конфигурацию:

    Подфайл 
    source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '14'

target 'BasicExample' do
  pod 'GoogleAds-IMA-iOS-SDK', '~> 3.24.0'
end

    Podfile

  2. Из каталога, содержащего подфайл, запустите:

    pod install --repo-update

Установите SDK с помощью диспетчера пакетов Swift.

SDK Interactive Media Ads поддерживает Swift Package Manager , начиная с версии 3.18.4. Выполните следующие шаги, чтобы импортировать пакет Swift.

  1. В Xcode установите пакет IMA DAI SDK Swift, выбрав «Файл» > «Добавить пакеты» .

  2. В появившемся окне найдите репозиторий IMA DAI SDK Swift Package GitHub:

    https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios

  3. Выберите версию пакета IMA DAI SDK Swift, которую вы хотите использовать. Для новых проектов мы рекомендуем использовать Up to Next Major Version .

Когда вы закончите, Xcode разрешит зависимости вашего пакета и загрузит их в фоновом режиме. Более подробную информацию о том, как добавить зависимости пакета, можно найти в статье Apple .

Загрузите и установите SDK вручную.

Если вы не хотите использовать Swift Package Manager или CocoaPods, вы можете загрузить IMA DAI SDK и вручную добавить его в свой проект.

Создайте простой видеоплеер

Реализуйте видеоплеер в главном контроллере представления, используя AV-плеер, завернутый в представление пользовательского интерфейса. IMA SDK использует представление пользовательского интерфейса для отображения элементов пользовательского интерфейса рекламы.

ViewController.m 
#import "ViewController.h"

#import <AVKit/AVKit.h>

/// Content URL.
static NSString *const kBackupContentUrl =
    @"http://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8";

@interface ViewController ()
/// Play button.
@property(nonatomic, weak) IBOutlet UIButton *playButton;

@property(nonatomic, weak) IBOutlet UIView *videoView;
/// Video player.
@property(nonatomic, strong) AVPlayer *videoPlayer;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.view.backgroundColor = [UIColor blackColor];

  // Load AVPlayer with the path to your content.
  NSURL *contentURL = [NSURL URLWithString:kBackupContentUrl];
  self.videoPlayer = [AVPlayer playerWithURL:contentURL];

  // Create a player layer for the player.
  AVPlayerLayer *playerLayer = [AVPlayerLayer playerLayerWithPlayer:self.videoPlayer];

  // Size, position, and display the AVPlayer.
  playerLayer.frame = self.videoView.layer.bounds;
  [self.videoView.layer addSublayer:playerLayer];
}

- (IBAction)onPlayButtonTouch:(id)sender {
  [self.videoPlayer play];
  self.playButton.hidden = YES;
}

@end

ViewController.m

Инициализируйте загрузчик рекламы

Импортируйте IMA SDK в свой контроллер представления и используйте протоколы IMAAdsLoaderDelegate и IMAStreamManagerDelegate для обработки событий загрузчика рекламы и менеджера потоков.

Добавьте эти частные свойства для хранения ключевых компонентов IMA SDK:

  • IMAAdsLoader — управляет потоковыми запросами на протяжении всего времени существования вашего приложения.
  • IMAAdDisplayContainer — управляет вставкой элементов пользовательского интерфейса рекламы и управлением ими.
  • IMAAVPlayerVideoDisplay — обеспечивает связь между IMA SDK и вашим медиаплеером и обрабатывает синхронизированные метаданные.
  • IMAStreamManager — управляет воспроизведением потока и запускает события, связанные с рекламой.

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

ViewController.m 
@import GoogleInteractiveMediaAds;

// ...

@interface ViewController () <IMAAdsLoaderDelegate, IMAStreamManagerDelegate>
/// The entry point for the IMA DAI SDK to make DAI stream requests.
@property(nonatomic, strong) IMAAdsLoader *adsLoader;
/// The container where the SDK renders each ad's user interface elements and companion slots.
@property(nonatomic, strong) IMAAdDisplayContainer *adDisplayContainer;
/// The reference of your video player for the IMA DAI SDK to monitor playback and handle timed
/// metadata.
@property(nonatomic, strong) IMAAVPlayerVideoDisplay *imaVideoDisplay;
/// References the stream manager from the IMA DAI SDK after successful stream loading.
@property(nonatomic, strong) IMAStreamManager *streamManager;

// ...

@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  self.adsLoader = [[IMAAdsLoader alloc] initWithSettings:nil];
  self.adsLoader.delegate = self;

  // Create an ad display container for rendering each ad's user interface elements and companion
  // slots.
  self.adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView
                                          viewController:self
                                          companionSlots:nil];

  // Create an IMAAVPlayerVideoDisplay to give the SDK access to your video player.
  self.imaVideoDisplay = [[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.videoPlayer];
}
ViewController.m

Сделать запрос на трансляцию

Когда пользователь нажимает кнопку воспроизведения, сделайте запрос нового потока. Используйте класс IMALiveStreamRequest для прямых трансляций. Для потоков VOD используйте класс IMAVODStreamRequest .

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

ViewController.m 
- (IBAction)onPlayButtonTouch:(id)sender {
  [self requestStream];
  self.playButton.hidden = YES;
}

- (void)requestStream {
  // Create a stream request. Use one of "Live stream request" or "VOD request", depending on your
  // type of stream.
  IMAStreamRequest *request;
  if (kStreamType == StreamTypeLive) {
    // Live stream request. Replace the asset key with your value.
    request = [[IMALiveStreamRequest alloc] initWithAssetKey:kLiveStreamAssetKey
                                                 networkCode:kNetworkCode
                                          adDisplayContainer:self.adDisplayContainer
                                                videoDisplay:self.imaVideoDisplay
                                                 userContext:nil];
  } else {
    // VOD request. Replace the content source ID and video ID with your values.
    request = [[IMAVODStreamRequest alloc] initWithContentSourceID:kVODContentSourceID
                                                           videoID:kVODVideoID
                                                       networkCode:kNetworkCode
                                                adDisplayContainer:self.adDisplayContainer
                                                      videoDisplay:self.imaVideoDisplay
                                                       userContext:nil];
  }
  [self.adsLoader requestStreamWithRequest:request];
}
ViewController.m

Прослушивание событий загрузки потока

Класс IMAAdsLoader вызывает методы IMAAdsLoaderDelegate при успешной инициализации или сбое запроса потока.

В методе adsLoadedWithData установите свой IMAStreamManagerDelegate . Инициализируйте менеджер потоков. При инициализации менеджер потоков начинает воспроизведение.

В методе failedWithErrorData зарегистрируйте ошибку. При желании воспроизведите резервный поток. См . рекомендации по DAI .

ViewController.m 
- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  NSLog(@"Stream created with: %@.", adsLoadedData.streamManager.streamId);
  self.streamManager = adsLoadedData.streamManager;
  self.streamManager.delegate = self;
  [self.streamManager initializeWithAdsRenderingSettings:nil];
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Log the error and play the content.
  NSLog(@"AdsLoader error, code:%ld, message: %@", adErrorData.adError.code,
        adErrorData.adError.message);
  [self.videoPlayer play];
}
ViewController.m

Слушайте рекламные события

IMAStreamManager вызывает методы IMAStreamManagerDelegate для передачи событий и ошибок потока в ваше приложение.

В этом примере запишите основные рекламные события в консоль:

ViewController.m 
- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {
  NSLog(@"Ad event (%@).", event.typeString);
  switch (event.type) {
    case kIMAAdEvent_STARTED: {
      // Log extended data.
      NSString *extendedAdPodInfo = [[NSString alloc]
          initWithFormat:@"Showing ad %ld/%ld, bumper: %@, title: %@, description: %@, contentType:"
                         @"%@, pod index: %ld, time offset: %lf, max duration: %lf.",
                         (long)event.ad.adPodInfo.adPosition, (long)event.ad.adPodInfo.totalAds,
                         event.ad.adPodInfo.isBumper ? @"YES" : @"NO", event.ad.adTitle,
                         event.ad.adDescription, event.ad.contentType,
                         (long)event.ad.adPodInfo.podIndex, event.ad.adPodInfo.timeOffset,
                         event.ad.adPodInfo.maxDuration];

      NSLog(@"%@", extendedAdPodInfo);
      break;
    }
    case kIMAAdEvent_AD_BREAK_STARTED: {
      NSLog(@"Ad break started");
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      NSLog(@"Ad break ended");
      break;
    }
    case kIMAAdEvent_AD_PERIOD_STARTED: {
      NSLog(@"Ad period started");
      break;
    }
    case kIMAAdEvent_AD_PERIOD_ENDED: {
      NSLog(@"Ad period ended");
      break;
    }
    default:
      break;
  }
}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
  NSLog(@"StreamManager error with type: %ld\ncode: %ld\nmessage: %@", error.type, error.code,
        error.message);
  [self.videoPlayer play];
}
ViewController.m

Run your app, and if successful, you can request and play Google DAI streams with the IMA SDK. Чтобы узнать о более продвинутых функциях SDK, см. другие руководства, перечисленные на левой боковой панели, или примеры на GitHub .