Configurar o SDK do IMA

Selecione a plataforma: HTML5 Android iOS tvOS

Os SDKs do IMA facilitam a integração de anúncios multimídia aos seus sites e apps. Os SDKs do IMA podem solicitar anúncios de qualquer servidor de anúncios compatível com VAST e gerenciar a reprodução de anúncios nos seus apps. Com os SDKs do lado do cliente do IMA, você mantém o controle da reprodução de vídeo de conteúdo, enquanto o SDK processa a reprodução de anúncios. Os anúncios são veiculados em um player de vídeo separado, posicionado acima do player de vídeo de conteúdo do app.

Este guia demonstra como integrar o SDK do IMA a um app de player de vídeo. Para conferir ou acompanhar um exemplo de integração concluída, faça o download do BasicExample no GitHub.

Observação:para informações sobre a integração com outras plataformas ou sobre o uso dos SDKs do DAI do IMA, consulte SDKs do Interactive Media Ads.

Visão geral do lado do cliente da IMA

A implementação do IMA do lado do cliente envolve quatro componentes principais do SDK, que este guia demonstra:

• IMAAdDisplayContainer: um objeto contêiner que especifica onde a IMA renderiza elementos da interface do anúncio e mede a visibilidade, incluindo o Active View e a Medição aberta.
• IMAAdsLoader: um objeto que solicita anúncios e processa eventos de respostas de solicitação de anúncios. Você só deve instanciar um carregador de anúncios, que pode ser reutilizado durante toda a vida útil do aplicativo.
• IMAAdsRequest: um objeto que define uma solicitação de anúncio. As solicitações de anúncios especificam o URL da tag de anúncio VAST e outros parâmetros, como dimensões do anúncio.
• IMAAdsManager: um objeto que contém a resposta à solicitação de anúncios, controla a reprodução de anúncios e detecta eventos de anúncio acionados pelo SDK.

Pré-requisitos

Antes de começar, os seguintes itens são necessários:

• Xcode 13 ou mais recente
• Método para instalar o SDK do IMA:
  • Gerenciador de pacotes do Swift (preferencial)
  • CocoaPods
  • Uma cópia baixada do SDK do IMA para iOS

1. Criar um projeto do Xcode

No Xcode, crie um projeto iOS usando Objective-C ou Swift. Use BasicExample como o nome do projeto.

2. Adicionar o SDK do IMA ao projeto do Xcode

Para instalar o SDK do IMA, escolha um método preferido.

Recomendado: instale o SDK usando o Swift Package Manager

O SDK do Interactive Media Ads é compatível com o Gerenciador de pacotes do Swift a partir da versão 3.18.4. Para importar o pacote Swift, siga estas etapas:

Observação: se você estiver migrando de um projeto baseado em CocoaPods, execute pod deintegrate para remover o CocoaPods do seu projeto do Xcode. Depois disso, o arquivo .xcworkspace gerado pelo CocoaPods pode ser excluído com segurança. Se você estiver adicionando o SDK Interactive Media Ads a um projeto pela primeira vez, ignore esta etapa.

1. No Xcode, instale o pacote Swift do SDK do IMA acessando File > Add Package Dependencies….

2. No comando, pesquise o repositório do GitHub do pacote Swift do SDK do IMA para iOS: swift-package-manager-google-interactive-media-ads-ios.

3. Selecione a versão do pacote Swift do SDK do IMA que você quer usar. Para novos projetos, recomendamos usar a opção Up to Next Major Version.

Depois disso, o Xcode resolve as dependências do pacote e faz o download delas em segundo plano. Para mais detalhes sobre como adicionar dependências de pacotes, consulte o artigo da Apple.

Instalar o SDK usando o CocoaPods

Atenção: o CocoaPods está se tornando somente leitura. Para instalar o SDK do IMA, recomendamos que você siga Recomendado: instale o SDK do IMA usando o Swift Package Manager. Para mais detalhes, consulte Plano somente leitura do CocoaPods Trunk.

