Comenzar

Requisitos previos

Para integrar y probar el SDK de PAL para Cast, necesitas lo siguiente:

• Una app receptora para generar un nonce con la intercepción de mensajes.

• Una app emisora para activar el receptor y cargar contenido que incluya una solicitud de anuncio

Dado que solo necesitas actualizar tu app para receptores para integrar el SDK de PAL, puedes usar la herramienta de comando y control de Cast (CAC) como un remitente web para probar tu receptor.

Puedes ejecutar la muestra al final de cada paso. Para ello, primero inicia tu app de receptor web en la herramienta de CAC y, luego, realiza cualquier solicitud de carga.

Generar nonce

Un "nonce" es una sola cadena encriptada que genera PAL a través de NonceManager. El método loadNonceManager del NonceLoader genera el NonceManager según la configuración que se pasa en un NonceRequest. Para ver una app de ejemplo que usa PAL para generar un nonce, descarga el ejemplo de Cast desde GitHub.

Cada solicitud de transmisión nueva requiere un nonce nuevo. Varias solicitudes de anuncios dentro del mismo flujo pueden usar el mismo nonce. Para generar un nonce con el SDK de PAL, primero crea una app de receptor web personalizada y agrega el siguiente código:

receiver.html

<!DOCTYPE html>
<html>
<head>
  <script src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <script src="//imasdk.googleapis.com/pal/sdkloader/cast_pal.js"></script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <footer>
    <script src="js/receiver.js" type="module"></script>
  </footer>
</body>
</html>

El elemento <cast-media-player> representa la IU del reproductor integrada que proporciona la API de Cast Web Receiver. Según el tipo de transmisión, el reproductor real que se usa puede variar. Puedes encontrar las versiones exactas de estos reproductores en las notas de la versión del SDK de Google Cast.

A continuación, agrega el siguiente código para interceptar los eventos LOAD y generar un nonce cada vez que el receptor cargue un nuevo objeto MediaInformation:

js/receiver.js

const castContext = cast.framework.CastReceiverContext.getInstance();
const playerManager = castContext.getPlayerManager();

const consentSettings = new goog.cast.pal.ConsentSettings();
// For the correct usage of the allowStorage property, See
// developers.google.com/ad-manager/pal/cast/reference/js/ConsentSettings#allowStorage.
consentSettings.allowStorage = true;

// You need a nonce loader to request your stream's nonceManager. The
// nonceManager provides your nonce. You should reuse the same nonce loader for
// the entire lifecycle of the receiver.
const nonceLoader = new goog.cast.pal.NonceLoader(consentSettings);

// You need a reference to the NonceManager to track when an ad is shown or
// clicked.
let nonceManager;

/**
 * Sends a debug message to the CAF sender.
 *
 * @param {String} message - The message to send
 */
const log = (message) => {
  // Use CastDebugLogger to log a message to the sender. See
  // https://developers.google.com/cast/docs/debugging/cast_debug_logger.
}

/**
 * Stores the nonce manager in the outer scoped variable and retrieves a nonce,
 * so it can be used to build your ad request URL
 *
 * @param {NonceManager} loadedNonceManager - The loaded nonce manager
 */
const buildAdRequest = (loadedNonceManager) => {
  nonceManager = loadedNonceManager;

  const nonce = nonceManager.getNonce();
  log('received nonce:' + nonce);

  // TODO: Set this nonce as the value for the `givn` parameter of your ad
  // request URL. For example:
  // const adRequestURL = 'https://myadserver.com/ads?givn=' + nonce;
}

/**
 * Configures a new nonce request, then requests a nonce.
 *
 * @param {LoadRequestData} loadRequestData - the load request object,
 * which contains the MediaInformation object from the sender. See
 * developers.google.com/cast/docs/reference/web_receiver/cast.framework.messages.LoadRequestData
 * @return {(Promise<LoadRequestData>)} - A Promise to build an ad request.
 */
