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 или более поздняя версия
- Способ установки IMA SDK:
- Swift Package Manager (желательно)
- CocoaPods
- Загруженная копия IMA SDK для iOS
1. Создайте новый проект Xcode.
В Xcode создайте новый проект iOS, используя Objective-C или Swift. В качестве имени проекта используйте BasicExample .
2. Добавьте SDK IMA в проект Xcode.
Для установки IMA SDK выберите предпочтительный способ.
Рекомендуется: установить SDK с помощью Swift Package Manager.
SDK для интерактивной рекламы поддерживает Swift Package Manager, начиная с версии 3.18.4. Для импорта пакета Swift выполните следующие шаги:
В Xcode установите пакет IMA SDK Swift, перейдя в меню File > Add Package Dependencies... .
В командной строке найдите репозиторий GitHub с пакетом Swift для IMA iOS SDK:
swift-package-manager-google-interactive-media-ads-ios.Выберите версию пакета IMA SDK Swift, которую вы хотите использовать. Для новых проектов мы рекомендуем использовать версию «Up to Next Major Version» .
После завершения Xcode разрешит зависимости ваших пакетов и загрузит их в фоновом режиме. Более подробную информацию о добавлении зависимостей пакетов см. в статье Apple .
Установите SDK с помощью CocoaPods.
CocoaPods — это менеджер зависимостей для проектов Xcode и рекомендуемый способ установки IMA SDK. Более подробную информацию об установке или использовании CocoaPods см. в документации CocoaPods . После установки CocoaPods используйте следующие инструкции для установки IMA SDK:
В той же директории, где находится файл BasicExample.xcodeproj , создайте текстовый файл с именем Podfile и добавьте в него следующую конфигурацию:
В директории, содержащей файл Podfile, выполните команду
pod install --repo-update.`.Убедитесь в успешности установки, открыв файл BasicExample.xcworkspace и проверив, содержит ли он два проекта: BasicExample и Pods (зависимости, установленные CocoaPods).
Загрузите и установите SDK вручную.
Если вы не хотите использовать Swift Package Manager, скачайте и вручную добавьте IMA SDK в свой проект.
Показать/скрыть инструкции
- На странице загрузки iOS IMA скачайте и распакуйте последнюю версию iOS IMA SDK.
- Откройте файл BasicExample.xcodeproj .
- В левой панели щелкните название проекта.
- В центральной панели нажмите «Этапы построения» .
- Разверните раздел « Связывание двоичных файлов с библиотеками» .
- В нижней части списка библиотек нажмите значок плюса [+] .
- Нажмите «Добавить другое» .
- В папке, куда вы распаковали загруженный SDK, выберите файл GoogleInteractiveMediaAds.framework и нажмите « Открыть» .
- В нижней части списка библиотек снова нажмите значок плюса [+] .
- В столбце «Статус» убедитесь, что для параметра
GoogleInteractiveMediaAds.frameworkустановлено значениеRequired. - Включите флаг компоновщика
-ObjCв параметры сборки. Для получения дополнительной информации см. Apple QA1490 .
3. Создайте видеоплеер.
Сначала реализуйте видеоплеер. Изначально этот плеер не использует IMA SDK и не содержит никаких методов для запуска воспроизведения.
Objective-C
Импортируйте зависимости плеера:
#import "ViewController.h"
@import AVFoundation;
Настройте переменные игрока:
@interface ViewController () <IMAAdsLoaderDelegate, IMAAdsManagerDelegate>
/// Content video player.
@property(nonatomic, strong) AVPlayer *contentPlayer;
/// Play button.
@property(nonatomic, weak) IBOutlet UIButton *playButton;
/// UIView in which we will render our AVPlayer for content.
@property(nonatomic, weak) IBOutlet UIView *videoView;
Запуск видеоплеера при загрузке страницы:
@implementation ViewController
// The content URL to play.
NSString *const kTestAppContentUrl_MP4 =
@"https://storage.googleapis.com/gvabox/media/samples/stock.mp4";
// Ad tag
NSString *const kTestAppAdTagUrl = @"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=";
- (void)viewDidLoad {
[super viewDidLoad];
self.playButton.layer.zPosition = MAXFLOAT;
[self setupAdsLoader];
[self setUpContentPlayer];
}
#pragma mark Content Player Setup
- (void)setUpContentPlayer {
// Load AVPlayer with path to our content.
NSURL *contentURL = [NSURL URLWithString:kTestAppContentUrl_MP4];
self.contentPlayer = [AVPlayer playerWithURL:contentURL];
// Create a player layer for the player.
AVPlayerLayer *playerLayer = [AVPlayerLayer playerLayerWithPlayer:self.contentPlayer];
// Size, position, and display the AVPlayer.
playerLayer.frame = self.videoView.layer.bounds;
[self.videoView.layer addSublayer:playerLayer];
// Set up our content playhead and contentComplete callback.
self.contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer];
[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(contentDidFinishPlaying:)
name:AVPlayerItemDidPlayToEndTimeNotification
object:self.contentPlayer.currentItem];
}
- (IBAction)onPlayButtonTouch:(id)sender {
[self requestAds];
self.playButton.hidden = YES;
}
Быстрый
Импортируйте зависимости плеера:
import AVFoundation
Настройте переменные игрока:
class PlayerContainerViewController: UIViewController, IMAAdsLoaderDelegate, IMAAdsManagerDelegate {
static let contentURL = URL(
string: "https://storage.googleapis.com/gvabox/media/samples/stock.mp4")!
private var contentPlayer = AVPlayer(url: PlayerContainerViewController.contentURL)
private lazy var playerLayer: AVPlayerLayer = {
AVPlayerLayer(player: contentPlayer)
}()
Запуск видеоплеера при загрузке страницы:
private lazy var videoView: UIView = {
let videoView = UIView()
videoView.translatesAutoresizingMaskIntoConstraints = false
view.addSubview(videoView)
NSLayoutConstraint.activate([
videoView.bottomAnchor.constraint(
equalTo: view.safeAreaLayoutGuide.bottomAnchor),
videoView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
videoView.trailingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.trailingAnchor),
videoView.leadingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.leadingAnchor),
])
return videoView
}()
// MARK: - View controller lifecycle methods
override func viewDidLoad() {
super.viewDidLoad()
videoView.layer.addSublayer(playerLayer)
adsLoader.delegate = self
NotificationCenter.default.addObserver(
self,
selector: #selector(contentDidFinishPlaying(_:)),
name: .AVPlayerItemDidPlayToEndTime,
object: contentPlayer.currentItem)
}
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
playerLayer.frame = videoView.layer.bounds
}
override func viewWillTransition(
to size: CGSize, with coordinator: UIViewControllerTransitionCoordinator
) {
coordinator.animate { _ in
// do nothing
} completion: { _ in
self.playerLayer.frame = self.videoView.layer.bounds
}
}
// MARK: - Public methods
func playButtonPressed() {
requestAds()
}
4. Импортируйте SDK IMA.
Для импорта IMA SDK выполните следующие действия:
Objective-C
Импортируйте SDK IMA:
@import GoogleInteractiveMediaAds;Создайте переменные для классов
IMAAdsLoader,IMAAVPlayerContentPlayheadиIMAAdsManagerиспользуемых в приложении:// SDK /// Entry point for the SDK. Used to make ad requests. @property(nonatomic, strong) IMAAdsLoader *adsLoader; /// Playhead used by the SDK to track content video progress and insert mid-rolls. @property(nonatomic, strong) IMAAVPlayerContentPlayhead *contentPlayhead; /// Main point of interaction with the SDK. Created by the SDK as the result of an ad request. @property(nonatomic, strong) IMAAdsManager *adsManager;
Быстрый
Импортируйте SDK IMA:
import GoogleInteractiveMediaAdsСоздайте переменные для классов
IMAAdsLoader,IMAAVPlayerContentPlayheadиIMAAdsManagerиспользуемых в приложении: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=" private let adsLoader = IMAAdsLoader() private var adsManager: IMAAdsManager? private lazy var contentPlayhead: IMAAVPlayerContentPlayhead = { IMAAVPlayerContentPlayhead(avPlayer: contentPlayer) }()
5. Реализовать отслеживание положения ползунка воспроизведения контента и наблюдатель конца потока.
Для воспроизведения рекламных вставок в середине видео SDK IMA необходимо отслеживать текущее положение видеоконтента. Для этого создайте класс, реализующий интерфейс IMAContentPlayhead . Если вы используете AVPlayer , как показано в этом примере, SDK предоставляет класс IMAAVPlayerContentPlayhead , который делает это за вас. Если вы не используете AVPlayer , вам необходимо реализовать IMAContentPlayhead в собственном классе.
Также необходимо сообщить SDK о завершении воспроизведения контента, чтобы он мог отображать рекламные вставки после него. Для этого вызовите метод contentComplete в IMAAdsLoader, используя AVPlayerItemDidPlayToEndTimeNotification .
Objective-C
Создайте экземпляр IMAAVPlayerContentPlayhead в настройках проигрывателя:
// Set up our content playhead and contentComplete callback.
self.contentPlayhead = [[IMAAVPlayerContentPlayhead alloc] initWithAVPlayer:self.contentPlayer];
[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(contentDidFinishPlaying:)
name:AVPlayerItemDidPlayToEndTimeNotification
object:self.contentPlayer.currentItem];
Создайте метод contentDidFinishPlaying() , который будет вызывать IMAAdsLoader.contentComplete() после завершения воспроизведения контента:
- (void)contentDidFinishPlaying:(NSNotification *)notification {
// Make sure we don't call contentComplete as a result of an ad completing.
if (notification.object == self.contentPlayer.currentItem) {
[self.adsLoader contentComplete];
}
}
Быстрый
Создайте обработчик завершения контента в настройках проигрывателя:
NotificationCenter.default.addObserver(
self,
selector: #selector(contentDidFinishPlaying(_:)),
name: .AVPlayerItemDidPlayToEndTime,
object: contentPlayer.currentItem)
Создайте метод contentDidFinishPlaying() , который будет вызывать IMAAdsLoader.contentComplete() после завершения воспроизведения контента:
@objc func contentDidFinishPlaying(_ notification: Notification) {
// Make sure we don't call contentComplete as a result of an ad completing.
if notification.object as? AVPlayerItem == contentPlayer.currentItem {
adsLoader.contentComplete()
}
}
6. Инициализируйте загрузчик рекламы и отправьте запрос на показ рекламы.
Для запроса набора объявлений необходимо создать экземпляр IMAAdsLoader . Этот загрузчик обрабатывает объекты IMAAdsRequest , связанные с указанным URL-адресом рекламного тега.
Рекомендуется использовать только один экземпляр IMAAdsLoader на протяжении всего жизненного цикла приложения. Для отправки дополнительных запросов на показ создайте новый объект IMAAdsRequest , но используйте тот же самый IMAAdsLoader . Дополнительную информацию см. в разделе часто задаваемых вопросов (FAQ) по IMA SDK .
Objective-C
- (void)setupAdsLoader {
self.adsLoader = [[IMAAdsLoader alloc] initWithSettings:nil];
self.adsLoader.delegate = self;
}
- (void)requestAds {
// Create an ad display container for ad rendering.
IMAAdDisplayContainer *adDisplayContainer =
[[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView
viewController:self
companionSlots:nil];
// Create an ad request with our ad tag, display container, and optional user context.
IMAAdsRequest *request = [[IMAAdsRequest alloc] initWithAdTagUrl:kTestAppAdTagUrl
adDisplayContainer:adDisplayContainer
contentPlayhead:self.contentPlayhead
userContext:nil];
[self.adsLoader requestAdsWithRequest:request];
}
Быстрый
private func requestAds() {
// Create ad display container for ad rendering.
let adDisplayContainer = IMAAdDisplayContainer(
adContainer: videoView, viewController: self, companionSlots: nil)
// Create an ad request with our ad tag, display container, and optional user context.
let request = IMAAdsRequest(
adTagUrl: PlayerContainerViewController.adTagURLString,
adDisplayContainer: adDisplayContainer,
contentPlayhead: contentPlayhead,
userContext: nil)
adsLoader.requestAds(with: request)
}
7. Настройте делегат для загрузки рекламы.
При успешной загрузке IMAAdsLoader вызывает метод adsLoadedWithData назначенного ему делегата, передавая ему экземпляр IMAAdsManager . Затем можно инициализировать менеджер рекламы, который загружает отдельные объявления в соответствии с ответом на URL-адрес рекламного тега.
Кроме того, обязательно обрабатывайте любые ошибки, которые могут возникнуть в процессе загрузки. Если реклама не загружается, убедитесь, что воспроизведение медиафайлов продолжается без рекламы, чтобы не мешать пользователю.
Objective-C
- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
// Grab the instance of the IMAAdsManager and set ourselves as the delegate.
self.adsManager = adsLoadedData.adsManager;
self.adsManager.delegate = self;
// Create ads rendering settings to tell the SDK to use the in-app browser.
IMAAdsRenderingSettings *adsRenderingSettings = [[IMAAdsRenderingSettings alloc] init];
adsRenderingSettings.linkOpenerPresentingController = self;
// Initialize the ads manager.
[self.adsManager initializeWithAdsRenderingSettings:adsRenderingSettings];
}
- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
// Something went wrong loading ads. Log the error and play the content.
NSLog(@"Error loading ads: %@", adErrorData.adError.message);
[self.contentPlayer 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
// Create ads rendering settings and tell the SDK to use the in-app browser.
let adsRenderingSettings = IMAAdsRenderingSettings()
adsRenderingSettings.linkOpenerPresentingController = self
// Initialize the ads manager.
adsManager?.initialize(with: adsRenderingSettings)
}
func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
if let message = adErrorData.adError.message {
print("Error loading ads: \(message)")
}
contentPlayer.play()
}
8. Настройте делегата для управления рекламными объявлениями.
Наконец, для управления событиями и изменениями состояния менеджеру рекламы необходим собственный делегат. IMAAdManagerDelegate имеет методы для обработки событий и ошибок, связанных с рекламой, а также методы для запуска воспроизведения и паузы видеоконтента.
Начать воспроизведение
Для начала воспроизведения контента и рекламы дождитесь события LOADED . Более подробную информацию см. в didReceiveAdEvent .
Objective-C
- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
// When the SDK notified us that ads have been loaded, play them.
if (event.type == kIMAAdEvent_LOADED) {
[adsManager start];
}
}
Быстрый
func adsManager(_ adsManager: IMAAdsManager, didReceive event: IMAAdEvent) {
// When the SDK notifies us the ads have been loaded, play them.
if event.type == IMAAdEventType.LOADED {
adsManager.start()
}
}
Обработка ошибок
Добавьте также обработчик ошибок, связанных с рекламой. Если возникнет ошибка, как и на предыдущем шаге, возобновите воспроизведение контента.
Objective-C
- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdError:(IMAAdError *)error {
// Something went wrong with the ads manager after ads were loaded. Log the error and play the
// content.
NSLog(@"AdsManager error: %@", error.message);
[self.contentPlayer play];
}
Быстрый
func adsManager(_ adsManager: IMAAdsManager, didReceive error: IMAAdError) {
// Something went wrong with the ads manager after ads were loaded.
// Log the error and play the content.
if let message = error.message {
print("AdsManager error: \(message)")
}
contentPlayer.play()
}
Отслеживайте события воспроизведения и паузы.
Последние два метода делегата необходимо реализовать для запуска событий воспроизведения и паузы видеоконтента по запросу IMA SDK. Запуск паузы и воспроизведения по запросу предотвращает пропуск пользователем фрагментов видеоконтента во время показа рекламы.
Objective-C
- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
// The SDK is going to play ads, so pause the content.
[self.contentPlayer pause];
}
- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
// The SDK is done playing ads (at least for now), so resume the content.
[self.contentPlayer play];
}
Быстрый
func adsManagerDidRequestContentPause(_ adsManager: IMAAdsManager) {
// The SDK is going to play ads, so pause the content.
contentPlayer.pause()
}
func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager) {
// The SDK is done playing ads (at least for now), so resume the content.
contentPlayer.play()
}
Вот и всё! Теперь вы запрашиваете и отображаете рекламу с помощью IMA SDK. Чтобы узнать о дополнительных возможностях SDK, ознакомьтесь с другими руководствами или примерами на GitHub .
Следующие шаги
Для максимизации дохода от рекламы на платформе iOS запросите разрешение на прозрачность и отслеживание приложения (App Transparency and Tracking) для использования IDFA .