Comenzar

Requisitos previos

• Xcode 13 o una versión más reciente

En esta guía, se describe cómo invocar el SDK de PAL para recibir un nonce y supervisar eventos de reproducción. Para continuar con la guía completa, descarga la aplicación de muestra de PAL 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 es compatible con 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, navega a File > Add Packages... para instalar el paquete 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-programmatic-access-library-tvos
   

3. Selecciona la versión del paquete de Swift del SDK para PAL que deseas 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 PAL de forma manual

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

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

Cómo generar un nonce

Un “nonce” es una única string encriptada que genera PAL con el PALNonceLoader. El SDK de PAL requiere que cada solicitud de transmisión nueva vaya acompañada 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 aparecen a continuación son modificaciones en ViewController.m en la aplicación de ejemplo de PAL tvOS.

Para solicitar un nonce, primero importa la biblioteca PAL:

@import ProgrammaticAccessLibrary;

Nota: Te recomendamos que crees solo una instancia de la clase PALNonceLoader para cada sesión de usuario en tu app, a menos que esta tenga varias páginas o construcciones equivalentes. De esta manera, se mantiene el correlator de la página, o el parámetro &correlator, sin cambios durante el ciclo de vida de una página o la sesión de la app de un usuario.

Aún tienes el control sobre el correlator de transmisión, o &scor, que se debe restablecer una vez para cada transmisión nueva. Todas las solicitudes de anuncios de la misma transmisión deben compartir el mismo valor de PALNonceLoader y de correlator de transmisión para que las funciones de limitación de frecuencia y exclusión competitiva funcionen correctamente.

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

@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 'allowStorage' and
  // 'directedForChildOrUnknownAge' is 'NO', but should be updated once the
  // appropriate consent has been gathered. Publishers should either
  // integrate with a CMP or use a different method to handle storage consent.
  PALSettings *settings = [[PALSettings alloc] init];
  settings.allowStorage = YES;
  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, propaga sus propiedades y úsala para inicializar un administrador de nonce:

@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.
 */
- (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 integer. See reference docs for more details.
  NSInteger SampleAPIFramework = 501;
  request.supportedApiFrameworks = [NSMutableSet setWithArray:@[ SampleAPIFramework ]];
  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, propaga los delegados del cargador 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 el nonce como el valor en el parámetro givn. El nonce es seguro para las URL, no es necesario que lo codifiques en formato URL.

Precaución: Si antes proporcionaste un nonce con el parámetro paln, te recomendamos que migres a givn y que dejes de enviar paln. Si se incluyen ambos parámetros, es un comportamiento indefinido con respecto a qué nonce se usa.

Por último, debes agregar métodos para controlar el envío de la información de la sesión de reproducción de contenido y de los clics al SDK. Consulta el siguiente ejemplo de implementación de 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 cuando "se inicia el reproductor de video" cuando se inicia 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 finaliza la reproducción, y se debe llamar a sendAdClick cada vez que el usuario hace 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 propaga 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.

Nota: Si usas varias soluciones de terceros, por ejemplo, un servidor de SSAI de terceros que llama a otro servidor de anuncios de terceros, debes asegurarte de que el nonce encriptado del SDK de PAL se reenvíe a cada tercero.

Configura tu servidor de anuncios de terceros para incluir el nonce en la solicitud del servidor a Ad Manager. A continuación, se muestra un ejemplo de una etiqueta de anuncio configurada dentro de un 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 del 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 de terceros, deberías encontrar más información disponible sobre cómo lograr esto.