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

DAI de servicio completo

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 ejemplo completa, descarga BasicExample 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: Es un IMAVODStreamRequest o un IMALiveStreamRequest. Es un objeto que define una solicitud de transmisión. Las solicitudes de transmisión pueden ser de video on demand o de transmisiones en vivo. Las solicitudes especifican un ID de contenido, así como una clave de API o un token de autenticación y otros parámetros.
• 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.

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. Para ver ejemplos de parámetros de solicitud, consulta Fluxes de muestra.

Crea un proyecto de Xcode nuevo

En Xcode, crea un proyecto de iOS nuevo con Objective-C. Usa BasicExample como nombre del proyecto.

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 BasicExample.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 'BasicExample' do
     pod 'GoogleAds-IMA-iOS-SDK', '~> 3.23.0'
   end
   Podfile

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

   pod install --repo-update`

3. Para verificar que la instalación se haya realizado correctamente, abre el archivo BasicExample.xcworkspace y confirma que contenga dos proyectos: BasicExample y Pods (las dependencias que instala CocoaPods).

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 IMALiveStreamRequest para las transmisiones en vivo. Para las transmisiones de VOD, usa la clase IMAVODStreamRequest.

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. Use one of "Live stream request" or "VOD request", depending on your
  // type of stream.
  IMAStreamRequest *request;
  // Switch this variable to NO to make a VOD request.
  BOOL useLiveStream = YES;
  if (useLiveStream) {
    // Live stream request. Replace the asset key with your value.
    request = [[IMALiveStreamRequest alloc] initWithAssetKey:@"c-rArva4ShKVIAkNfy6HUQ"
                                          adDisplayContainer:self.adDisplayContainer
                                                videoDisplay:self.imaVideoDisplay
                                                 userContext:nil];
  } else {
    // VOD request. Replace the content source ID and video ID with your values.
    request = [[IMAVODStreamRequest alloc] initWithContentSourceID:@"2548831"
                                                           videoID:@"tears-of-steel"
                                                adDisplayContainer:self.adDisplayContainer
                                                      videoDisplay:self.imaVideoDisplay
                                                       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 e inicializa el administrador de transmisiones. Durante la inicialización, el administrador de transmisiones 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;
  [self.streamManager initializeWithAdsRenderingSettings:nil];
}

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

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.