Começar a usar o SDK de DAI do IMA

Com os SDKs do IMA, é fácil integrar anúncios multimídia aos seus sites e apps. Os SDKs do IMA podem solicitar anúncios de qualquer servidor compatível com VAST e gerenciar a reprodução de anúncios nos seus apps. Com os SDKs de DAI do IMA, os apps fazem uma solicitação de streaming para anúncio e conteúdo de vídeo, seja VOD ou conteúdo ao vivo. Em seguida, o SDK retorna um stream de vídeo combinado para que você não precise gerenciar a alternância entre anúncios e vídeos de conteúdo no seu app.

Selecione a solução de DAI do seu interesse

DAI de serviço completo

Este guia demonstra como integrar o SDK de DAI do IMA a um app de player de vídeo simples. Se você quiser visualizar ou acompanhar um exemplo de integração completo, faça o download do BasicExample no GitHub.

Visão geral da DAI do IMA

A implementação da DAI do IMA envolve quatro componentes principais do SDK, conforme demonstrado neste guia:

  • IMAAdDisplayContainer: um objeto contêiner que fica acima do elemento de reprodução de vídeo e hospeda os elementos da interface do anúncio.
  • IMAAdsLoader: um objeto que solicita streams e processa eventos acionados por objetos de resposta à solicitação de stream. Instancie apenas um carregador de anúncios, que poderá ser reutilizado durante toda a vida útil do aplicativo.
  • IMAStreamRequest: um IMAVODStreamRequest ou um IMALiveStreamRequest: um objeto que define uma solicitação de stream. As solicitações de stream podem ser para vídeo on demand ou transmissões ao vivo. As solicitações especificam um ID de conteúdo, bem como uma chave de API ou um token de autenticação e outros parâmetros.
  • IMAStreamManager: um objeto que processa fluxos de inserção de anúncios dinâmicos e interações com o back-end da DAI. Ele também processa pings de rastreamento e encaminha os eventos de anúncio e stream para o editor.

Pré-requisitos

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

Criar um novo projeto do Xcode

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

Adicionar o SDK de DAI do IMA ao projeto do Xcode

Use um destes três métodos para instalar o SDK de DAI do IMA.

Instalar o SDK usando CocoaPods (preferencial)

O CocoaPods é um gerenciador de dependências para projetos do Xcode e é o método recomendado para instalar o SDK de DAI 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 de DAI do IMA:

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

    source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '14'
target "BasicExample" do
  pod 'GoogleAds-IMA-iOS-SDK', '~> 3.23.0'
end

  2. No diretório que contém o Podfile, execute o seguinte:

    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 instaladas pelo CocoaPods).

Instalar o SDK usando o Gerenciador de pacotes do Swift

O SDK do Interactive Media Ads é compatível com o Gerenciador de pacotes do Swift a partir da versão 3.18.4. Siga as etapas abaixo para importar o pacote Swift.

  1. No Xcode, instale o pacote Swift do SDK de DAI do IMA acessando Arquivo > Adicionar pacotes.

  2. No prompt exibido, pesquise o repositório GitHub do pacote Swift do SDK de DAI do IMA:

    https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios

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

Quando terminar, 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 pacote, consulte o artigo da Apple.

Fazer o download e instalar o SDK manualmente

Se você não quiser usar o Swift Package Manager ou o CocoaPods, faça o download do SDK de DAI do IMA e o adicione manualmente ao seu projeto.

Criar um player de vídeo simples

Primeiro, implemente um player de vídeo básico. Inicialmente, esse player não usa o SDK de DAI do IMA nem contém métodos para acionar a reprodução.

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>

@interface ViewController ()
@property(nonatomic) AVPlayerViewController *playerViewController;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.view.backgroundColor = [UIColor blackColor];

  // Create a stream video player.
  AVPlayer *player = [[AVPlayer alloc] init];
  self.playerViewController = [[AVPlayerViewController alloc] init];
  self.playerViewController.player = player;

  // Attach the video player to the view hierarchy.
  [self addChildViewController:self.playerViewController];
  self.playerViewController.view.frame = self.view.bounds;
  [self.view addSubview:self.playerViewController.view];
  [self.playerViewController didMoveToParentViewController:self];
}

@end

Importar o SDK e adicionar stubs para interação com o IMA

Depois de adicionar o SDK de DAI do IMA ao projeto, importe o SDK e adicione stubs para os principais pontos de interação do IMA.

ViewController.m

#import "ViewController.h"

#import <AVKit/AVKit.h>
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

@interface ViewController ()
@property(nonatomic) IMAAdsLoader *adsLoader;
@property(nonatomic) UIView *adContainerView;
@property(nonatomic) IMAStreamManager *streamManager;
@property(nonatomic) AVPlayerViewController *playerViewController;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  self.view.backgroundColor = [UIColor blackColor];

  [self setupAdsLoader];

  // Create a stream video player.
  AVPlayer *player = [[AVPlayer alloc] init];
  self.playerViewController = [[AVPlayerViewController alloc] init];
  self.playerViewController.player = player;

  // Attach the video player to the view hierarchy.
  [self addChildViewController:self.playerViewController];
  self.playerViewController.view.frame = self.view.bounds;
  [self.view addSubview:self.playerViewController.view];
  [self.playerViewController didMoveToParentViewController:self];

  [self attachAdContainer];
}

- (void)viewDidAppear:(BOOL)animated {
  [super viewDidAppear:animated];
  [self requestStream];
}

- (void)setupAdsLoader {}

- (void)attachAdContainer {}

- (void)requestStream {}

@end

Implementar o IMAAdsLoader

