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

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

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

Под, обслуживающий DAI

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

Обзор IMA DAI

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

  • IMAAdDisplayContainer — объект-контейнер, который находится поверх элемента воспроизведения видео и содержит элементы пользовательского интерфейса рекламы.
  • IMAAdsLoader — объект, который запрашивает потоки и обрабатывает события, инициированные объектами ответа на запрос потока. Вам следует создать только один экземпляр загрузчика рекламы, который можно будет повторно использовать на протяжении всего срока службы приложения.
  • IMAStreamRequest — либо IMAPodVODStreamRequest , либо IMAPodStreamRequest .
  • IMAStreamManager — объект, который обрабатывает потоки динамической вставки рекламы и взаимодействие с серверной частью DAI. Менеджер потоков также обрабатывает отслеживание пингов и пересылает события потока и рекламы издателю.

Кроме того, для воспроизведения потоков обслуживания модулей необходимо реализовать собственный обработчик VTP . Этот пользовательский обработчик VTP отправляет идентификатор потока вашему техническому партнеру по видео (VTP) вместе с любой другой информацией, необходимой для возврата манифеста потока, содержащего как контент, так и объединенную рекламу. Ваш VTP предоставит инструкции по реализации вашего собственного обработчика VTP.

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

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

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

Параметры прямой трансляции
Сетевой код Сетевой код вашего аккаунта Менеджера рекламы 360.
Пример: 51636543
Пользовательский ключ актива Пользовательский ключ ресурса, который идентифицирует ваше событие обслуживания модулей в Менеджере рекламы 360. Его может создать ваш манипулятор манифеста или сторонний партнер по обслуживанию модулей.
Пример: google-sample
Параметры VOD-потока
Сетевой код Сетевой код вашего аккаунта Менеджера рекламы 360.
Пример: 51636543

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

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

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

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

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

CocoaPods — это менеджер зависимостей для проектов Xcode, который рекомендуется использовать для установки IMA DAI SDK. Дополнительную информацию об установке или использовании CocoaPods см. в документации CocoaPods . После установки CocoaPods используйте следующие инструкции для установки IMA DAI SDK:

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

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

platform :ios, '14'

target 'PodServingExample' do
  pod 'GoogleAds-IMA-iOS-SDK'
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. В появившемся окне найдите репозиторий GitHub IMA DAI SDK Swift Package: 

    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

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

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

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

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

- (void)requestStream {
  // Create a stream request.
  IMAStreamRequest *request;
  if (kStreamType == StreamTypeLive) {
    // Live stream request. Replace the network code and custom asset key with your values.
    request = [[IMAPodStreamRequest alloc] initWithNetworkCode:kNetworkCode
                                                customAssetKey:kCustomAssetKey
                                            adDisplayContainer:adDisplayContainer
                                                  videoDisplay:self.videoDisplay
                                         pictureInPictureProxy:nil
                                                   userContext:nil];
  } else {
    // VOD request. Replace the network code with your value.
    request = [[IMAPodVODStreamRequest alloc] initWithNetworkCode:@kNetworkCode
                                               adDisplayContainer:adDisplayContainer
                                                     videoDisplay:self.videoDisplay
                                            pictureInPictureProxy:nil
                                                      userContext:nil];
  }
  [self.adsLoader requestStreamWithRequest:request];
}
ViewController.m

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

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

В методе adsLoadedWithData установите свой IMAStreamManagerDelegate . Передайте идентификатор потока своему пользовательскому обработчику VTP и получите URL-адрес манифеста потока. Для прямых трансляций загрузите URL-адрес манифеста на видеодисплей и начните воспроизведение. Для потоков VOD передайте URL-адрес манифеста в метод loadThirdPartyStream диспетчера потоков. Этот метод запрашивает данные о рекламных событиях из Менеджера рекламы 360, затем загружает URL-адрес манифеста и запускает воспроизведение.

В методе 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;

  // Build the Pod serving Stream URL.
  NSString *streamID = adsLoadedData.streamManager.streamId;
  // Your custom VTP handler takes the stream ID and returns the stream manifest URL.
  NSString *urlString = gCustomVTPHandler(streamID);
  NSURL *streamUrl = [NSURL URLWithString:urlString];
  if (kStreamType == StreamTypeLive) {
    // Load live streams directly into the AVPlayer.
    [self.videoDisplay loadStream:streamUrl withSubtitles:@[]];
    [self.videoDisplay play];
  } else {
    // Load VOD streams using the `loadThirdPartyStream` method in IMA SDK's stream manager.
    // The stream manager loads the stream, requests metadata, and starts playback.
    [self.streamManager loadThirdPartyStream:streamUrl streamSubtitles:@[]];
  }
}

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

Реализуйте свой собственный обработчик VTP

Пользовательский обработчик VTP отправляет идентификатор потока зрителя вашему техническому партнеру по видео (VTP) вместе с любой другой информацией, которая требуется вашему VTP для возврата манифеста потока, содержащего как контент, так и объединенную рекламу. Ваш VTP предоставит конкретные инструкции по реализации вашего собственного обработчика VTP.

For example, a VTP may include a manifest template URL containing the macro [[STREAMID]] . In this example, the handler inserts the Stream ID in place of the macro and returns the resulting manifest URL.

ViewController.m 
/// Custom VTP Handler.
///
/// Returns the stream manifest URL from the video technical partner or manifest manipulator.
static NSString *(^gCustomVTPHandler)(NSString *) = ^(NSString *streamID) {
  // Insert synchronous code here to retrieve a stream manifest URL from your video tech partner
  // or manifest manipulation server.
  // This example uses a hardcoded URL template, containing a placeholder for the stream
  // ID and replaces the placeholder with the stream ID.
  NSString *manifestUrl = @"YOUR_MANIFEST_URL_TEMPLATE";
  return [manifestUrl stringByReplacingOccurrencesOfString:@"[[STREAMID]]"
                                                withString:streamID];
};
ViewController.m

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

The IMAStreamManager calls the IMAStreamManagerDelegate methods to pass stream events and errors to your application.

For this example, log the primary ad events to the console:

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

Очистите активы IMA DAI

Чтобы остановить воспроизведение потока, остановить все объявления и выпустить все загруженные активы потока, позвоните IMAStreamManager.destroy() .

Запустите свое приложение, и в случае успеха вы можете запросить и воспроизводить Google Dai Streams с помощью IMA SDK. Чтобы узнать о более продвинутых функциях SDK, см. другие руководства, перечисленные на левой боковой панели, или примеры на GitHub .