Начало работы с 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 . Объект, определяющий запрос потока. Запросы на поток могут относиться как к видео по запросу, так и к прямым трансляциям. В запросах указывается идентификатор контента, а также ключ API или токен аутентификации и другие параметры.
  • IMAStreamManager — объект, который обрабатывает потоки динамической вставки рекламы и взаимодействие с серверной частью DAI. Менеджер потоков также обрабатывает отслеживание пингов и пересылает события потока и рекламы издателю.

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

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

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

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

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

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

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

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

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

CocoaPods — это менеджер зависимостей для проектов Xcode, который рекомендуется использовать для установки IMA DAI SDK. Дополнительную информацию об установке или использовании CocoaPods см. в документации CocoaPods . После установки 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.23.0'
    end
    
  2. Из каталога, содержащего подфайл, запустите:

    pod install --repo-update`
  3. Убедитесь, что установка прошла успешно, открыв файл BasicExample.xcworkspace и подтвердив, что он содержит два проекта: BasicExample и Pods (зависимости, установленные CocoaPods).

Установите 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 использует представление пользовательского интерфейса для отображения элементов пользовательского интерфейса рекламы.

#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

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

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

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

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

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

@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];
}

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

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

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

- (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;
  // Switch this variable to NO to make a VOD request.
  BOOL useLiveStream = YES;
  if (useLiveStream) {
    // Live stream request. Replace the asset key with your value.
    request = [[IMALiveStreamRequest alloc] initWithAssetKey:@"c-rArva4ShKVIAkNfy6HUQ"
                                          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:@"2548831"
                                                           videoID:@"tears-of-steel"
                                                adDisplayContainer:self.adDisplayContainer
                                                      videoDisplay:self.imaVideoDisplay
                                                       userContext:nil];
  }
  [self.adsLoader requestStreamWithRequest:request];
}

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

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

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

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

- (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];
}

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

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

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

- (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];
}

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