SDK IMA упрощают интеграцию мультимедийной рекламы в ваши веб-сайты и приложения. SDK IMA могут запрашивать рекламу с любого рекламного сервера, совместимого с VAST , и управлять воспроизведением рекламы в ваших приложениях. С помощью клиентских SDK IMA вы сохраняете контроль над воспроизведением видеоконтента, в то время как SDK обрабатывает воспроизведение рекламы. Реклама воспроизводится в отдельном видеоплеере, расположенном поверх видеоплеера приложения.
В этом руководстве показано, как интегрировать IMA SDK в приложение видеоплеера. Если вы хотите посмотреть или пройтись по готовому примеру интеграции, скачайте BasicExample с GitHub.
Обзор клиентской части IMA
Реализация клиентской части IMA включает в себя четыре основных компонента SDK, которые описаны в этом руководстве:
-
IMAAdDisplayContainer: Объект-контейнер, определяющий, где IMA отображает элементы пользовательского интерфейса рекламы и измеряет видимость, включая Active View и Open Measurement . -
IMAAdsLoader: Объект, который запрашивает рекламу и обрабатывает события из ответов на запросы рекламы. Следует создавать только один экземпляр загрузчика рекламы, который можно использовать повторно на протяжении всего жизненного цикла приложения. -
IMAAdsRequest: Объект, определяющий запрос на показ рекламы. Запросы на показ рекламы указывают URL-адрес тега VAST, а также дополнительные параметры, такие как размеры объявления. -
IMAAdsManager: Объект, содержащий ответ на запрос рекламы, управляющий воспроизведением рекламы и отслеживающий события, связанные с рекламой, генерируемые SDK.
Предварительные требования
Прежде чем начать, вам потребуется следующее:
- Xcode 13 или более поздняя версия
- Swift Package Manager, CocoaPods или загруженная копия IMA SDK для tvOS
1. Создайте новый проект Xcode.
В Xcode создайте новый проект tvOS, используя Objective-C или Swift. В качестве имени проекта используйте BasicExample .
2. Добавьте IMA SDK в проект Xcode.
Установите IMA SDK с помощью Swift Package Manager.
Начиная с версии 4.8.2, Interactive Media Ads SDK поддерживает Swift Package Manager . Для импорта пакета Swift выполните следующие действия.
В Xcode установите пакет IMA SDK Swift, перейдя в меню Файл > Добавить пакеты... .
В появившемся окне найдите репозиторий IMA SDK Swift Package на GitHub:
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvosВыберите версию пакета IMA SDK Swift, которую вы хотите использовать. Для новых проектов мы рекомендуем использовать версию «Up to Next Major Version» .
После завершения Xcode разрешит зависимости ваших пакетов и загрузит их в фоновом режиме. Более подробную информацию о добавлении зависимостей пакетов см. в статье Apple .
Установите IMA SDK с помощью CocoaPods.
Для установки IMA SDK используйте CocoaPods. Дополнительную информацию об установке или использовании CocoaPods см. в документации CocoaPods . После установки CocoaPods выполните следующие действия:
В той же директории, где находится файл BasicExample.xcodeproj , создайте текстовый файл с именем Podfile и добавьте в него следующую конфигурацию:
source 'https://github.com/CocoaPods/Specs.git' platform :tvos, '15' target "BasicExample" do pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.16.0' endВ директории, содержащей файл Podfile, выполните команду
pod install --repo-updateУбедитесь в успешности установки, открыв файл BasicExample.xcworkspace и проверив, что он содержит два проекта: BasicExample и Pods (зависимости, устанавливаемые CocoaPods).
Загрузка и установка IMA SDK вручную
Если вы не хотите использовать CocoaPods, вы можете загрузить IMA SDK и добавить его в свой проект вручную.
3. Импортируйте IMA SDK
Добавьте фреймворк IMA, используя оператор импорта.
Objective-C
#import "ViewController.h"
#import <AVKit/AVKit.h>
@import GoogleInteractiveMediaAds;
Быстрый
import AVFoundation
import GoogleInteractiveMediaAds
import UIKit
4. Создайте видеоплеер и интегрируйте IMA SDK.
В следующем примере выполняется инициализация IMA SDK:
Objective-C
NSString *const kContentURLString =
@"https://storage.googleapis.com/interactive-media-ads/media/stock.mp4";
NSString *const kAdTagURLString =
@"https://pubads.g.doubleclick.net/gampad/ads?"
@"iu=/21775744923/external/vmap_ad_samples&sz=640x480&"
@"cust_params=sample_ar%3Dpremidpostlongpod&ciu_szs=300x250&gdfp_req=1&ad_rule=1&"
@"output=vmap&unviewed_position_start=1&env=vp&cmsid=496&vid=short_onecue&correlator=";
@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) IMAAdDisplayContainer *adDisplayContainer;
@property(nonatomic) IMAAdsManager *adsManager;
@property(nonatomic) IMAAVPlayerContentPlayhead *contentPlayhead;
@property(nonatomic) AVPlayerViewController *contentPlayerViewController;
@property(nonatomic, getter=isAdBreakActive) BOOL adBreakActive;
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
self.view.backgroundColor = [UIColor blackColor];
[self setupAdsLoader];
[self setupContentPlayer];
}
- (void)viewDidAppear:(BOOL)animated {
[super viewDidAppear:animated];
[self requestAds];
}
// Add the content video player as a child view controller.
- (void)showContentPlayer {
[self addChildViewController:self.contentPlayerViewController];
self.contentPlayerViewController.view.frame = self.view.bounds;
[self.view insertSubview:self.contentPlayerViewController.view atIndex:0];
[self.contentPlayerViewController didMoveToParentViewController:self];
}
// Remove and detach the content video player.
- (void)hideContentPlayer {
// The whole controller needs to be detached so that it doesn't capture resume events from the
// remote and play content underneath the ad.
[self.contentPlayerViewController willMoveToParentViewController:nil];
[self.contentPlayerViewController.view removeFromSuperview];
[self.contentPlayerViewController removeFromParentViewController];
}
Быстрый
class ViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {
static let contentURLString =
"https://devstreaming-cdn.apple.com/videos/streaming/examples/"
+ "img_bipbop_adv_example_fmp4/master.m3u8"
static let adTagURLString =
"https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_ad_samples&"
+ "sz=640x480&cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&"
+ "unviewed_position_start=1&env=vp&correlator="
var adsLoader: IMAAdsLoader!
var adDisplayContainer: IMAAdDisplayContainer!
var adsManager: IMAAdsManager!
var contentPlayhead: IMAAVPlayerContentPlayhead?
var playerViewController: AVPlayerViewController!
var adBreakActive = false
deinit {
NotificationCenter.default.removeObserver(self)
}
override func viewDidLoad() {
super.viewDidLoad()
self.view.backgroundColor = UIColor.black
setUpContentPlayer()
setUpAdsLoader()
}
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
requestAds()
}
В этом примере метод viewDidLoad() инициализирует IMAAdsLoader , а viewDidAppear() запрашивает показ рекламы, как только представление становится видимым. Вспомогательные методы showContentPlayer() и hideContentPlayer() переключают видимость контента во время воспроизведения рекламы.
В этом примере используется константная переменная adTagURLString для определения тега объявления VAST для запроса объявления, а также следующие компоненты для управления IMA SDK:
-
adsLoader: Обрабатывает запросы и ответы на рекламу. Рекомендуем использовать один экземпляр на протяжении всего жизненного цикла приложения. -
adDisplayContainer: Задает представление для отображения рекламы. -
adsManager: Управляет воспроизведением рекламы и отслеживает рекламные события. -
contentPlayhead: Отслеживает прогресс воспроизведения контента для запуска рекламных пауз в середине ролика. -
adBreakActive: Указывает, воспроизводится ли рекламная пауза, чтобы предотвратить перемотку рекламы.
5. Реализовать отслеживание положения ползунка воспроизведения контента и наблюдатель конца потока.
Для воспроизведения рекламных вставок в середине видео IMA SDK необходимо отслеживать текущее положение видеоконтента. Для этого создайте класс, реализующий интерфейс IMAContentPlayhead . Если вы используете AVPlayer , как показано в этом примере, SDK предоставляет класс IMAAVPlayerContentPlayhead , который делает это за вас. Если вы не используете AVPlayer , вам необходимо реализовать IMAContentPlayhead в собственном классе.
Objective-C
- (void)setupContentPlayer {
// Create a content video player. Create a playhead to track content progress so the SDK knows
// when to play ads in a VMAP playlist.
NSURL *contentURL = [NSURL URLWithString:kContentURLString];
AVPlayer *player = [AVPlayer playerWithURL:contentURL];
self.contentPlayerViewController = [[AVPlayerViewController alloc] init];
self.contentPlayerViewController.player = player;
self.contentPlayerViewController.view.frame = self.view.bounds;
self.contentPlayhead =
[[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayerViewController.player];
// Track end of content.
AVPlayerItem *contentPlayerItem = self.contentPlayerViewController.player.currentItem;
[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(contentDidFinishPlaying:)
name:AVPlayerItemDidPlayToEndTimeNotification
object:contentPlayerItem];
// Attach content video player to view hierarchy.
[self showContentPlayer];
}
Быстрый
func setUpContentPlayer() {
// Load AVPlayer with path to our content.
let contentURL = URL(string: ViewController.contentURLString)!
let player = AVPlayer(url: contentURL)
playerViewController = AVPlayerViewController()
playerViewController.player = player
// Set up our content playhead and contentComplete callback.
contentPlayhead = IMAAVPlayerContentPlayhead(avPlayer: player)
NotificationCenter.default.addObserver(
self,
selector: #selector(ViewController.contentDidFinishPlaying(_:)),
name: NSNotification.Name.AVPlayerItemDidPlayToEndTime,
object: player.currentItem)
showContentPlayer()
}
Также необходимо сообщить SDK о завершении воспроизведения контента, чтобы он мог отображать рекламу после ролика. Это делается путем вызова contentComplete в IMAAdsLoader с использованием AVPlayerItemDidPlayToEndTimeNotification .
Objective-C
- (void)contentDidFinishPlaying:(NSNotification *)notification {
// Notify the SDK that the postrolls should be played.
[self.adsLoader contentComplete];
}
- (void)dealloc {
[[NSNotificationCenter defaultCenter] removeObserver:self];
}
Быстрый
@objc func contentDidFinishPlaying(_ notification: Notification) {
adsLoader.contentComplete()
}
6. Инициализируйте загрузчик рекламы и отправьте запрос на показ рекламы.
Для запроса набора объявлений необходимо создать экземпляр IMAAdsLoader . Этот загрузчик можно использовать для обработки объектов IMAAdsRequest , связанных с указанным URL-адресом рекламного тега.
Рекомендуется использовать только один экземпляр IMAAdsLoader на протяжении всего жизненного цикла приложения. Для отправки дополнительных запросов на показ создайте новый объект IMAAdsRequest , но используйте тот же самый IMAAdsLoader . Дополнительную информацию см. в разделе часто задаваемых вопросов (FAQ) по IMA SDK .
Objective-C
- (void)setupAdsLoader {
self.adsLoader = [[IMAAdsLoader alloc] init];
self.adsLoader.delegate = self;
}
- (void)requestAds {
// Pass the main view as the container for ad display.
self.adDisplayContainer = [[IMAAdDisplayContainer alloc] initWithAdContainer:self.view
viewController:self];
IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kAdTagURLString
adDisplayContainer:self.adDisplayContainer
contentPlayhead:self.contentPlayhead
userContext:nil];
[self.adsLoader requestAdsWithRequest:request];
}
Быстрый
func setUpAdsLoader() {
adsLoader = IMAAdsLoader(settings: nil)
adsLoader.delegate = self
}
func requestAds() {
// Create ad display container for ad rendering.
adDisplayContainer = IMAAdDisplayContainer(adContainer: self.view, viewController: self)
// Create an ad request with our ad tag, display container, and optional user context.
let request = IMAAdsRequest(
adTagUrl: ViewController.adTagURLString,
adDisplayContainer: adDisplayContainer,
contentPlayhead: contentPlayhead,
userContext: nil)
adsLoader.requestAds(with: request)
}
7. Настройте делегат для загрузки рекламы.
При успешной загрузке IMAAdsLoader вызывает метод adsLoadedWithData назначенного ему делегата, передавая ему экземпляр IMAAdsManager . Затем можно инициализировать менеджер рекламы, который загружает отдельные объявления в соответствии с ответом на URL-адрес рекламного тега.
Кроме того, обязательно обрабатывайте любые ошибки, которые могут возникнуть в процессе загрузки. Если реклама не загружается, убедитесь, что воспроизведение медиафайлов продолжается без рекламы, чтобы не мешать пользователю.
Objective-C
#pragma mark - IMAAdsLoaderDelegate
- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
// Initialize and listen to the ads manager loaded for this request.
self.adsManager = adsLoadedData.adsManager;
self.adsManager.delegate = self;
[self.adsManager initializeWithAdsRenderingSettings:nil];
}
- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
// Fall back to playing content.
NSLog(@"Error loading ads: %@", adErrorData.adError.message);
[self.contentPlayerViewController.player play];
}
Быстрый
func adsLoader(_ loader: IMAAdsLoader, adsLoadedWith adsLoadedData: IMAAdsLoadedData) {
// Grab the instance of the IMAAdsManager and set ourselves as the delegate.
adsManager = adsLoadedData.adsManager
adsManager.delegate = self
adsManager.initialize(with: nil)
}
func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
print("Error loading ads: \(adErrorData.adError.message ?? "No error message available.")")
showContentPlayer()
playerViewController.player?.play()
}
8. Настройте делегата для управления рекламными объявлениями.
Наконец, для управления событиями и изменениями состояния менеджеру рекламы необходим собственный делегат. IMAAdManagerDelegate имеет методы для обработки событий и ошибок, связанных с рекламой, а также методы для запуска воспроизведения и паузы видеоконтента.
Начало воспроизведения
Метод didReceiveAdEvent может обрабатывать множество событий. В этом простом примере мы будем отслеживать событие LOADED , чтобы сообщить менеджеру рекламы о начале воспроизведения контента и рекламы. SDK IMA запускает событие ICON_FALLBACK_IMAGE_CLOSED когда пользователь закрывает диалоговое окно резервного варианта значка после нажатия на значок. После этого действия воспроизведение рекламы возобновляется.
Objective-C
#pragma mark - IMAAdsManagerDelegate
- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
switch (event.type) {
case kIMAAdEvent_LOADED: {
// Play each ad once it has loaded.
[adsManager start];
break;
}
case kIMAAdEvent_ICON_FALLBACK_IMAGE_CLOSED: {
// Resume ad after user has closed dialog.
[adsManager resume];
break;
}
default:
break;
}
}
Быстрый
func adsManager(_ adsManager: IMAAdsManager, didReceive event: IMAAdEvent) {
switch event.type {
case IMAAdEventType.LOADED:
// Play each ad once it has been loaded.
adsManager.start()
case IMAAdEventType.ICON_FALLBACK_IMAGE_CLOSED:
// Resume playback after the user has closed the dialog.
adsManager.resume()
default:
break
}
}
Обработка ошибок
Добавьте также обработчик ошибок, связанных с рекламой. Если возникнет ошибка, как и на предыдущем шаге, возобновите воспроизведение контента.
Objective-C
- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdError:(IMAAdError *)error {
// Fall back to playing content.
NSLog(@"AdsManager error: %@", error.message);
[self showContentPlayer];
[self.contentPlayerViewController.player play];
}
Быстрый
func adsManager(_ adsManager: IMAAdsManager, didReceive error: IMAAdError) {
// Fall back to playing content
print("AdsManager error: \(error.message ?? "No error message available.")")
showContentPlayer()
playerViewController.player?.play()
}
Запуск событий воспроизведения и паузы
Последние два метода делегата, которые вам необходимо реализовать, используются для запуска событий воспроизведения и паузы видеоконтента по запросу IMA SDK. Запуск событий паузы и воспроизведения по запросу предотвращает пропуск пользователем фрагментов видеоконтента во время показа рекламы.
Objective-C
- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
// Pause the content for the SDK to play ads.
[self.contentPlayerViewController.player pause];
[self hideContentPlayer];
// Trigger an update to send focus to the ad display container.
self.adBreakActive = YES;
[self setNeedsFocusUpdate];
}
- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
// Resume the content since the SDK is done playing ads (at least for now).
[self showContentPlayer];
[self.contentPlayerViewController.player play];
// Trigger an update to send focus to the content player.
self.adBreakActive = NO;
[self setNeedsFocusUpdate];
}
Быстрый
func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager) {
// Pause the content for the SDK to play ads.
playerViewController.player?.pause()
hideContentPlayer()
// Trigger an update to send focus to the ad display container.
adBreakActive = true
setNeedsFocusUpdate()
}
func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager) {
// Resume the content since the SDK is done playing ads (at least for now).
showContentPlayer()
playerViewController.player?.play()
// Trigger an update to send focus to the content player.
adBreakActive = false
setNeedsFocusUpdate()
}
Вот и всё! Теперь вы запрашиваете и отображаете рекламу с помощью IMA SDK. Чтобы узнать о дополнительных возможностях SDK, ознакомьтесь с другими руководствами или примерами на GitHub .
Следующие шаги
Для максимизации дохода от рекламы на платформе tvOS запросите разрешение на прозрачность и отслеживание приложения (App Transparency and Tracking) для использования IDFA .

