Configurar o SDK do IMA para DAI

Selecione a plataforma: HTML5 Android iOS tvOS Cast Roku

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 de anúncios 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 stream para anúncios e vídeos de conteúdo, 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 troca entre o anúncio e o vídeo de conteúdo no app.

Selecione a solução de DAI de seu interesse

DAI de veiculação de conjunto

Este guia aborda a integração do SDK DAI do IMA em um app player de vídeo. Se você quiser conferir ou acompanhar um exemplo de integração concluído, baixe o PodServingExample do 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 abriga os elementos da interface do anúncio.
  • IMAAdsLoader: um objeto que solicita streams e processa eventos acionados por objetos de resposta de solicitação de stream. Você só precisa instanciar um carregador de anúncios, que pode ser reutilizado durante toda a vida útil do aplicativo.
  • IMAStreamRequest – um IMAPodVODStreamRequest ou um IMAPodStreamRequest.
  • IMAStreamManager: um objeto que processa fluxos de inserção de anúncios dinâmicos e interações com o back-end da DAI. O gerenciador de stream também processa pings de rastreamento e encaminha eventos de stream e de anúncio para o publisher.

Além disso, para reproduzir streams de veiculação de pods, implemente um processador de VTP personalizado. Esse gerenciador personalizado da VTP envia o ID do stream ao seu parceiro técnico de vídeo (VTP) junto com outras informações necessárias para retornar um manifesto de stream que contenha conteúdo e anúncios combinados. Seu VTP fornece instruções sobre como implementar o manipulador de VTP personalizado.

Pré-requisitos

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

Você também precisa dos parâmetros para solicitar o stream do SDK do IMA.

Parâmetros de transmissão ao vivo
Código da rede O código de rede da sua conta do Ad Manager 360.
Chave de recurso personalizada A chave de recurso personalizada que identifica seu evento de veiculação de pod no Ad Manager 360. Ele é criado pelo manipulador de manifesto ou pelo parceiro de veiculação de conjunto terceirizado.
Parâmetros de stream de VOD
Código da rede O código de rede da sua conta do Ad Manager 360.

Criar um projeto do Xcode

No Xcode, crie um projeto iOS usando Objective-C chamado "PodServingExample".

Adicionar o SDK do DAI 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 Swift Package Manager a partir da versão 3.18.4. Siga estas etapas para importar o pacote Swift.

  1. No Xcode, instale o pacote Swift do SDK de DAI do IMA: navegue até File > Add Packages.

  2. No comando que aparece, pesquise o repositório do GitHub do pacote Swift do SDK 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 da DAI do IMA que você quer usar. Para novos projetos, use a opção Up to Next Major Version.

Quando terminar, o Xcode vai resolver as dependências do pacote e fazer o download delas em segundo plano. Para mais detalhes sobre como adicionar dependências de pacote, consulte o artigo da Apple.

Baixar e instalar o SDK manualmente

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

Criar um player de vídeo

Implemente um player de vídeo no controlador de visualização principal. Encapsule um player AV em uma visualização da interface. O SDK do IMA usa a visualização da interface para mostrar elementos da interface do anúncio.

Objective-C

#import "ViewController.h"

#import <AVKit/AVKit.h>

/// Content URL.
static NSString *const kBackupContentUrl =
    @"http://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8";

@interface ViewController ()
/// Play button.
@property(nonatomic, weak) IBOutlet UIButton *playButton;

@property(nonatomic, weak) IBOutlet UIView *videoView;
/// Video player.
@property(nonatomic, strong) AVPlayer *videoPlayer;
@end

@implementation ViewController

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

  // Load AVPlayer with the path to your content.
  NSURL *contentURL = [NSURL URLWithString:kBackupContentUrl];
  self.videoPlayer = [AVPlayer playerWithURL:contentURL];

  // Create a player layer for the player.
  AVPlayerLayer *playerLayer = [AVPlayerLayer playerLayerWithPlayer:self.videoPlayer];

  // Size, position, and display the AVPlayer.
  playerLayer.frame = self.videoView.layer.bounds;
  [self.videoView.layer addSublayer:playerLayer];
}

