תחילת עבודה

דרישות מוקדמות

כדי לשלב את PAL SDK ל-Cast ולבדוק אותו, צריך:

מכיוון שצריך לעדכן רק את אפליקציית המקלט כדי לשלב את PAL SDK, אפשר להשתמש בכלי Cast Command and Control (CAC) בתור שולח אינטרנט כדי לבדוק את המקלט.

אפשר להריץ את הדוגמה בסוף כל שלב. לשם כך, קודם מפעילים את אפליקציית מקלט האינטרנט בכלי CAC, ואז שולחים בקשת טעינה.

יצירת צופן חד-פעמי (nonce)

‫Nonce הוא מחרוזת מוצפנת יחידה שנוצרת על ידי PAL באמצעות NonceManager. הערך של NonceManager נוצר על ידי השיטה loadNonceManager של NonceLoader, על סמך ההגדרות שמועברות ב-NonceRequest. כדי לראות אפליקציה לדוגמה שמשתמשת ב-PAL כדי ליצור צופן חד-פעמי (nonce), מורידים את הדוגמה של Cast מ-GitHub.

כל בקשה חדשה להזרמת נתונים דורשת ערך nonce חדש. יכול להיות שיהיו כמה בקשות למודעות באותו הזרם עם אותו ערך nonce. כדי ליצור ערך חד-פעמי באמצעות PAL SDK, קודם צריך ליצור אפליקציית מקלט אינטרנט בהתאמה אישית ולהוסיף את הקוד הבא:

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 וליצור צופן חד-פעמי (nonce) בכל פעם שהמקלט טוען אובייקט 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();

כשמבצעים קריאה ישירה של VAST ‏ (DVC), מגדירים את ה-nonce הזה כערך בפרמטר givn. ה-nonce בטוח לשימוש בכתובת URL, כך שאין צורך לבצע קידוד URL.

אם אתם שולחים בקשות להצגת מודעות מ-Google ומציגים אותן, אתם חייבים להציג את הסמל ואת שכבת העל של AdChoices. פרטים על ניתוח תגובת VAST ועיבוד סמלים מופיעים במאמר בנושא הסמל של AdChoices ושכבת-על.

מעקב אחרי אינטראקציות עם סרטונים

בנוסף ליצירת צופן חד-פעמי (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. אחרי שתשלימו את השלבים הבאים, הפרמטר nonce יועבר מ-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= כדי לזהות את ערך ה-nonce. שרת הפרסום של הצד השלישי צריך לתמוך במאקרו משלו, כמו %%custom_key_for_google_nonce%%, ולהחליף אותו בפרמטר השאילתה של הצופן החד-פעמי שסיפקתם בשלב הקודם. מידע נוסף על האופן שבו אפשר לעשות את זה אמור להיות זמין במסמכי התיעוד של שרת המודעות של הצד השלישי.