Пакеты IMA SDK упрощают интеграцию мультимедийной рекламы в ваши веб-сайты и приложения. Пакеты IMA SDK могут запрашивать рекламу с любого рекламного сервера , совместимого с VAST, и управлять её воспроизведением в ваших приложениях. Клиентские пакеты IMA SDK позволяют вам контролировать воспроизведение видеоконтента, в то время как SDK управляет воспроизведением рекламы. Реклама воспроизводится в отдельном видеоплеере, расположенном поверх видеоплеера приложения.
В этом руководстве показано, как интегрировать IMA SDK в приложение видеоплеера. Если вы хотите просмотреть готовый пример интеграции или следовать ему, скачайте BasicExample с GitHub.
Обзор клиентской части IMA
Реализация IMA на стороне клиента включает четыре основных компонента SDK, которые продемонстрированы в этом руководстве:
-
IMAAdDisplayContainer
: объект-контейнер, который указывает, где IMA отображает элементы пользовательского интерфейса рекламы и измеряет видимость, включая Active View и Open Measurement . -
IMAAdsLoader
: объект, который запрашивает рекламу и обрабатывает события, возникающие при ответах на запросы рекламы. Следует создать только один экземпляр загрузчика рекламы, который можно использовать повторно на протяжении всего жизненного цикла приложения. -
IMAAdsRequest
: объект, определяющий запрос на рекламу. Запросы на рекламу содержат URL-адрес тега VAST, а также дополнительные параметры, такие как размеры объявления. -
IMAAdsManager
: объект, который содержит ответ на запрос рекламы, управляет воспроизведением рекламы и прослушивает события рекламы, запускаемые SDK.
Предпосылки
Прежде чем начать, вам понадобится следующее:
- Xcode 13 или более поздняя версия
- CocoaPods (предпочтительно), Swift Package Manager или загруженная копия IMA SDK для iOS
1. Создайте новый проект Xcode.
В Xcode создайте новый iOS-проект на Objective-C или Swift. Используйте BasicExample в качестве имени проекта.
2. Добавьте IMA SDK в проект Xcode.
Установить SDK с помощью CocoaPods (рекомендуется)
CocoaPods — это менеджер зависимостей для проектов Xcode, рекомендуемый метод установки IMA SDK. Подробнее об установке и использовании CocoaPods см. в документации CocoaPods . После установки CocoaPods следуйте следующим инструкциям для установки IMA SDK:
В том же каталоге, где находится файл BasicExample.xcodeproj , создайте текстовый файл с именем Podfile и добавьте следующую конфигурацию:
Objective-C
source 'https://github.com/CocoaPods/Specs.git' platform :ios, '12' target "BasicExample" do pod 'GoogleAds-IMA-iOS-SDK', '~> 3.26.1' end
Быстрый
source 'https://github.com/CocoaPods/Specs.git' platform :ios, '12' target "BasicExample" do pod 'GoogleAds-IMA-iOS-SDK', '~> 3.26.1' end
Из каталога, содержащего Podfile, запустите
pod install --repo-update
.Убедитесь, что установка прошла успешно, открыв файл BasicExample.xcworkspace и убедившись, что он содержит два проекта: BasicExample и Pods (зависимости, установленные CocoaPods).
Установите SDK с помощью Swift Package Manager
Interactive Media Ads SDK поддерживает Swift Package Manager, начиная с версии 3.18.4. Чтобы импортировать пакет Swift, выполните следующие действия:
В Xcode установите пакет IMA SDK Swift, перейдя в Файл > Добавить зависимости пакета... .
В командной строке найдите репозиторий GitHub IMA iOS SDK Swift Package:
swift-package-manager-google-interactive-media-ads-ios
.Выберите нужную версию пакета IMA SDK Swift. Для новых проектов мы рекомендуем использовать версию Up to Next Major Version .
После завершения Xcode определит зависимости пакетов и загрузит их в фоновом режиме. Подробнее о добавлении зависимостей пакетов см. в статье Apple .
Загрузите и установите SDK вручную
Если вы не хотите использовать Swift Package Manager или CocoaPods, вы можете загрузить IMA SDK и вручную добавить его в свой проект.
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. Импортируйте IMA SDK
Чтобы импортировать IMA SDK, выполните следующие действия:
Objective-C
Импортируйте IMA SDK:
@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;
Быстрый
Импортируйте IMA SDK:
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. Реализуйте отслеживание точки воспроизведения контента и наблюдение за окончанием трансляции.
Для воспроизведения рекламы в середине ролика IMA SDK необходимо отслеживать текущее положение видеоконтента. Для этого создайте класс, реализующий 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
. Подробнее см. в разделе часто задаваемых вопросов по 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, запросите разрешение на прозрачность и отслеживание приложений для использования IDFA .