Cómo comenzar a usar el SDK de IMA de DAI

Los SDKs de IMA facilitan la integración de anuncios multimedia en tus sitios web y apps. Los SDKs de IMA pueden solicitar anuncios de cualquier servidor de anuncios que cumpla con VAST y administrar la reproducción de anuncios en tus apps. Con los SDKs de DAI de IMA, las apps realizan una solicitud de transmisión de anuncios y videos de contenido, ya sea VOD o contenido en vivo. Luego, el SDK muestra una transmisión de video combinada para que no tengas que administrar el cambio entre el video de anuncios y el de contenido dentro de tu app.

Selecciona la solución de DAI que te interesa

Publicación de grupos de anuncios de DAI

En esta guía, se muestra cómo integrar el SDK de IMA DAI en una app de reproductor de video simple. Si deseas ver o seguir una integración de muestra completa, descarga PodServingExample desde GitHub.

Descripción general de la DAI de IMA

La implementación de la DAI de IMA implica cuatro componentes principales del SDK, como se muestra en esta guía:

• IMAAdDisplayContainer: Un objeto contenedor que se encuentra sobre el elemento de reproducción de video y aloja los elementos de la IU del anuncio.
• IMAAdsLoader: Un objeto que solicita transmisiones y controla los eventos activados por objetos de respuesta de solicitudes de transmisión. Solo debes crear una instancia de un cargador de anuncios, que se puede volver a usar durante la vida útil de la aplicación.
• IMAStreamRequest: Puede ser IMAPodVODStreamRequest o IMAPodStreamRequest.
• IMAStreamManager: Es un objeto que controla las transmisiones de inserción de anuncios dinámicos y las interacciones con el backend de la DAI. El administrador de transmisiones también controla los pings de seguimiento y reenvía los eventos de transmisión y de anuncios al publicador.

Además, para reproducir transmisiones de entrega de pods, debes implementar un controlador de VTP personalizado. Este controlador de VTP personalizado envía el ID de transmisión a tu socio técnico de video (VTP) junto con cualquier otra información que requiera para mostrar un manifiesto de transmisión que contenga contenido y anuncios unidos. Tu VTP te proporcionará instrucciones para implementar tu controlador de VTP personalizado.

Requisitos previos

Antes de comenzar, necesitas lo siguiente:

• Xcode 13 o una versión posterior
• CocoaPods (preferido), Swift Package Manager o una copia descargada del SDK de IMA DAI para iOS

También necesitas los parámetros que se usan para solicitar tu transmisión desde el SDK de IMA.

Crea un nuevo proyecto de Xcode

En Xcode, crea un proyecto de iOS nuevo con Objective-C llamado "PodServingExample".

Agrega el SDK de IMA DAI al proyecto de Xcode

Usa uno de estos tres métodos para instalar el SDK de IMA DAI.

Instala el SDK con CocoaPods (opción preferida)

CocoaPods es un administrador de dependencias para proyectos de Xcode y es el método recomendado para instalar el SDK de IMA DAI. Para obtener más información sobre cómo instalar o usar CocoaPods, consulta la documentación de CocoaPods. Después de instalar CocoaPods, sigue las siguientes instrucciones para instalar el SDK de IMA DAI:

1. En el mismo directorio en que está el archivo PodServingExample.xcodeproj, crea un archivo de texto llamado Podfile y agrega la siguiente configuración:

   Podfile
   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '14'
   
   target 'PodServingExample' do
     pod 'GoogleAds-IMA-iOS-SDK'
   end
   Podfile

2. Desde el directorio que contiene el Podfile, ejecuta lo siguiente:

   pod install --repo-update

Instala el SDK con Swift Package Manager

El SDK de anuncios multimedia interactivos admite Swift Package Manager a partir de la versión 3.18.4. Sigue los pasos que se indican a continuación para importar el paquete Swift.

1. En Xcode, instala el paquete Swift del SDK de IMA DAI. Para ello, navega a File > Add Packages.

2. En el mensaje que aparece, busca el repositorio de GitHub del paquete de Swift del SDK de IMA DAI:

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

3. Selecciona la versión del paquete Swift del SDK de IMA DAI que quieres usar. Para proyectos nuevos, recomendamos usar la opción Hasta la siguiente versión principal.

Cuando termines, Xcode resolverá las dependencias de tus paquetes y las descargará en segundo plano. Para obtener más detalles sobre cómo agregar dependencias de paquetes, consulta el artículo de Apple.

Descarga e instala el SDK de forma manual

Si no quieres usar Swift Package Manager ni CocoaPods, puedes descargar el SDK de IMA DAI y agregarlo manualmente a tu proyecto.

