Как настроить 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

Начиная с версии 3.18.4, Interactive Media Ads SDK поддерживает Swift Package Manager. Чтобы импортировать пакет 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. Для новых проектов мы рекомендуем использовать вариант До следующей основной версии.

Когда все будет готово, 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.