شروع کنید

پیش‌نیازها

برای ادغام و آزمایش کردن «کیت توسعه نرم‌افزار PAL برای Cast»، به موارد زیر نیاز دارید:

• برنامه گیرنده برای تولید یک نانس بااستفاده از پیام رهگیری.

• برنامه فرستنده برای راه‌اندازی گیرنده برای بار کردن محتوایی که دربردارنده درخواست آگهی است.

ازآنجایی‌که فقط باید برنامه گیرنده خود را برای ادغام کردن «کیت توسعه نرم‌افزار PAL» به‌روز کنید، می‌توانید از ابزار «فرمان و کنترل پخش محتوا» (CAC) به‌عنوان فرستنده وب برای آزمایش گیرنده خود استفاده کنید.

می‌توانید نمونه را در پایان هر مرحله با ابتدا راه‌اندازی برنامه گیرنده وب در «ابزار CAC» و سپس ایجاد هر درخواست بار کردن اجرا کنید.

تولید مقدار یک‌بارمصرف

«نانس» رشته‌ای رمزگذاری‌شده و یکتا است که PAL ازطریق NonceManager تولید می‌کند. NonceManager توسط روش loadNonceManager NonceLoader تولید می‌شود، براساس تنظیماتی که در NonceRequest گذرانده شده است. برای دیدن برنامه نمونه‌ای که از PAL برای تولید یک nonce استفاده می‌کند، نمونه Cast را از GitHub بارگیری کنید.

هر درخواست جاری‌سازی جدید به یک nonce جدید نیاز دارد. چندین درخواست آگهی در همان جاری‌سازی می‌توانند از همان عدد یک‌بارمصرف استفاده کنند. برای تولید یک نانس بااستفاده از «کیت توسعه نرم‌افزار PAL»، ابتدا یک برنامه گیرنده وب سفارشی‌سازی‌شده ایجاد کنید و کد زیر را اضافه کنید:

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» است. بسته به نوع جاری‌سازی، پخش‌کننده واقعی مورد استفاده می‌تواند متفاوت باشد. می‌توانید نسخه‌های دقیق این پخش‌کننده‌ها را در کیت توسعه نرم‌افزار Google Cast یادداشت‌های انتشار پیدا کنید.

سپس، کد زیر را اضافه کنید تا رویدادهای LOAD را رهگیری کنید و هر بار که گیرنده 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)، این مقدار یک‌بارمصرف را به‌عنوان مقدار در پارامتر givn تنظیم کنید. «نانس» برای نشانی وب ایمن است؛ نیازی نیست آن را کدبندی نشانی وب کنید.

احتیاط: اگر قبلاً بااستفاده از پارامتر paln یک نانس ارائه کرده‌اید، به‌شدت توصیه می‌شود به givn انتقال دهید و ارسال paln را متوقف کنید. اگر هر دو پارامتر گنجانده شوند، رفتار نامشخصی درباره اینکه از کدام شماره یک‌بارمصرف استفاده شود وجود دارد.

اگر از Google درخواست آگهی می‌کنید و آگهی‌ها را ارائه می‌کنید، باید نماد و رونهاد AdChoices را ارائه کنید. برای جزئیات مربوط به تجزیه پاسخ VAST و پرداز کردن نمادها، به نماد و رونهاد AdChoices مراجعه کنید.

پیگیری تعامل‌های ویدیو

علاوه‌بر تولید یک نانس، «کیت توسعه نرم‌افزار PAL» باید در تعاملات ویدیویی خاصی مطلع شود. برای ردیابی تعاملات با گیرنده 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» ازطریق سرورهای واسطه شما و سپس به Google Ad Manager منتقل می‌شود. این کار باعث بهتر شدن درآمدزایی ازطریق Google Ad Manager می‌شود.

توجه: اگر از چند راهکار طرف سوم استفاده می‌کنید، برای مثال، سرور SSAI طرف سوم که سرور آگهی طرف سوم دیگری را فرا می‌خواند، باید مطمئن شوید که مقدار یک‌بارمصرف رمزگذاری‌شده «کیت توسعه نرم‌افزار» PAL به هر طرف سوم ارسال می‌شود.

سرور آگهی طرف سوم خود را پیکربندی کنید تا مقدار یک‌بارمصرف را در درخواست سرور به 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%%، پشتیبانی کند و آن را با پارامتر پُرسمان یک‌بارمصرف که در مرحله قبلی ارائه کردید جایگزین کند. اطلاعات بیشتر درباره نحوه انجام این کار باید در اسناد سرور آگهی طرف سوم دردسترس باشد.