O CocoaPods é um gerenciador de dependências para projetos do Xcode e é o método recomendado para instalar o SDK do IMA. Para mais informações sobre como instalar ou usar o CocoaPods, consulte a documentação do CocoaPods. Depois de instalar o CocoaPods, use as instruções a seguir para instalar o SDK do IMA:

1. No mesmo diretório do arquivo BasicExample.xcodeproj, crie um arquivo de texto chamado Podfile e adicione a seguinte configuração:

   Objective-C

   platform :ios, '15'
   
   target "BasicExample" do
     pod 'GoogleAds-IMA-iOS-SDK', '~> 3.28.10'
   end
   Podfile
   

   Swift

   platform :ios, '15'
   
   target "BasicExample" do
     pod 'GoogleAds-IMA-iOS-SDK', '~> 3.28.10'
   end
   Podfile
   

2. No diretório que contém o Podfile, execute pod install --repo-update.

3. Para verificar se a instalação foi bem-sucedida, abra o arquivo BasicExample.xcworkspace e confirme se ele contém dois projetos: BasicExample e Pods (as dependências que o CocoaPods instalou).

Fazer o download e instalar o SDK manualmente

Se você não quiser usar o Gerenciador de pacotes do Swift, faça o download e adicione manualmente o SDK da IMA ao seu projeto.

Mostrar/ocultar instruções

1. Na página de download do IMA para iOS, baixe e extraia a versão mais recente do SDK do IMA para iOS.
2. Abra BasicExample.xcodeproj.
3. No painel à esquerda, clique no nome do projeto.
   
4. No painel central, clique em Build Phases.
   
5. Expanda a seção Link Binary With Libraries.
6. Na parte de baixo da lista de bibliotecas, clique no ícone de adição [+].
7. Clique em Adicionar outro.
8. No diretório em que você extraiu o SDK baixado, selecione GoogleInteractiveMediaAds.framework e clique em Abrir.
9. Na parte de baixo da lista de bibliotecas, clique no ícone de adição [+] novamente.
10. Na coluna Status, verifique se GoogleInteractiveMediaAds.framework está definido como Required.
11. Inclua a flag do vinculador -ObjC nas configurações de build. Para mais informações, consulte Apple QA1490.

3. Criar um player de vídeo

Primeiro, implemente um player de vídeo. Inicialmente, esse player não usa o SDK do IMA e não contém nenhum método para acionar a reprodução.

Objective-C

Importe as dependências do player:

#import "ViewController.h"

@import AVFoundation;
ViewController.m

Configure as variáveis do player:

@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;
ViewController.m

Inicie o player de vídeo quando a visualização for carregada:

@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;
}
ViewController.m

Swift

Importe as dependências do player:

import AVFoundation
PlayerContainerViewController.swift

Configure as variáveis do player:

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)
  }()
PlayerContainerViewController.swift

Inicie o player de vídeo quando a visualização for carregada:

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()
}
PlayerContainerViewController.swift

4. Importar o SDK do IMA

Para importar o SDK do IMA, faça o seguinte:

Objective-C

1. Importe o SDK do IMA:

   @import GoogleInteractiveMediaAds;
   ViewController.m
   

2. Crie variáveis para as classes IMAAdsLoader, IMAAVPlayerContentPlayhead e IMAAdsManager usadas no app:

   // 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;
   ViewController.m
   

Swift

1. Importe o SDK do IMA:

   import GoogleInteractiveMediaAds
   PlayerContainerViewController.swift
   

2. Crie variáveis para as classes IMAAdsLoader, IMAAVPlayerContentPlayhead e IMAAdsManager usadas no app:

   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)
   }()
   PlayerContainerViewController.swift
   

5. Implementar o rastreador de cabeça de reprodução de conteúdo e o observador de fim de stream

Para veicular anúncios intermediários, o SDK do IMA precisa rastrear a posição atual do conteúdo de vídeo. Para fazer isso, crie uma classe que implemente IMAContentPlayhead. Se você estiver usando um AVPlayer, como mostrado neste exemplo, o SDK vai fornecer a classe IMAAVPlayerContentPlayhead, que faz isso por você. Se você não estiver usando AVPlayer, implemente IMAContentPlayhead em uma classe própria.