- (IBAction)onPlayButtonTouch:(id)sender {
  [self.videoPlayer play];
  self.playButton.hidden = YES;
}

@end

Swift

// Copyright 2024 Google LLC. All rights reserved.
//
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this
// file except in compliance with the License. You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software distributed under
// the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
// ANY KIND, either express or implied. See the License for the specific language governing
// permissions and limitations under the License.

import AVFoundation
import UIKit

class ViewController: UIViewController {

  /// Content URL.
  static let backupStreamURLString =
    "http://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8"

  /// Play button.
  @IBOutlet private weak var playButton: UIButton!

  @IBOutlet private weak var videoView: UIView!
  /// Video player.
  private var videoPlayer: AVPlayer?

  override func viewDidLoad() {
    super.viewDidLoad()

    playButton.layer.zPosition = CGFloat(MAXFLOAT)

    // Load AVPlayer with path to our content.
    // note: this unwrap is safe because the URL is a constant string.
    let contentURL = URL(string: ViewController.backupStreamURLString)!
    videoPlayer = AVPlayer(url: contentURL)

    // Create a player layer for the player.
    let playerLayer = AVPlayerLayer(player: videoPlayer)

    // Size, position, and display the AVPlayer.
    playerLayer.frame = videoView.layer.bounds
    videoView.layer.addSublayer(playerLayer)
  }

  @IBAction func onPlayButtonTouch(_ sender: Any) {
    videoPlayer?.play()
    playButton.isHidden = true
  }
}

Inicializar o carregador de anúncios

Importe o SDK do IMA para seu controlador de visualização e adote os protocolos IMAAdsLoaderDelegate e IMAStreamManagerDelegate para processar eventos do carregador de anúncios e do gerenciador de streams.

Adicione estas propriedades particulares para armazenar os principais componentes do SDK do IMA:

  • IMAAdsLoader
    • Gerencia solicitações de stream durante todo o ciclo de vida do app.
  • IMAAdDisplayContainer
    • Lida com a inserção e o gerenciamento de elementos da interface do usuário de anúncios.
  • IMAAVPlayerVideoDisplay: se comunica entre o SDK do IMA e seu player de mídia e processa metadados com carimbo de data/hora.
  • IMAStreamManager: gerencia a reprodução de stream e aciona eventos relacionados a anúncios.

Inicialize o carregador de anúncios, o contêiner de exibição de anúncios e a exibição de vídeo depois que a visualização for carregada.

Objective-C

@import GoogleInteractiveMediaAds;

// ...

@interface ViewController () <IMAAdsLoaderDelegate, IMAStreamManagerDelegate>
/// The entry point for the IMA DAI SDK to make DAI stream requests.
@property(nonatomic, strong) IMAAdsLoader *adsLoader;
/// The container where the SDK renders each ad's user interface elements and companion slots.
@property(nonatomic, strong) IMAAdDisplayContainer *adDisplayContainer;
/// The reference of your video player for the IMA DAI SDK to monitor playback and handle timed
/// metadata.
@property(nonatomic, strong) IMAAVPlayerVideoDisplay *imaVideoDisplay;
/// References the stream manager from the IMA DAI SDK after successful stream loading.
@property(nonatomic, strong) IMAStreamManager *streamManager;

// ...

