Se usó la API de Cloud Translation para traducir esta página.

Cómo comenzar

Con los SDK de IMA, puedes integrar fácilmente anuncios multimedia en tus sitios web y apps. 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 SDKs 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, 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 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 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 objetos de respuesta de solicitud 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 IMAVODStreamRequest o 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 los pings de seguimiento y reenvía eventos de anuncios y transmisiones al publicador.

Requisitos previos

Antes de comenzar, necesitas lo siguiente:

Xcode 13 o una versión más reciente
CocoaPods (preferido), Swift Package Manager o una copia descargada del SDK de IMA para tvOS

1. Crea un proyecto de Xcode nuevo

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

2. Agrega el SDK de IMA al proyecto de Xcode

Instala 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 la instalación o el uso de CocoaPods, consulta la documentación de CocoaPods. Una vez que tengas instalado CocoaPods, usa las siguientes instrucciones para instalar el SDK de IMA:

En el mismo directorio que tu 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

Desde el directorio que contiene el Podfile, ejecuta pod install --repo-update.
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 instaladas por CocoaPods).

Instala el SDK con Swift Package Manager

El SDK de anuncios multimedia interactivos admite 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.

En Xcode, instala el paquete de Swift del SDK de IMA. Para ello, navega a File > Add Packages....
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
```
Selecciona la versión del paquete de Swift del SDK de IMA que quieres usar. Para los proyectos nuevos, te recomendamos usar Hasta la siguiente versión principal.

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

Descargar e instalar el SDK de forma manual

Si no quieres usar CocoaPods, puedes descargar el SDK de IMA y agregarlo manualmente a tu proyecto.

Mostrar/ocultar instrucciones

En la página de descarga de IMA de tvOS, descarga y extrae la versión más reciente del SDK de IMA de tvOS.
Abre BasicExample.xcodeproj.
En el panel izquierdo, haz clic en el nombre del proyecto.
En el panel central, haz clic en Fases de compilación.
Expande la sección Link Binary With Libraries.
En la parte inferior de la lista de bibliotecas, haz clic en el ícono de signo más [+].
Haz clic en Agregar Otros.
En el directorio donde extrajiste el SDK descargado, selecciona GoogleInteractiveMediaAds.framework y haz clic en Open.
En la parte inferior de la lista de bibliotecas, vuelve a hacer clic en el ícono de signo más [+].
En la columna Estado, verifica que GoogleInteractiveMediaAds.framework esté configurado como Required.
Incluye la marca del vinculador -ObjC en tu configuración de compilación. Para obtener más información, consulta Apple QA1490.

3. Cómo crear un reproductor de video simple

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 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. Haz 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 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 la 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 no se carga un anuncio, 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 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 controlar 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 solicita y muestra 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

Si desea maximizar los ingresos publicitarios en la plataforma de tvOS, solicite el permiso de seguimiento y transparencia de la aplicación para usar el IDFA.