Você também precisa informar ao SDK quando o conteúdo terminar de ser reproduzido para que ele possa mostrar anúncios pós-vídeo. Para fazer isso, chame o método contentComplete no IMAAdsLoader usando AVPlayerItemDidPlayToEndTimeNotification.

Objective-C

Crie a instância IMAAVPlayerContentPlayhead na configuração do player:

// 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];
ViewController.m

Crie o método contentDidFinishPlaying() para chamar IMAAdsLoader.contentComplete() quando o conteúdo terminar de ser reproduzido:

- (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];
  }
}
ViewController.m

Swift

Crie o observador de fim de conteúdo na configuração do player:

NotificationCenter.default.addObserver(
  self,
  selector: #selector(contentDidFinishPlaying(_:)),
  name: .AVPlayerItemDidPlayToEndTime,
  object: contentPlayer.currentItem)
PlayerContainerViewController.swift

Crie o método contentDidFinishPlaying() para chamar IMAAdsLoader.contentComplete() quando o conteúdo terminar de ser reproduzido:

@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()
  }
}
PlayerContainerViewController.swift

6. Inicializar o carregador de anúncios e fazer uma solicitação de anúncios

Para solicitar um conjunto de anúncios, crie uma instância de IMAAdsLoader. Esse carregador processa objetos IMAAdsRequest associados a um URL de tag de anúncio especificado.

Como prática recomendada, mantenha apenas uma instância de IMAAdsLoader durante todo o ciclo de vida do app. Para fazer outras solicitações de anúncio, crie um novo objeto IMAAdsRequest, mas reutilize o mesmo IMAAdsLoader. Para mais informações, consulte as Perguntas frequentes sobre o SDK do IMA.

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];
}
ViewController.m

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)
}
PlayerContainerViewController.swift

7. Configurar um delegado do carregador de anúncios

Em um evento de carregamento bem-sucedido, o IMAAdsLoader chama o método adsLoadedWithData do delegado atribuído, transmitindo uma instância de IMAAdsManager. Em seguida, você pode inicializar o gerenciador de anúncios, que carrega os anúncios individuais, conforme definido pela resposta ao URL da tag de anúncio.

Além disso, processe os erros que possam ocorrer durante o processo de carregamento. Se os anúncios não carregarem, verifique se a reprodução de mídia continua sem anúncios para não interferir na experiência do usuário.

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];
}
ViewController.m

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()
}
PlayerContainerViewController.swift

8. Configurar um delegado do gerenciador de anúncios

Por fim, para gerenciar eventos e mudanças de estado, o gerenciador de anúncios precisa de um delegado próprio. O IMAAdManagerDelegate tem métodos para processar eventos e erros de anúncios, além de métodos para acionar a reprodução e a pausa no conteúdo de vídeo.

Iniciar reprodução

Aguarde o evento LOADED para iniciar a reprodução de conteúdo e anúncios. Para mais detalhes, consulte 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];
  }
}
ViewController.m

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()
  }
}
PlayerContainerViewController.swift

Solucionar erros

Adicione também um handler para erros de anúncio. Se ocorrer um erro, como na etapa anterior, retome a reprodução do conteúdo.

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];
}
ViewController.m

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()
}
PlayerContainerViewController.swift

Detectar eventos de tocar e pausar

Os dois últimos métodos delegados que você precisa implementar acionam eventos de reprodução e pausa no conteúdo de vídeo subjacente quando o SDK do IMA os solicita. Acionar a pausa e a reprodução quando solicitado evita que o usuário perca partes do conteúdo de vídeo quando os anúncios são exibidos.

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];
}
ViewController.m

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()
}
PlayerContainerViewController.swift

Pronto! Agora você está solicitando e mostrando anúncios com o SDK do IMA. Para saber mais sobre outros recursos do SDK, consulte os outros guias ou os exemplos no GitHub.

Próximas etapas

Para maximizar a receita de publicidade na plataforma iOS, solicite permissão de transparência e rastreamento de apps para usar o IDFA.