@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  self.adsLoader = [[IMAAdsLoader alloc] initWithSettings:nil];
  self.adsLoader.delegate = self;

  // Create an ad display container for rendering each ad's user interface elements and companion
  // slots.
  self.adDisplayContainer =
      [[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView
                                          viewController:self
                                          companionSlots:nil];

  // Create an IMAAVPlayerVideoDisplay to give the SDK access to your video player.
  self.imaVideoDisplay = [[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.videoPlayer];
}

Swift

import GoogleInteractiveMediaAds
// ...

class ViewController: UIViewController, IMAAdsLoaderDelegate, IMAStreamManagerDelegate {
  // ...

  /// The entry point for the IMA DAI SDK to make DAI stream requests.
  private var adsLoader: IMAAdsLoader?
  /// The container where the SDK renders each ad's user interface elements and companion slots.
  private var adDisplayContainer: IMAAdDisplayContainer?
  /// The reference of your video player for the IMA DAI SDK to monitor playback and handle timed
  /// metadata.
  private var imaVideoDisplay: IMAAVPlayerVideoDisplay!
  /// References the stream manager from the IMA DAI SDK after successfully loading the DAI stream.
  private var streamManager: IMAStreamManager?

  // ...

  override func viewDidLoad() {
    super.viewDidLoad()

    // ...

    adsLoader = IMAAdsLoader(settings: nil)
    adsLoader?.delegate = self

    // Create an ad display container for rendering each ad's user interface elements and companion
    // slots.
    adDisplayContainer = IMAAdDisplayContainer(
      adContainer: videoView,
      viewController: self,
      companionSlots: nil)

    // Create an IMAAVPlayerVideoDisplay to give the SDK access to your video player.
    imaVideoDisplay = IMAAVPlayerVideoDisplay(avPlayer: videoPlayer)
  }

Fazer uma solicitação de stream

Quando um usuário pressiona o botão de reprodução, faça uma nova solicitação de stream. Use a classe IMAPodStreamRequest para transmissões ao vivo. Para transmissões de VOD, use a classe IMAPodVODStreamRequest.

A solicitação de stream exige seus parâmetros de stream, bem como uma referência ao seu contêiner de exibição de anúncios e exibição de vídeo.

Objective-C

- (IBAction)onPlayButtonTouch:(id)sender {
  [self requestStream];
  self.playButton.hidden = YES;
}

- (void)requestStream {
  // Create a stream request.
  IMAStreamRequest *request;
  if (kStreamType == StreamTypeLive) {
    // Live stream request. Replace the network code and custom asset key with your values.
    request = [[IMAPodStreamRequest alloc] initWithNetworkCode:kNetworkCode
                                                customAssetKey:kCustomAssetKey
                                            adDisplayContainer:self.adDisplayContainer
                                                  videoDisplay:self.imaVideoDisplay
                                         pictureInPictureProxy:nil
                                                   userContext:nil];
  } else {
    // VOD request. Replace the network code with your value.
    request = [[IMAPodVODStreamRequest alloc] initWithNetworkCode:kNetworkCode
                                               adDisplayContainer:self.adDisplayContainer
                                                     videoDisplay:self.imaVideoDisplay
                                            pictureInPictureProxy:nil
                                                      userContext:nil];
  }
  [self.adsLoader requestStreamWithRequest:request];
}

Swift

@IBAction func onPlayButtonTouch(_ sender: Any) {
  requestStream()
  playButton.isHidden = true
}

func requestStream() {
  // Create a stream request. Use one of "Livestream request" or "VOD request".
  if ViewController.requestType == StreamType.live {
    // Livestream request.
    let request = IMAPodStreamRequest(
      networkCode: ViewController.networkCode,
      customAssetKey: ViewController.customAssetKey,
      adDisplayContainer: adDisplayContainer!,
      videoDisplay: self.imaVideoDisplay,
      pictureInPictureProxy: nil,
      userContext: nil)
    adsLoader?.requestStream(with: request)
  } else {
    // VOD stream request.
    let request = IMAPodVODStreamRequest(
      networkCode: ViewController.networkCode,
      adDisplayContainer: adDisplayContainer!,
      videoDisplay: self.imaVideoDisplay,
      pictureInPictureProxy: nil,
      userContext: nil)
    adsLoader?.requestStream(with: request)
  }
}

Detectar eventos de carregamento de stream

A classe IMAAdsLoader chama os métodos IMAAdsLoaderDelegate em caso de inicialização bem-sucedida ou falha da solicitação de stream.

No método delegado adsLoadedWithData, defina seu IMAStreamManagerDelegate. Transmita o ID da transmissão para seu gerenciador de VTP personalizado e recupere o URL do manifesto da transmissão. Para transmissões ao vivo, carregue o URL do manifesto na tela de vídeo e inicie a reprodução. Para transmissões de VOD, transmita o URL do manifesto ao método loadThirdPartyStream do gerenciador de transmissões. Esse método solicita dados de eventos de anúncios do Ad Manager 360, carrega o URL do manifesto e inicia a reprodução.

No método delegado failedWithErrorData, registre o erro. Se quiser, reproduza o fluxo de backup. Consulte as práticas recomendadas da DAI.

Objective-C

- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
  NSLog(@"Stream created with: %@.", adsLoadedData.streamManager.streamId);
  self.streamManager = adsLoadedData.streamManager;
  self.streamManager.delegate = self;

  // Build the Pod serving Stream URL.
  NSString *streamID = adsLoadedData.streamManager.streamId;
  // Your custom VTP handler takes the stream ID and returns the stream manifest URL.
  NSString *urlString = gCustomVTPHandler(streamID);
  NSURL *streamUrl = [NSURL URLWithString:urlString];
  if (kStreamType == StreamTypeLive) {
    // Load live streams directly into the AVPlayer.
    [self.imaVideoDisplay loadStream:streamUrl withSubtitles:@[]];
    [self.imaVideoDisplay play];
  } else {
    // Load VOD streams using the `loadThirdPartyStream` method in IMA SDK's stream manager.
    // The stream manager loads the stream, requests metadata, and starts playback.
    [self.streamManager loadThirdPartyStream:streamUrl streamSubtitles:@[]];
  }
}

- (void)adsLoader:(IMAAdsLoader *)loader failedWithErrorData:(IMAAdLoadingErrorData *)adErrorData {
  // Log the error and play the backup content.
  NSLog(@"AdsLoader error, code:%ld, message: %@", adErrorData.adError.code,
        adErrorData.adError.message);
  [self.videoPlayer play];
}

Swift

func adsLoader(_ loader: IMAAdsLoader, adsLoadedWith adsLoadedData: IMAAdsLoadedData) {
  print("DAI stream loaded. Stream session ID: \(adsLoadedData.streamManager!.streamId!)")
  streamManager = adsLoadedData.streamManager!
  streamManager!.delegate = self

  // Initialize the stream manager to handle ad click and user interactions with ad UI elements.
  streamManager!.initialize(with: nil)

  // Build the Pod serving Stream URL.
  let streamID = streamManager!.streamId
  // Your custom VTP handler takes the stream ID and returns the stream manifest URL.
  let urlString = ViewController.customVTPParser(streamID!)
  let streamUrl = URL(string: urlString)
  if ViewController.requestType == StreamType.live {
    // Live streams can be loaded directly into the AVPlayer.
    imaVideoDisplay.loadStream(streamUrl!, withSubtitles: [])
    imaVideoDisplay.play()
  } else {
    // VOD streams are loaded using the IMA SDK's stream manager.
    // The stream manager loads the stream, requests metadata, and starts playback.
    streamManager!.loadThirdPartyStream(streamUrl!, streamSubtitles: [])
  }
}

func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
  print("Error loading DAI stream. Error message: \(adErrorData.adError.message!)")
  // Play the backup stream.
  videoPlayer.play()
}

