Débuter

Prérequis

Pour intégrer et tester le SDK PAL pour Cast, vous avez besoin des éléments suivants :

Comme vous n'avez besoin de mettre à jour votre application réceptrice que pour intégrer le SDK PAL, vous pouvez utiliser l'outil Cast Command and Control (CAC) comme émetteur Web pour tester votre récepteur.

Vous pouvez exécuter l'exemple à la fin de chaque étape en lançant d'abord votre application Web Receiver dans l'outil CAC, puis en effectuant une demande de chargement.

Générer un nonce

Un "nonce" est une chaîne chiffrée unique générée par PAL via NonceManager. NonceManager est généré par la méthode loadNonceManager de NonceLoader, en fonction des paramètres transmis dans un NonceRequest. Pour voir une application exemple qui utilise PAL pour générer un nonce, téléchargez l'exemple Cast depuis GitHub.

Chaque nouvelle demande de flux nécessite un nouveau nonce. Plusieurs demandes d'annonces dans le même flux peuvent utiliser le même nonce. Pour générer un nonce à l'aide du SDK PAL, commencez par créer une application Web Receiver personnalisée et ajoutez le code suivant :

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'élément <cast-media-player> représente l'UI du lecteur intégrée fournie par l'API Cast Web Receiver. Le lecteur utilisé peut varier en fonction du type de flux. Vous trouverez les versions exactes de ces lecteurs dans les notes de version du SDK Google Cast.

Ajoutez ensuite le code suivant pour intercepter les événements LOAD et générer un nonce chaque fois que le récepteur charge un nouvel objet 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();

Lorsque vous effectuez votre appel VAST direct (DVC), définissez ce nonce comme valeur du paramètre givn. Le nonce est adapté aux URL. Vous n'avez pas besoin de l'encoder en URL.

Si vous demandez et affichez des annonces Google, vous devez afficher l'icône et le calque AdChoices. Pour en savoir plus sur l'analyse de la réponse VAST et l'affichage des icônes, consultez Icône et superposition Choisir sa pub.

Suivre les interactions vidéo

En plus de générer un nonce, le SDK PAL doit être informé de certaines interactions vidéo. Pour suivre les interactions avec le récepteur Cast, ajoutez le code suivant à votre récepteur personnalisé :

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

(Facultatif) Envoyer des signaux Google Ad Manager via des ad servers tiers

Configurez la demande de l'ad server tiers pour Ad Manager. Une fois les étapes suivantes effectuées, le paramètre nonce se propage du SDK PAL à Google Ad Manager, en passant par vos serveurs intermédiaires. Cela permet une meilleure monétisation grâce à Google Ad Manager.

Configurez votre ad server tiers pour inclure le nonce dans la requête du serveur envoyée à Ad Manager. Voici un exemple de tag d'emplacement publicitaire configuré dans l'ad server tiers :

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

Pour en savoir plus, consultez le guide d'implémentation côté serveur de Google Ad Manager.

Ad Manager recherche givn= pour identifier la valeur nonce. L'ad server tiers doit accepter l'une de ses propres macros, comme %%custom_key_for_google_nonce%%, et la remplacer par le paramètre de requête nonce que vous avez fourni à l'étape précédente. Pour en savoir plus, consultez la documentation de l'ad server tiers.