开始使用

前提条件

如需集成和测试 Cast 的 PAL SDK，您需要满足以下条件：

由于您只需更新接收器应用即可集成 PAL SDK，因此可以使用 Cast Command and Control (CAC) Tool 作为 Web 发送器来测试接收器。

您可以在每个步骤结束时运行示例，方法是先在 CAC 工具中启动 Web 接收器应用，然后发出任意加载请求。

生成 nonce

“nonce”是 PAL 通过 NonceManager 生成的单个加密字符串。NonceManager 由 NonceLoader 的 loadNonceManager 方法根据 NonceRequest 中传递的设置生成。如需查看使用 PAL 生成 Nonce 的示例应用，请从 GitHub 下载 Cast 示例。

每个新的流请求都需要一个新的随机数。同一视频流中的多个广告请求可以使用相同的随机数。如需使用 PAL SDK 生成 Nonce，请先创建自定义 Web 接收器应用，然后添加以下代码：

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>

<cast-media-player> 元素表示由 Cast Web Receiver API 提供的内置播放器界面。根据直播类型，实际使用的播放器可能会有所不同。您可以在 Google Cast SDK 版本说明中找到这些播放器的确切版本。

接下来，添加以下代码以拦截 LOAD 事件，并在每次接收器加载新的 MediaInformation 对象时生成 Nonce：

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

在进行直接 VAST 调用 (DVC) 时，请将此 Nonce 设置为 givn 参数的值。nonce 适合包含在网址中，因此您无需对其进行网址编码。

如果您要请求和呈现 Google 广告，则必须呈现AdChoices图标和叠加层。如需详细了解如何解析 VAST 响应和呈现图标，请参阅“广告选项”图标和叠加层。

跟踪视频互动

除了生成 Nonce 之外，PAL SDK 还需要在发生某些视频互动时收到通知。如需跟踪与 Cast 接收器的互动，请将以下代码添加到自定义接收器：

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

（可选）通过第三方广告服务器发送 Google Ad Manager 信号

配置第三方广告服务器向 Ad Manager 发送的请求。完成以下步骤后，随机数参数会从 PAL SDK 传播到您的中介服务器，然后再传播到 Google Ad Manager。这样一来，您就可以通过 Google Ad Manager 更好地创收。

配置第三方广告服务器，以在服务器向 Ad Manager 发出的请求中包含随机数。以下是第三方广告服务器内配置的广告代码示例：

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

如需了解详情，请参阅 Google Ad Manager 服务器端实现指南。

Ad Manager 会查找 givn= 以确定随机数的值。第三方广告服务器需要支持自己的某个宏（例如 %%custom_key_for_google_nonce%%），并将其替换为您在上一步中提供的随机数查询参数。如需详细了解如何实现此目的，请参阅第三方广告服务器的文档。