Comenzar

Requisitos previos

  • Xcode 13 o una versión posterior

En esta guía, se describe cómo invocar el SDK de PAL para recibir un nonce y supervisar los eventos de reproducción. Para seguir la guía completa, descarga la aplicación de ejemplo de PAL para tvOS.

Agrega el SDK de PAL a tu proyecto

Instala el SDK de PAL con Swift Package Manager

El SDK de la biblioteca de acceso programático admite Swift Package Manager a partir de la versión 2.5.3. Sigue los pasos que se indican a continuación para importar el paquete de Swift.

  1. En Xcode, instala el paquete de Swift del SDK de IMA. 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:

    https://github.com/googleads/swift-package-manager-google-programmatic-access-library-tvos
    
  3. Selecciona la versión del paquete de Swift del SDK de PAL que deseas usar. Para los proyectos nuevos, te recomendamos que uses la opción Up to Next Major Version.

Cuando termines, Xcode resolverá las dependencias de tu paquete 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 PAL de forma manual

Si no quieres usar Swift Package Manager, puedes descargar el SDK de la PAL y agregarlo manualmente a tu proyecto.

  1. Descarga y extrae el SDK de la PAL para tvOS
  2. Sigue la Guía para desarrolladores de Apple para incorporar el framework en tu proyecto.

Cómo generar un nonce

Un "nonce" es una sola cadena encriptada que PAL genera con PALNonceLoader. El SDK de PAL requiere que cada solicitud de transmisión nueva se acompañe de un nonce recién generado. Sin embargo, los nonces se pueden volver a usar para varias solicitudes de anuncios dentro de la misma transmisión.

Todos los fragmentos de código que se muestran a continuación son modificaciones de ViewController.m en la aplicación de ejemplo de PAL para tvOS.

Para solicitar un nonce, primero importa la biblioteca de PAL:

@import ProgrammaticAccessLibrary;

A continuación, crea una instancia de PALNonceLoader y agrega stubs para los dos métodos de delegado:

@interface ViewController () <PALNonceLoaderDelegate>
// The nonce loader to use for nonce requests.
@property(nonatomic) PALNonceLoader *nonceLoader;
// The view in which a video would play.
// In this sample, it is mocked for simplification.
@property(nonatomic, weak) IBOutlet UIView *videoView;
@end
...
- (void) viewDidLoad {
  [super viewDidLoad];
  // The default value for 'directedForChildOrUnknownAge' is
  // 'NO'. Update the value after the appropriate consent has been gathered.
  // By default, PAL automatically determines whether to enable limited ads
  // based on the user's TCF (Transparency and Consent Framework) consent data
  // on the device. If you must manually override the default behavior,
  // for example, to meet your app's requirements, use the
  // `PALSettings.forceLimitedAds` property.
  PALSettings *settings = [[PALSettings alloc] init];
  settings.directedForChildOrUnknownAge = NO;

  self.nonceLoader = [[PALNonceLoader alloc] initWithSettings:settings];
  self.nonceLoader.delegate = self;
}

#pragma mark - PALNonceLoaderDelegate methods

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
            withRequest:(PALNonceRequest *)request
    didLoadNonceManager:(PALNonceManager *)nonceManager {
}

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
         withRequest:(PALNonceRequest *)request
    didFailWithError:(NSError *)error {
}

Luego, inicia una solicitud de nonce, completa sus propiedades y úsala para inicializar un administrador de nonces:

@interface ViewController () <PALNonceLoaderDelegate>
// The nonce loader to use for nonce requests.
@property(nonatomic) PALNonceLoader *nonceLoader;
// The nonce manager result from the last successful nonce request.
@property(nonatomic) PALNonceManager *nonceManager;
// The view in which a video would play. In this sample, it is mocked for
// simplification.
@property(nonatomic, weak) IBOutlet UIView *videoView;
@end

...

- (void)viewDidLoad {
  ...
  self.nonceLoader.delegate = self;
  [self requestNonceManager];
}

...

#pragma mark - UI Callback methods

/**
 * Requests a new nonce manager with a request containing arbitrary test values
 * like a (sane) user might supply. Displays the nonce or error on success. This
 * should be called once per stream.
 *
 * The PALNonceRequest parameters set here are example parameters.
 * You should set your parameters based on your own app characteristics.
 */