Crea un reproductor de video simple

Implementa un reproductor de video en tu controlador de vista principal con un reproductor de AV unido en una vista de IU. El SDK de IMA usa la vista de la IU para mostrar los elementos de la IU del anuncio.

#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
ViewController.m

Cómo inicializar el cargador de anuncios

Importa el SDK de IMA a tu controlador de vista y adopta los protocolos IMAAdsLoaderDelegate y IMAStreamManagerDelegate para controlar los eventos del cargador de anuncios y el administrador de transmisiones.

Agrega estas propiedades privadas para almacenar los componentes clave del SDK de IMA:

• IMAAdsLoader: Administra las solicitudes de transmisión durante el ciclo de vida de tu app.
• IMAAdDisplayContainer: Controla la inserción y administración de elementos de la interfaz de usuario del anuncio.
• IMAAVPlayerVideoDisplay: Se comunica entre el SDK de IMA y tu reproductor multimedia, y controla los metadatos sincronizados.
• IMAStreamManager: Administra la reproducción de transmisiones y activa eventos relacionados con los anuncios.

Inicializa el cargador de anuncios, el contenedor de visualización de anuncios y la visualización de video después de que se cargue la vista.

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

Realiza una solicitud de transmisión

Cuando un usuario presiona el botón de reproducción, realiza una nueva solicitud de transmisión. Usa la clase IMAPodStreamRequest para las transmisiones en vivo. Para las transmisiones de VOD, usa la clase IMAPodVODStreamRequest.

La solicitud de transmisión requiere tus parámetros de transmisión, así como una referencia a tu contenedor de visualización de anuncios y a la visualización de video.

- (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:adDisplayContainer
                                                  videoDisplay:self.videoDisplay
                                         pictureInPictureProxy:nil
                                                   userContext:nil];
  } else {
    // VOD request. Replace the network code with your value.
    request = [[IMAPodVODStreamRequest alloc] initWithNetworkCode:@kNetworkCode
                                               adDisplayContainer:adDisplayContainer
                                                     videoDisplay:self.videoDisplay
                                            pictureInPictureProxy:nil
                                                      userContext:nil];
  }
  [self.adsLoader requestStreamWithRequest:request];
}
ViewController.m

Cómo escuchar eventos de carga de transmisión

La clase IMAAdsLoader llama a los métodos IMAAdsLoaderDelegate cuando la inicialización se realiza correctamente o falla la solicitud de transmisión.

En el método del delegado adsLoadedWithData, configura tu IMAStreamManagerDelegate. Pasa el ID de transmisión a tu controlador de VTP personalizado y recupera la URL del manifiesto de transmisión. En el caso de las transmisiones en vivo, carga la URL del manifiesto en la pantalla de video y comienza la reproducción. Para las transmisiones de VOD, pasa la URL del manifiesto al método loadThirdPartyStream del administrador de transmisiones. Este método solicita datos de eventos de anuncios de Ad Manager 360, luego carga la URL del manifiesto y comienza la reproducción.

En el método delegado failedWithErrorData, registra el error. De manera opcional, reproduce la transmisión de copia de seguridad. Consulta las prácticas recomendadas de DAI.

- (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.videoDisplay loadStream:streamUrl withSubtitles:@[]];
    [self.videoDisplay 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];
}
ViewController.m

Implementa tu controlador de VTP personalizado

El controlador de VTP personalizado envía el ID de transmisión del usuario a tu socio técnico de video (VTP) junto con cualquier otra información que este requiera para mostrar un manifiesto de transmisión que contenga contenido y anuncios unidos. Tu VTP te proporcionará instrucciones específicas para implementar tu controlador de VTP personalizado.

Por ejemplo, un VTP puede incluir una URL de plantilla de manifiesto que contenga la macro [[STREAMID]]. En este ejemplo, el controlador inserta el ID de flujo en lugar de la macro y muestra la URL del manifiesto resultante.

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

Cómo escuchar eventos de anuncios

IMAStreamManager llama a los métodos IMAStreamManagerDelegate para pasar eventos y errores de transmisión a tu aplicación.

En este ejemplo, registra los eventos de anuncios principales en la consola:

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

Limpia los recursos de DAI de IMA

Para detener la reproducción de la transmisión, detener todo el seguimiento de anuncios y liberar todos los recursos de transmisión cargados, llama a IMAStreamManager.destroy().

Ejecuta tu app y, si se realiza correctamente, podrás solicitar y reproducir transmisiones de Google DAI con el SDK de IMA. Para obtener información sobre funciones más avanzadas del SDK, consulta otras guías que se enumeran en la barra lateral izquierda o los ejemplos en GitHub.