Em seguida, instancie o IMAAdsLoader e anexe a visualização do contêiner de anúncios à hierarquia de visualização.

ViewController.m

- (void)setupAdsLoader {
  self.adsLoader = [[IMAAdsLoader alloc] init];
  self.adsLoader.delegate = self;
}

- (void)attachAdContainer {
  self.adContainerView = [[UIView alloc] init];
  [self.view addSubview:self.adContainerView];
  self.adContainerView.frame = self.view.bounds;
}

Fazer uma solicitação de stream

Crie algumas constantes para armazenar as informações do stream e implemente a função de solicitação de stream para fazer a solicitação.

ViewController.m

#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
static NSString *const kVideoID = @"tears-of-steel";

@interface ViewController ()
...

- (void)requestStream {
  IMAAVPlayerVideoDisplay *videoDisplay =
      [[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.playerViewController.player];
  IMAAdDisplayContainer *adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.adContainerView];
  IMALiveStreamRequest *request = [[IMALiveStreamRequest alloc] initWithAssetKey:kAssetKey
                                                              adDisplayContainer:adDisplayContainer
                                                                    videoDisplay:videoDisplay];
  // VOD request. Comment out the IMALiveStreamRequest above and uncomment this IMAVODStreamRequest
  // to switch from a livestream to a VOD stream.
  // IMAVODStreamRequest *request =
  //     [[IMAVODStreamRequest alloc] initWithContentSourceId:kContentSourceID
  //                                                  videoId:kVideoID
  //                                       adDisplayContainer:adDisplayContainer
  //                                             videoDisplay:videoDisplay];
  [self.adsLoader requestStreamWithRequest:request];
}

Processar eventos de stream

Os eventos IMAAdsLoader e IMAStreamManager disparam eventos que são usados para lidar com inicialização, erros e mudanças no estado do stream. Esses eventos são disparados nos protocolos IMAAdsLoaderDelegate e IMAStreamManagerDelegate. Detecte um evento carregado de anúncio e inicialize o stream. Se um anúncio não for carregado, reproduza um fluxo de backup.

ViewController.m

static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2548831";
static NSString *const kVideoID = @"tears-of-steel";
static NSString *const kBackupStreamURLString =
    @"https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8";

@interface ViewController () <IMAAdsLoaderDelegate, IMAStreamManagerDelegate>

...
  [self.adsLoader requestStreamWithRequest:request];
}

- (void)playBackupStream {
  NSURL *backupStreamURL = [NSURL URLWithString:kBackupStreamURLString];
  AVPlayerItem *backupStreamItem = [AVPlayerItem playerItemWithURL:backupStreamURL];
  [self.playerViewController.player replaceCurrentItemWithPlayerItem:backupStreamItem];
  [self.playerViewController.player play];
}

#pragma mark - IMAAdsLoaderDelegate

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  // Initialize and listen to stream manager's events.
  self.streamManager = adsLoadedData.streamManager;
  self.streamManager.delegate = self;
  [self.streamManager initializeWithAdsRenderingSettings:nil];
  NSLog(@"Stream created with: %@.", self.streamManager.streamId);
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Fall back to playing the backup stream.
  NSLog(@"Error loading ads: %@", adErrorData.adError.message);
  [self playBackupStream];
}

#pragma mark - IMAStreamManagerDelegate

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {}

- (void)streamManager:(IMAStreamManager *)streamManager
  adDidProgressToTime:(NSTimeInterval)time
           adDuration:(NSTimeInterval)adDuration
           adPosition:(NSInteger)adPosition
             totalAds:(NSInteger)totalAds
      adBreakDuration:(NSTimeInterval)adBreakDuration {}

@end

Processar eventos de geração de registros e erros

Há vários eventos que podem ser processados pelo delegado do gerenciador de streams. No entanto, para implementações básicas, os usos mais importantes são realizar a geração de registros de eventos, evitar ações de busca durante a reprodução de anúncios e lidar com erros.

ViewController.m

#pragma mark - IMAStreamManagerDelegate

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdEvent:(IMAAdEvent *)event {
  NSLog(@"StreamManager event (%@).", event.typeString);
  switch (event.type) {
    case kIMAAdEvent_STARTED: {
      // Log extended data.
      NSString *extendedAdPodInfo = [[NSString alloc]
          initWithFormat:@"Showing ad %zd/%zd, bumper: %@, title: %@, description: %@, contentType:"
                         @"%@, pod index: %zd, time offset: %lf, max duration: %lf.",
                         event.ad.adPodInfo.adPosition, event.ad.adPodInfo.totalAds,
                         event.ad.adPodInfo.isBumper ? @"YES" : @"NO", event.ad.adTitle,
                         event.ad.adDescription, event.ad.contentType, event.ad.adPodInfo.podIndex,
                         event.ad.adPodInfo.timeOffset, event.ad.adPodInfo.maxDuration];

      NSLog(@"%@", extendedAdPodInfo);
      break;
    }
    case kIMAAdEvent_AD_BREAK_STARTED: {
      // Prevent user seek through when an ad starts and show the ad controls.
      self.adContainerView.hidden = NO;
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      // Allow user seek through after an ad ends and hide the ad controls.
      self.adContainerView.hidden = YES;
      break;
    }
    default:
      break;
  }
}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
  // Fall back to playing the backup stream.
  NSLog(@"StreamManager error: %@", error.message);
  [self playBackupStream];
}

@end

Pronto! Agora você está solicitando e exibindo anúncios com o SDK de DAI do IMA. Para saber mais sobre recursos avançados do SDK, consulte os outros guias ou os exemplos no GitHub (link em inglês).