Implementar seu manipulador personalizado do VTP

O gerenciador de VTP personalizado envia o ID do fluxo do espectador ao seu parceiro técnico de vídeo (VTP) junto com outras informações necessárias para que o VTP retorne um manifesto de fluxo que contenha conteúdo e anúncios combinados. Seu VTP fornece instruções específicas sobre como implementar seu manipulador de VTP personalizado.

Por exemplo, um VTP pode incluir um URL de modelo de manifesto que contém a macro [[STREAMID]]. Neste exemplo, o gerenciador insere o ID do fluxo no lugar da macro e retorna o URL do manifesto resultante.

Objective-C

/// Custom VTP Handler.
///
/// Returns the stream manifest URL from the video technical partner or manifest manipulator.
static NSString *(^gCustomVTPHandler)(NSString *) = ^(NSString *streamID) {
  // Insert synchronous code here to retrieve a stream manifest URL from your video tech partner
  // or manifest manipulation server.
  // This example uses a hardcoded URL template, containing a placeholder for the stream
  // ID and replaces the placeholder with the stream ID.
  NSString *manifestUrl = @"YOUR_MANIFEST_URL_TEMPLATE";
  return [manifestUrl stringByReplacingOccurrencesOfString:@"[[STREAMID]]"
                                                withString:streamID];
};

