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

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

Seleccione la solución de DAI que le interesa

DAI de servicio completo

En esta guía, se muestra cómo integrar el SDK de IMA de DAI en una app simple de reproductor de video. Si deseas ver o seguir una integración de muestra 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: Es un objeto contenedor que se ubica sobre el elemento de reproducción de video y aloja los elementos de la IU del anuncio.
  • IMAAdsLoader: Es un objeto que solicita transmisiones y controla los eventos activados por los objetos de respuesta a 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: ya sea IMAVODStreamRequest o IMALiveStreamRequest: Es un objeto que define una solicitud de transmisión. Las solicitudes de transmisión pueden ser para transmisiones de video on demand o 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 interacciones y los flujos de inserción de anuncios dinámicos con el backend de la DAI. El administrador de transmisiones también controla el seguimiento de los pings y reenvía eventos de transmisión y anuncios al publicador.

Requisitos previos

Antes de comenzar, necesitas lo siguiente:

Crea un proyecto de Xcode nuevo

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

Agregue el SDK de IMA de DAI al proyecto de Xcode

Use uno de estos tres métodos para instalar el SDK de IMA de 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 de 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, usa las siguientes instrucciones para instalar el SDK de IMA de DAI:

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

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

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

    pod install --repo-update`

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

Instala el SDK con Swift Package Manager

El SDK de anuncios multimedia interactivos es compatible con Swift Package Manager a partir de la versión 3.18.4. Sigue estos pasos para importar el paquete de Swift.

  1. En Xcode, navega a File > Add Packages para instalar el paquete de Swift del SDK de DAI de IMA.

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

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

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

Cuando termines, Xcode resuelve las dependencias de paquetes y las descarga en segundo plano. Para obtener más información 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 o CocoaPods, puedes descargar el SDK de IMA de DAI y agregarlo manualmente a tu proyecto.

Cómo crear un reproductor de video simple

Primero, implementa un reproductor de video básico. Inicialmente, este reproductor no usa el SDK de DAI de IMA ni contiene ningún método para activar la reproducción.

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

Importa el SDK y agrega stubs para la interacción de IMA

Después de agregar el SDK de IMA de DAI a tu proyecto, importa el SDK y agrega stubs para los puntos principales de interacción de 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

Cómo implementar IMAAdsLoader

Luego, crea una instancia de IMAAdsLoader y adjunta la vista del contenedor de anuncios a la jerarquía de vistas.

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;
}

Cómo realizar una solicitud de transmisión

Crea algunas constantes para contener la información de la transmisión y, luego, implementa la función de solicitud de transmisión para realizar la solicitud.

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];
}

Controla eventos de transmisión

Los eventos IMAAdsLoader y IMAStreamManager activan eventos que se usan para controlar la inicialización, los errores y los cambios en el estado de transmisión. Estos eventos se activan a través de los protocolos IMAAdsLoaderDelegate y IMAStreamManagerDelegate. Detecta un evento de carga de anuncios y, luego, inicializa la transmisión. Si un anuncio no se carga, reproduce una transmisión de copia de seguridad.

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

Administra el registro y los eventos de errores

Hay varios eventos que el delegado del administrador de transmisión puede controlar, pero para las implementaciones básicas, los usos más importantes son realizar el registro de eventos, evitar acciones de búsqueda mientras se reproducen los anuncios y manejar errores.

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

Listo. Ahora solicita y muestra anuncios con el SDK de DAI de IMA. Para obtener información sobre funciones del SDK más avanzadas, consulta las otras guías o las muestras en GitHub.