const handleLoadRequest = (loadRequestData) => {
  // Clear any old nonceManager before loading new media.
  nonceManager = null;

  // See developers.google.com/ad-manager/pal/cast/reference/js/NonceRequest
  // for details about each property. The NonceRequest parameters set here are
  // example parameters. You should set your parameters based on your own app
  // characteristics.
  const nonceRequest = new goog.cast.pal.NonceRequest();
  nonceRequest.adWillAutoPlay = true;
  // A URL describing the video stream.
  nonceRequest.descriptionUrl = 'https://example.com';
  nonceRequest.iconsSupported = true;
  nonceRequest.ppid = 'Sample PPID';
  nonceRequest.sessionId = 'Sample SID';
  nonceRequest.url = loadRequestData.media.contentUrl;
  // The height of the player in physical pixels.
  // For a fullscreen player on a 1080p screen, the video height would be 1080.
  nonceRequest.videoHeight = window.devicePixelRatio * window.screen.height;
  // The width of the player in physical pixels.
  // For a fullscreen player on a 1080p screen, the video width would be 1920.
  nonceRequest.videoWidth = window.devicePixelRatio * window.screen.width;

  return nonceLoader.loadNonceManager(nonceRequest)
    .then(buildAdRequest)
    .catch((e) => {
      log("Error: " + e.message);
    });
};

// Set up the event handler for the LOAD event type.
playerManager.setMessageInterceptor(cast.framework.messages.MessageType.LOAD, handleLoadRequest);

castContext.start();

Cuando realices tu llamada directa de VAST (DVC), establece este 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.

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

Si solicitas y renderizas anuncios de Google, debes renderizar el ícono y la superposición de AdChoices. Para obtener detalles sobre el análisis de la respuesta de VAST y la renderización de íconos, consulta Ícono y superposición de AdChoices.

Realiza un seguimiento de las interacciones con videos

Además de generar un nonce, el SDK de PAL debe recibir notificaciones sobre ciertas interacciones de video. Para hacer un seguimiento de las interacciones con el receptor de Cast, agrega el siguiente código a tu receptor personalizado:

js/receiver.js

const castContext = cast.framework.CastReceiverContext.getInstance();
const playerManager = castContext.getPlayerManager();

const consentSettings = new goog.cast.pal.ConsentSettings();
// For the correct usage of the allowStorage property, See
// developers.google.com/ad-manager/pal/cast/reference/js/ConsentSettings#allowStorage.
consentSettings.allowStorage = true;

// You need a nonce loader to request your stream's nonceManager. The
// nonceManager provides your nonce. You should reuse the same nonce loader for
// the entire lifecycle of the receiver.
const nonceLoader = new goog.cast.pal.NonceLoader(consentSettings);

// You need a reference to the NonceManager for sending ad events.
let nonceManager;

// Track playback status.
let playbackDidStart = false;

...

// Register the start of playback.
playerManager.addEventListener(cast.framework.events.EventType.PLAYING, () => {
  if (playbackDidStart) return;

  playbackDidStart = true;
  if (nonceManager) {
    log('Registered playback start');
    nonceManager.sendPlaybackStart();
  } else {
    log("Error: There is no nonce manager for this media.");
  }
});

// Register any interactions with the player.
const interactionEvents = [
  cast.framework.events.EventType.REQUEST_SEEK,
  cast.framework.events.EventType.REQUEST_STOP,
  cast.framework.events.EventType.REQUEST_PAUSE,
  cast.framework.events.EventType.REQUEST_PLAY,
  cast.framework.events.EventType.REQUEST_SKIP_AD,
  cast.framework.events.EventType.REQUEST_PLAY_AGAIN,
  cast.framework.events.EventType.REQUEST_PLAYBACK_RATE_CHANGE,
  cast.framework.events.EventType.REQUEST_VOLUME_CHANGE,
  cast.framework.events.EventType.REQUEST_USER_ACTION,
  cast.framework.events.EventType.REQUEST_FOCUS_STATE,
];
playerManager.addEventListener(interactionEvents, (interactionEvent) => {
  if (nonceManager) {
    log('Registered interaction: ' + interactionEvent);
    nonceManager.sendAdTouch(interactionEvent);
  } else {
    log("Error: There is no nonce manager for this media.");
  }
});

// Register the end of playback.
playerManager.addEventListener(cast.framework.events.EventType.MEDIA_FINISHED, () => {
  playbackDidStart = false;
  if (nonceManager) {
    log('Registered playback end');
    nonceManager.sendPlaybackEnd();
  } else {
    log("Error: There is no nonce manager for this media.");
  }
});

castContext.start();

(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.

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 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.