Cómo comenzar

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 el anuncio y el contenido de video, ya sea VOD o contenido en vivo. Luego, el SDK muestra una transmisión de video por Internet combinada, de modo que no tengas que administrar el cambio entre el anuncio y el video de contenido dentro de tu app.

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

Descripción general de la DAI de IMA

La implementación de la DAI de IMA implica tres componentes principales del SDK, que se demuestran en esta guía:

  • IMAAdDisplayContainer: Es un objeto contenedor que se ubica sobre el elemento de reproducción de video y contiene los elementos de la IU del anuncio.
  • IMAAdsLoader: Es un objeto que solicita transmisiones y controla 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: 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 en vivo. Las solicitudes especifican un ID de contenido, 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 los eventos de transmisión y de anuncios al publicador.

Requisitos previos

Antes de comenzar, necesitas lo siguiente:

1. Crea un proyecto de Xcode nuevo

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

2. Agrega el SDK de IMA al proyecto de Xcode

Instalar el SDK con CocoaPods (preferido)

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

  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 :tvos, '14'
target "BasicExample" do
  pod 'GoogleAds-IMA-tvOS-SDK', '~> 4.9.2'
end

  2. Desde el directorio que contiene el Podfile, ejecuta pod install --repo-update.

  3. Verifica que la instalación se haya realizado con éxito. 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 4.8.2. Sigue los pasos que se indican a continuación para importar el paquete de Swift.

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

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

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

  3. Selecciona la versión del paquete Swift del SDK de IMA que quieres usar. Para proyectos nuevos, te recomendamos usar 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 CocoaPods, puedes descargar el SDK de IMA y agregarlo de forma manual a tu proyecto.

3. Cómo crear un reproductor de video sencillo

Primero, implementa un reproductor de video básico. Inicialmente, este reproductor no usa el SDK de IMA y aún no 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

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

Una vez que hayas agregado el SDK de IMA a tu proyecto, importa el SDK y agrega stubs para los puntos principales de la 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

5. Cómo implementar IMAAdsLoader

A continuación, 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;
}
...

6. Realiza una solicitud de transmisión continua

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

ViewController.m

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

static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2528370";
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];
}
...

7. 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. Escucha 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 en su lugar.

ViewController.m

...
static NSString *const kAssetKey = @"sN_IYUG8STe1ZzhIIE_ksA";
static NSString *const kContentSourceID = @"2528370";
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

8. Controla los eventos de registro y de errores

Hay varios eventos que el delegado del administrador de transmisiones puede controlar, pero para implementaciones básicas, los usos más importantes son realizar registros 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.
      self.playerViewController.requiresLinearPlayback = YES;
      break;
    }
    case kIMAAdEvent_AD_BREAK_ENDED: {
      // Allow users to seek through after an ad ends.
      self.playerViewController.requiresLinearPlayback = NO;
      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 solicitas y muestras anuncios con el SDK de IMA. Para obtener información sobre funciones del SDK más avanzadas, consulta las otras guías o las muestras en GitHub.

Próximos pasos

Para maximizar los ingresos publicitarios en la plataforma tvOS, solicita el permiso de Transparencia y seguimiento de apps para usar el IDFA.