Как настроить IMA SDK

Выберите платформу: HTML5 Android iOS tvOS

IMA SDK позволяет легко интегрировать мультимедийные объявления на сайты и в приложения. IMA SDK может запрашивать объявления с любого сервера, совместимого с VAST, и управлять воспроизведением рекламы в ваших приложениях. Клиентские IMA SDK позволяют управлять воспроизведением видеоконтента, а воспроизведение рекламы берет на себя SDK. Объявления воспроизводятся в отдельном видеопроигрывателе, который расположен поверх проигрывателя видеоконтента в приложении.

В этом руководстве рассказывается, как интегрировать IMA SDK в приложение с видеопроигрывателем. Чтобы посмотреть или повторить готовую интеграцию, скачайте BasicExample с GitHub.

Общие сведения о IMA на стороне клиента

В этом руководстве рассматриваются четыре основных компонента SDK, которые используются при реализации IMA на стороне клиента:

  • IMAAdDisplayContainer – объект-контейнер, который указывает, где IMA отображает элементы интерфейса объявления и измеряет видимость, включая Active View и Open Measurement.
  • IMAAdsLoader – объект, который запрашивает объявления и обрабатывает события, связанные с ответами на запросы объявлений. Вам нужно создать только один экземпляр загрузчика объявлений, который можно использовать в течение всего жизненного цикла приложения.
  • IMAAdsRequest: Объект, определяющий запрос объявления. В запросах объявлений указывается URL тега объявления VAST, а также дополнительные параметры, например размеры объявления.
  • IMAAdsManager: Объект, который содержит ответ на запрос объявления, управляет воспроизведением объявления и отслеживает события, связанные с объявлением и инициированные SDK.

Требования

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

  • Xcode 13 или более поздней версии;
  • Способ установки IMA SDK:

1. Создайте проект Xcode

В Xcode создайте новый проект iOS на Objective-C или Swift. В качестве названия проекта укажите BasicExample.

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

Выберите способ установки IMA SDK.

Рекомендуется: установите SDK с помощью Swift Package Manager

Interactive Media Ads SDK поддерживает Swift Package Manager, начиная с версии 3.18.4. Чтобы импортировать пакет Swift, выполните следующие действия:

  1. В Xcode установите пакет IMA SDK Swift. Для этого выберите File (Файл) > Add Package Dependencies (Добавить зависимости пакетов).

  2. В окне поиска введите адрес репозитория IMA iOS SDK Swift Package на GitHub: swift-package-manager-google-interactive-media-ads-ios.

  3. Выберите версию пакета IMA SDK Swift, которую вы хотите использовать. Для новых проектов рекомендуется использовать Up to Next Major Version.

Когда все будет готово, Xcode распознает зависимости пакета и скачает их в фоновом режиме. Подробнее о том, как добавлять зависимости пакетов, читайте в статье Apple.

Как скачать и установить SDK вручную

Если вы не хотите использовать Swift Package Manager, скачайте 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;
}

Swift

Импортируйте зависимости проигрывателя:

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

  1. Импортируйте IMA SDK:

    @import GoogleInteractiveMediaAds;
    
  2. Создайте переменные для классов 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;
    

Swift

  1. Импортируйте IMA SDK:

    import GoogleInteractiveMediaAds
    
    
  2. Создайте переменные для классов 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];
  }
}

Swift

Создайте наблюдатель за окончанием контента в настройках проигрывателя:

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

Swift

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

Swift

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

Swift

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

Swift

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

Swift

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 в соответствии с фреймворком App Tracking Transparency.