- (void)requestNonceManager {
  PALNonceRequest *request = [[PALNonceRequest alloc] init];
  request.continuousPlayback = PALFlagOff;
  request.descriptionURL = [NSURL URLWithString:@"https://example.com/desc?key=val"];
  request.iconsSupported = YES;
  request.playerType = @"AwesomePlayer";
  request.playerVersion = @"4.2.1";
  request.PPID = @"123987456";
  request.sessionID = @"Sample SID";
  // Sample API framework integers. See reference docs for more details.
  request.supportedAPIFrameworks = [NSMutableSet setWithArray:@[ @2, @7, @9 ]];
  request.videoPlayerHeight = 480;
  request.videoPlayerWidth = 640;
  request.willAdAutoPlay = PALFlagOn;
  request.willAdPlayMuted = PALFlagOff;

  if (self.nonceManager) {
    // Detach the old nonce manager's gesture recognizer before destroying it.
    [self.videoView removeGestureRecognizer:self.nonceManager.gestureRecognizer];
    self.nonceManager = nil;
  }
  [self.nonceLoader loadNonceManagerWithRequest:request];
}

Por último, completa los delegados del cargador de nonce para registrar los nonces generados:

#pragma mark - PALNonceLoaderDelegate methods

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
            withRequest:(PALNonceRequest *)request
    didLoadNonceManager:(PALNonceManager *)nonceManager {
  NSLog(@"Programmatic access nonce: %@", nonceManager.nonce);
  // Capture the created nonce manager and attach its gesture recognizer to the video view.
  self.nonceManager = nonceManager;
  [self.videoView addGestureRecognizer:self.nonceManager.gestureRecognizer];
}

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
         withRequest:(PALNonceRequest *)request
    didFailWithError:(NSError *)error {
  NSLog(@"Error generating programmatic access nonce: %@", error);
}

Cuando realices tu llamada directa de VAST (DVC), establece tu nonce como el valor del parámetro givn. El nonce es seguro para las URLs, por lo que no es necesario que lo codifiques para ese formato.

Por último, debes agregar métodos para controlar el envío de información y clics de la sesión de reproducción de contenido al SDK. Consulta el siguiente ejemplo que implementa los métodos sendPlaybackStart, sendPlaybackEnd y sendAdClick:

...

// Reports the start of playback for the current content session.
- (void)sendPlaybackStart {
  [self.nonceManager sendPlaybackStart];
}

// Reports the end of playback for the current content session.
- (void)sendPlaybackEnd {
  [self.nonceManager sendPlaybackEnd];
}

// Reports an ad click for the current nonce manager, if not nil.
- (void)sendAdClick {
  [self.nonceManager sendAdClick];
}

En tu implementación, se debe llamar a sendPlaybackStart en el "inicio del reproductor de video" cuando se inicie la reproducción por primera vez, en respuesta a una acción iniciada por el usuario (clic para reproducir) o una acción iniciada por la app (reproducción automática). Se debe llamar a sendPlaybackEnd cuando finalice la reproducción y se debe llamar a sendAdClick cada vez que el usuario haga clic en un anuncio.

(Opcional) Envía indicadores de Google Ad Manager a través de servidores de anuncios de terceros

Configura la solicitud del servidor de anuncios de terceros para Ad Manager. Después de completar los siguientes pasos, el parámetro nonce se propagará desde el SDK de PAL, a través de tus servidores intermediarios y, luego, a Google Ad Manager. Esto permite una mejor monetización a través de Google Ad Manager.

Configura tu servidor de anuncios de terceros para que incluya el nonce en la solicitud del servidor a Ad Manager. Este es un ejemplo de una etiqueta de anuncio configurada dentro del servidor de anuncios de terceros:

https://pubads.serverside.net/gampad/ads?givn=%%custom_key_for_google_nonce%%&...

Para obtener más detalles, consulta la guía de implementación del servidor de Google Ad Manager.

Ad Manager busca givn= para identificar el valor de nonce. El servidor de anuncios de terceros debe admitir alguna macro propia, como %%custom_key_for_google_nonce%%, y reemplazarla por el parámetro de consulta nonce que proporcionaste en el paso anterior. En la documentación del servidor de anuncios externo, debería haber más información sobre cómo lograr esto.