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. Менеджер потоков также обрабатывает отслеживание пингов и пересылает события потока и рекламы издателю.
Предварительные условия
Прежде чем начать, вам необходимо следующее:
- Xcode 13 или новее
- CocoaPods (предпочтительно), Swift Package Manager или загруженная копия IMA DAI SDK для tvOS
Создайте новый проект Xcode.
В Xcode создайте новый проект tvOS, используя Objective-C. Используйте BasicExample в качестве имени проекта.
Добавьте IMA DAI SDK в проект Xcode.
Используйте один из этих трех методов для установки IMA DAI SDK.
Установите SDK с помощью CocoaPods (предпочтительно)
CocoaPods — это менеджер зависимостей для проектов Xcode, который рекомендуется использовать для установки IMA DAI SDK. Дополнительную информацию об установке или использовании CocoaPods см. в документации CocoaPods . После установки CocoaPods используйте следующие инструкции для установки IMA DAI SDK:
В том же каталоге, где находится файл BasicExample.xcodeproj , создайте текстовый файл с именем Podfile и добавьте следующую конфигурацию:
source 'https://github.com/CocoaPods/Specs.git' platform :tvos, '14' target "BasicExample" do pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.13.0' end
Из каталога, содержащего подфайл, запустите:
pod install --repo-update`
Убедитесь, что установка прошла успешно, открыв файл BasicExample.xcworkspace и подтвердив, что он содержит два проекта: BasicExample и Pods (зависимости, установленные CocoaPods).
Установите SDK с помощью диспетчера пакетов Swift.
SDK Interactive Media Ads поддерживает Swift Package Manager, начиная с версии 4.8.2. Выполните следующие действия, чтобы импортировать пакет Swift.
В Xcode установите пакет GoogleInteractiveMediaAds Swift, выбрав «Файл» > «Добавить пакеты» .
В появившемся окне найдите репозиторий GitHub пакета GoogleInteractiveMediaAds Swift:
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos
Выберите версию пакета GoogleInteractiveMediaAds Swift, которую вы хотите использовать. Для новых проектов мы рекомендуем использовать Up to Next Major Version .
Когда вы закончите, Xcode разрешит зависимости вашего пакета и загрузит их в фоновом режиме. Более подробную информацию о том, как добавить зависимости пакета, можно найти в статье Apple .
Загрузка и установка SDK вручную
Если вы не хотите использовать Swift Package Manager или CocoaPods, вы можете загрузить IMA DAI SDK и вручную добавить его в свой проект.
Создайте простой видеоплеер
Сначала реализуем базовый видеоплеер. Изначально этот проигрыватель не использует IMA DAI SDK и не содержит каких-либо методов запуска воспроизведения.
ViewController.m
#import "ViewController.h"
#import <AVKit/AVKit.h>
@interface ViewController ()
@property(nonatomic) AVPlayerViewController *playerViewController;
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
self.view.backgroundColor = [UIColor blackColor];
// Create a stream video player.
AVPlayer *player = [[AVPlayer alloc] init];
self.playerViewController = [[AVPlayerViewController alloc] init];
self.playerViewController.player = player;
// Attach the video player to the view hierarchy.
[self addChildViewController:self.playerViewController];
self.playerViewController.view.frame = self.view.bounds;
[self.view addSubview:self.playerViewController.view];
[self.playerViewController didMoveToParentViewController:self];
}
@end
Импортируйте SDK и добавьте заглушки для взаимодействия IMA.
Добавив SDK IMA DAI в свой проект, импортируйте SDK и добавьте заглушки для основных точек взаимодействия IMA.
ViewController.m
#import "ViewController.h"
#import <AVKit/AVKit.h>
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>
@interface ViewController ()
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) UIView *adContainerView;
@property(nonatomic) IMAStreamManager *streamManager;
@property(nonatomic) AVPlayerViewController *playerViewController;
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
self.view.backgroundColor = [UIColor blackColor];
[self setupAdsLoader];
// Create a stream video player.
AVPlayer *player = [[AVPlayer alloc] init];
self.playerViewController = [[AVPlayerViewController alloc] init];
self.playerViewController.player = player;
// Attach the video player to the view hierarchy.
[self addChildViewController:self.playerViewController];
self.playerViewController.view.frame = self.view.bounds;
[self.view addSubview:self.playerViewController.view];
[self.playerViewController didMoveToParentViewController:self];
[self attachAdContainer];
}
- (void)viewDidAppear:(BOOL)animated {
[super viewDidAppear:animated];
[self requestStream];
}
- (void)setupAdsLoader {}
- (void)attachAdContainer {}
- (void)requestStream {}
@end
Реализация IMAAdsLoader
Затем создайте экземпляр IMAAdsLoader
и прикрепите представление контейнера объявлений к иерархии представлений.
ViewController.m
- (void)setupAdsLoader {
self.adsLoader = [[IMAAdsLoader alloc] init];
self.adsLoader.delegate = self;
}
- (void)attachAdContainer {
self.adContainerView = [[UIView alloc] init];
[self.view addSubview:self.adContainerView];
self.adContainerView.frame = self.view.bounds;
}
Сделать запрос на трансляцию
Создайте несколько констант для хранения информации о потоке, а затем реализуйте функцию запроса потока для выполнения запроса.
ViewController.m
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>
static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
static NSString *const kVideoID = @"tears-of-steel";
@interface ViewController ()
...
- (void)requestStream {
IMAAVPlayerVideoDisplay *videoDisplay =
[[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.playerViewController.player];
IMAAdDisplayContainer *adDisplayContainer =
[[IMAAdDisplayContainer alloc] initWithAdContainer:self.adContainerView];
IMALiveStreamRequest *request = [[IMALiveStreamRequest alloc] initWithAssetKey:kAssetKey
adDisplayContainer:adDisplayContainer
videoDisplay:videoDisplay];
// VOD request. Comment out the IMALiveStreamRequest above and uncomment this IMAVODStreamRequest
// to switch from a livestream to a VOD stream.
// IMAVODStreamRequest *request =
// [[IMAVODStreamRequest alloc] initWithContentSourceId:kContentSourceID
// videoId:kVideoID
// adDisplayContainer:adDisplayContainer
// videoDisplay:videoDisplay];
[self.adsLoader requestStreamWithRequest:request];
}
Обработка событий потока
IMAAdsLoader
и IMAStreamManager
запускают события, которые используются для обработки инициализации, ошибок и изменений состояния потока. Эти события запускаются по протоколам IMAAdsLoaderDelegate
и IMAStreamManagerDelegate
. Прослушайте событие загрузки рекламы и инициализируйте поток. Если реклама не загружается, вместо этого воспроизведите резервный поток.
ViewController.m
static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
static NSString *const kVideoID = @"tears-of-steel";
static NSString *const kBackupStreamURLString =
@"https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8";
@interface ViewController () <IMAAdsLoaderDelegate, IMAStreamManagerDelegate>
...
[self.adsLoader requestStreamWithRequest:request];
}
- (void)playBackupStream {
NSURL *backupStreamURL = [NSURL URLWithString:kBackupStreamURLString];
AVPlayerItem *backupStreamItem = [AVPlayerItem playerItemWithURL:backupStreamURL];
[self.playerViewController.player replaceCurrentItemWithPlayerItem:backupStreamItem];
[self.playerViewController.player play];
}
#pragma mark - IMAAdsLoaderDelegate
- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
// Initialize and listen to stream manager's events.
self.streamManager = adsLoadedData.streamManager;
self.streamManager.delegate = self;
[self.streamManager initializeWithAdsRenderingSettings:nil];
NSLog(@"Stream created with: %@.", self.streamManager.streamId);
}
- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
// Fall back to playing the backup stream.
NSLog(@"Error loading ads: %@", adErrorData.adError.message);
[self playBackupStream];
}
#pragma mark - IMAStreamManagerDelegate
- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {}
- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {}
- (void)streamManager:(IMAStreamManager *)streamManager
adDidProgressToTime:(NSTimeInterval)time
adDuration:(NSTimeInterval)adDuration
adPosition:(NSInteger)adPosition
totalAds:(NSInteger)totalAds
adBreakDuration:(NSTimeInterval)adBreakDuration {}
@end
Обработка журналов и событий ошибок
Есть несколько событий, которые могут обрабатываться делегатом диспетчера потоков, но для базовых реализаций наиболее важными являются ведение журнала событий, предотвращение действий поиска во время воспроизведения рекламы и обработка ошибок.
ViewController.m
#pragma mark - IMAStreamManagerDelegate
- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {
NSLog(@"StreamManager event (%@).", event.typeString);
switch (event.type) {
case kIMAAdEvent_STARTED: {
// Log extended data.
NSString *extendedAdPodInfo = [[NSString alloc]
initWithFormat:@"Showing ad %zd/%zd, bumper: %@, title: %@, description: %@, contentType:"
@"%@, pod index: %zd, time offset: %lf, max duration: %lf.",
event.ad.adPodInfo.adPosition, event.ad.adPodInfo.totalAds,
event.ad.adPodInfo.isBumper ? @"YES" : @"NO", event.ad.adTitle,
event.ad.adDescription, event.ad.contentType, event.ad.adPodInfo.podIndex,
event.ad.adPodInfo.timeOffset, event.ad.adPodInfo.maxDuration];
NSLog(@"%@", extendedAdPodInfo);
break;
}
case kIMAAdEvent_AD_BREAK_STARTED: {
// Prevent user seek through when an ad starts and show the ad controls.
self.adContainerView.hidden = NO;
break;
}
case kIMAAdEvent_AD_BREAK_ENDED: {
// Allow user seek through after an ad ends and hide the ad controls.
self.adContainerView.hidden = YES;
break;
}
default:
break;
}
}
- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
// Fall back to playing the backup stream.
NSLog(@"StreamManager error: %@", error.message);
[self playBackupStream];
}
@end
Вот и все! Теперь вы запрашиваете и показываете рекламу с помощью IMA DAI SDK. Чтобы узнать о более продвинутых функциях SDK, ознакомьтесь с другими руководствами или примерами на GitHub .