Inizia

Prerequisiti

Per integrare e testare l'SDK PAL per Cast, devi disporre di quanto segue:

Poiché devi aggiornare solo l'app ricevitore per integrare l'SDK PAL, puoi utilizzare lo strumento di controllo e comando di Cast (CAC) come mittente web per testare il ricevitore.

Puoi eseguire l'esempio alla fine di ogni passaggio avviando l'app ricevitore web nello strumento CAC, quindi effettuando qualsiasi richiesta di caricamento.

Genera nonce

Un "nonce" è una singola stringa criptata generata da PAL tramite NonceManager. Il NonceManager viene generato dal metodo loadNonceManager di NonceLoader, in base alle impostazioni trasmesse in un NonceRequest. Per visualizzare un'app di esempio che utilizza PAL per generare un nonce, scarica l'esempio di Cast da GitHub.

Ogni nuova richiesta di stream richiede un nuovo nonce. Più richieste di annuncio all'interno dello stesso stream possono utilizzare lo stesso nonce. Per generare un nonce utilizzando l'SDK PAL, prima crea un'app ricevitore web personalizzata e aggiungi il seguente codice:

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>

L'elemento <cast-media-player> rappresenta l'UI del player integrato fornita dall'API Cast Web Receiver. A seconda del tipo di stream, il player effettivo utilizzato può variare. Puoi trovare le versioni esatte di questi player nelle note di rilascio dell'SDK Google Cast.

Quindi, aggiungi il seguente codice per intercettare gli eventi LOAD e generare un nonce ogni volta che il ricevitore carica un nuovo oggetto 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();

Quando effettui la chiamata VAST diretta (DVC), imposta questo nonce come valore del parametro givn. Il nonce è sicuro per l'URL, quindi non è necessario codificarlo.

Se richiedi e visualizzi annunci di Google, devi visualizzare l'icona e l'overlay AdChoices. Per informazioni dettagliate sull'analisi della risposta VAST e sul rendering delle icone, consulta Icona e overlay Scegli Tu!.

Monitorare le interazioni video

Oltre a generare un nonce, l'SDK PAL deve ricevere una notifica in caso di determinate interazioni con i video. Per monitorare le interazioni con il ricevitore Cast, aggiungi il seguente codice al ricevitore personalizzato:

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();

(Facoltativo) Inviare indicatori di Google Ad Manager tramite ad server di terze parti

Configura la richiesta del server pubblicitario di terze parti per Ad Manager. Dopo aver completato i seguenti passaggi, il parametro nonce si propaga dall'SDK PAL, attraverso i server intermediari, fino a Google Ad Manager. Ciò consente una migliore monetizzazione tramite Google Ad Manager.

Configura l'ad server di terze parti in modo che includa il nonce nella richiesta del server ad Ad Manager. Ecco un esempio di tag annuncio configurato all'interno dell'ad server di terze parti:

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

Per maggiori dettagli, consulta la guida all'implementazione lato server di Google Ad Manager.

Ad Manager cerca givn= per identificare il valore nonce. L'ad server di terze parti deve supportare una macro propria, ad esempio %%custom_key_for_google_nonce%%, e sostituirla con il parametro di query nonce che hai fornito nel passaggio precedente. Maggiori informazioni su come eseguire questa operazione dovrebbero essere disponibili nella documentazione del server pubblicitario di terze parti.