Swift

/// Custom VTP Handler.
///
/// Returns the stream manifest URL from the video technical partner or manifest manipulator.
static let customVTPParser = { (streamID: String) -> (String) in
  // Insert synchronous code here to retrieve a stream manifest URL from your video tech partner
  // or manifest manipulation server.
  // This example uses a hardcoded URL template, containing a placeholder for the stream
  // ID and replaces the placeholder with the stream ID.
  let manifestURL = "YOUR_MANIFEST_URL_TEMPLATE"
  return manifestURL.replacingOccurrences(of: "[[STREAMID]]", with: streamID)
}

Detectar eventos de anúncios

O IMAStreamManager chama os métodos IMAStreamManagerDelegate para transmitir eventos e erros ao seu aplicativo.

Neste exemplo, registre os eventos de anúncio principais no console:

Objective-C

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

      NSLog(@"%@", extendedAdPodInfo);
      break;
    }
    case kIMAAdEvent_AD_BREAK_STARTED: {
      NSLog(@"Ad break started");
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      NSLog(@"Ad break ended");
      break;
    }
    case kIMAAdEvent_AD_PERIOD_STARTED: {
      NSLog(@"Ad period started");
      break;
    }
    case kIMAAdEvent_AD_PERIOD_ENDED: {
      NSLog(@"Ad period ended");
      break;
    }
    default:
      break;
  }
}

- (void)streamManager:(IMAStreamManager *)streamManager didReceiveAdError:(IMAAdError *)error {
  NSLog(@"StreamManager error with type: %ld\ncode: %ld\nmessage: %@", error.type, error.code,
        error.message);
  [self.videoPlayer play];
}

Swift

func streamManager(_ streamManager: IMAStreamManager, didReceive event: IMAAdEvent) {
  print("Ad event \(event.typeString).")
  switch event.type {
  case IMAAdEventType.STARTED:
    // Log extended data.
    if let ad = event.ad {
      let extendedAdPodInfo = String(
        format: "Showing ad %zd/%zd, bumper: %@, title: %@, "
          + "description: %@, contentType:%@, pod index: %zd, "
          + "time offset: %lf, max duration: %lf.",
        ad.adPodInfo.adPosition,
        ad.adPodInfo.totalAds,
        ad.adPodInfo.isBumper ? "YES" : "NO",
        ad.adTitle,
        ad.adDescription,
        ad.contentType,
        ad.adPodInfo.podIndex,
        ad.adPodInfo.timeOffset,
        ad.adPodInfo.maxDuration)

      print("\(extendedAdPodInfo)")
    }
    break
  case IMAAdEventType.AD_BREAK_STARTED:
    print("Ad break started.")
    break
  case IMAAdEventType.AD_BREAK_ENDED:
    print("Ad break ended.")
    break
  case IMAAdEventType.AD_PERIOD_STARTED:
    print("Ad period started.")
    break
  case IMAAdEventType.AD_PERIOD_ENDED:
    print("Ad period ended.")
    break
  default:
    break
  }
}

func streamManager(_ streamManager: IMAStreamManager, didReceive error: IMAAdError) {
  print("StreamManager error with type: \(error.type)")
  print("code: \(error.code)")
  print("message: \(error.message ?? "Unknown Error")")
}

Limpar recursos da DAI do IMA

Para interromper a reprodução do stream, parar todo o rastreamento de anúncios e liberar todos os recursos de stream carregados, chame IMAStreamManager.destroy().

Execute o app. Se tudo der certo, solicite e reproduza streams de DAI do Google com o SDK do IMA. Para saber mais sobre recursos avançados do SDK, consulte outros guias listados na barra lateral esquerda ou exemplos no GitHub.