این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

ویژگی های اصلی را به گیرنده وب سفارشی خود اضافه کنید

این صفحه شامل قطعه کدها و توضیحاتی در مورد ویژگی‌های موجود برای یک برنامه گیرنده وب سفارشی است.

یک عنصر cast-media-player که رابط کاربری پخش‌کننده‌ی داخلی ارائه شده توسط گیرنده‌ی وب را نشان می‌دهد.
استایل‌بندی سفارشی شبیه به CSS برای عنصر cast-media-player جهت استایل‌بندی عناصر مختلف رابط کاربری مانند background-image ، splash-image و font-family .
یک عنصر اسکریپت برای بارگذاری چارچوب گیرنده وب.
کد جاوا اسکریپت برای رهگیری پیام‌ها و مدیریت رویدادها.
صف پخش خودکار.
گزینه‌هایی برای پیکربندی پخش.
گزینه‌هایی برای تنظیم زمینه گیرنده وب.
گزینه‌هایی برای تنظیم دستوراتی که توسط برنامه گیرنده وب پشتیبانی می‌شوند.
یک فراخوانی جاوا اسکریپت برای شروع برنامه گیرنده وب.

پیکربندی و گزینه‌های برنامه

پیکربندی برنامه

CastReceiverContext بیرونی‌ترین کلاسی است که در اختیار توسعه‌دهنده قرار می‌گیرد و بارگذاری کتابخانه‌های زیربنایی را مدیریت کرده و مقداردهی اولیه‌ی Web Receiver SDK را انجام می‌دهد. SDK رابط‌های برنامه‌نویسی کاربردی (API) ارائه می‌دهد که به توسعه‌دهندگان برنامه اجازه می‌دهد SDK را از طریق CastReceiverOptions پیکربندی کنند. این پیکربندی‌ها یک بار در هر اجرای برنامه ارزیابی می‌شوند و هنگام تنظیم پارامتر اختیاری در فراخوانی start ، به SDK ارسال می‌شوند.

مثال زیر نحوه‌ی لغو رفتار پیش‌فرض برای تشخیص فعال بودن اتصال فرستنده را نشان می‌دهد. هنگامی که گیرنده‌ی وب نتوانسته باشد برای مدت زمان maxInactivity ثانیه با فرستنده ارتباط برقرار کند، یک رویداد SENDER_DISCONNECTED ارسال می‌شود. پیکربندی زیر این زمان وقفه را لغو می‌کند. این می‌تواند هنگام اشکال‌زدایی مشکلات مفید باشد زیرا مانع از بسته شدن جلسه‌ی اشکال‌زدای از راه دور کروم توسط برنامه‌ی گیرنده‌ی وب در زمانی که هیچ فرستنده‌ی متصلی در حالت IDLE وجود ندارد، می‌شود.

const context = cast.framework.CastReceiverContext.getInstance();
const options = new cast.framework.CastReceiverOptions();
options.maxInactivity = 3600; // Development only
context.start(options);

پخش کننده را پیکربندی کنید

هنگام بارگذاری محتوا، Web Receiver SDK راهی برای پیکربندی متغیرهای پخش مانند اطلاعات DRM ، پیکربندی‌های retry و کنترل‌کننده‌های درخواست با استفاده از cast.framework.PlaybackConfig ارائه می‌دهد. این اطلاعات توسط PlayerManager مدیریت می‌شود و در زمان ایجاد پخش‌کننده‌ها ارزیابی می‌شود. پخش‌کننده‌ها هر بار که یک بارگذاری جدید به Web Receiver SDK ارسال می‌شود، ایجاد می‌شوند. تغییرات در PlaybackConfig پس از ایجاد پخش‌کننده در بارگذاری محتوای بعدی ارزیابی می‌شوند. SDK روش‌های زیر را برای اصلاح PlaybackConfig ارائه می‌دهد.

CastReceiverOptions.playbackConfig برای لغو گزینه‌های پیکربندی پیش‌فرض هنگام مقداردهی اولیه CastReceiverContext .
PlayerManager.getPlaybackConfig() برای دریافت پیکربندی فعلی.
PlayerManager.setPlaybackConfig() برای لغو پیکربندی فعلی. این تنظیم برای تمام بارگذاری‌های بعدی یا تا زمانی که دوباره لغو شود، اعمال می‌شود.
PlayerManager.setMediaPlaybackInfoHandler() برای اعمال تنظیمات اضافی فقط برای آیتم رسانه‌ای که در بالای پیکربندی‌های فعلی بارگذاری می‌شود. این هندلر درست قبل از ایجاد بازیکن فراخوانی می‌شود. تغییرات ایجاد شده در اینجا دائمی نیستند و در کوئری‌های getPlaybackConfig() لحاظ نمی‌شوند. وقتی آیتم رسانه‌ای بعدی بارگذاری می‌شود، این هندلر دوباره فراخوانی می‌شود.

مثال زیر نحوه تنظیم PlaybackConfig هنگام مقداردهی اولیه CastReceiverContext را نشان می‌دهد. این پیکربندی درخواست‌های خروجی برای دریافت مانیفست‌ها را لغو می‌کند. این هندلر مشخص می‌کند که درخواست‌های CORS Access-Control باید با استفاده از اعتبارنامه‌هایی مانند کوکی‌ها یا هدرهای مجوز انجام شوند.

const playbackConfig = new cast.framework.PlaybackConfig();
playbackConfig.manifestRequestHandler = requestInfo => {
  requestInfo.withCredentials = true;
};
context.start({playbackConfig: playbackConfig});

مثال زیر نحوه‌ی لغو PlaybackConfig با استفاده از getter و setter ارائه شده در PlayerManager نشان می‌دهد. این تنظیم، پخش‌کننده را طوری پیکربندی می‌کند که پس از بارگذاری ۱ بخش، پخش محتوا را از سر بگیرد.

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
const playbackConfig = (Object.assign(
            new cast.framework.PlaybackConfig(), playerManager.getPlaybackConfig()));
playbackConfig.autoResumeNumberOfSegments = 1;
playerManager.setPlaybackConfig(playbackConfig);

مثال زیر نحوه‌ی لغو PlaybackConfig برای یک درخواست بارگذاری خاص با استفاده از کنترل‌کننده‌ی اطلاعات پخش رسانه را نشان می‌دهد. این کنترل‌کننده، متد getLicenseUrlForMedia پیاده‌سازی‌شده توسط برنامه را فراخوانی می‌کند تا licenseUrl از contentId آیتم فعلی دریافت کند.

playerManager.setMediaPlaybackInfoHandler((loadRequestData, playbackConfig) => {
  const mediaInformation = loadRequestData.media;
  playbackConfig.licenseUrl = getLicenseUrlForMedia(mediaInformation.contentId);

  return playbackConfig;
});

شنونده رویداد

کیت توسعه نرم‌افزاری Web Receiver به برنامه Web Receiver شما اجازه می‌دهد تا رویدادهای بازیکن را مدیریت کند. شنونده رویداد، پارامتر cast.framework.events.EventType (یا آرایه‌ای از این پارامترها) را دریافت می‌کند که رویداد(هایی) را که باید شنونده را فعال کنند، مشخص می‌کند. آرایه‌های از پیش پیکربندی شده cast.framework.events.EventType که برای اشکال‌زدایی مفید هستند را می‌توان در cast.framework.events.category یافت. پارامتر رویداد، اطلاعات بیشتری در مورد رویداد ارائه می‌دهد.

برای مثال، اگر می‌خواهید بدانید چه زمانی یک تغییر mediaStatus منتشر می‌شود، می‌توانید از منطق زیر برای مدیریت این رویداد استفاده کنید:

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
playerManager.addEventListener(
    cast.framework.events.EventType.MEDIA_STATUS, (event) => {
      // Write your own event handling code, for example
      // using the event.mediaStatus value
});

رهگیری پیام

کیت توسعه نرم‌افزاری گیرنده وب (Web Receiver SDK) به برنامه گیرنده وب شما اجازه می‌دهد تا پیام‌ها را رهگیری کرده و کد سفارشی را روی آن پیام‌ها اجرا کند. رهگیر پیام، پارامتر cast.framework.messages.MessageType را دریافت می‌کند که مشخص می‌کند چه نوع پیامی باید رهگیری شود.

رهگیر باید درخواست اصلاح‌شده یا Promise ای را که با مقدار درخواست اصلاح‌شده حل می‌شود، برگرداند. برگرداندن null از فراخوانی مدیریت‌کننده‌ی پیش‌فرض پیام جلوگیری می‌کند. برای جزئیات بیشتر به بارگذاری رسانه مراجعه کنید.

برای مثال، اگر می‌خواهید داده‌های درخواست بارگذاری را تغییر دهید، می‌توانید از منطق زیر برای رهگیری و اصلاح آن استفاده کنید:

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      const error = new cast.framework.messages.ErrorData(
                      cast.framework.messages.ErrorType.LOAD_FAILED);
      if (!loadRequestData.media) {
        error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
        return error;
      }

      if (!loadRequestData.media.entity) {
        return loadRequestData;
      }

      return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
                                          loadRequestData.credentials)
        .then(asset => {
          if (!asset) {
            throw cast.framework.messages.ErrorReason.INVALID_REQUEST;
          }

          loadRequestData.media.contentUrl = asset.url;
          loadRequestData.media.metadata = asset.metadata;
          loadRequestData.media.tracks = asset.tracks;
          return loadRequestData;
        }).catch(reason => {
          error.reason = reason; // cast.framework.messages.ErrorReason
          return error;
        });
    });

context.start();

مدیریت خطا

وقتی در message interceptor خطایی رخ می‌دهد، برنامه‌ی Web Receiver شما باید یک cast.framework.messages.ErrorType و cast.framework.messages.ErrorReason مناسب را برگرداند.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      const error = new cast.framework.messages.ErrorData(
                      cast.framework.messages.ErrorType.LOAD_CANCELLED);
      if (!loadRequestData.media) {
        error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
        return error;
      }

      ...

      return fetchAssetAndAuth(loadRequestData.media.entity,
                               loadRequestData.credentials)
        .then(asset => {
          ...
          return loadRequestData;
        }).catch(reason => {
          error.reason = reason; // cast.framework.messages.ErrorReason
          return error;
        });
    });

رهگیری پیام در مقابل شنونده رویداد

برخی از تفاوت‌های کلیدی بین رهگیری پیام و شنونده رویداد به شرح زیر است:

شنونده‌ی رویداد (event listener) به شما اجازه نمی‌دهد داده‌های درخواست را تغییر دهید.
یک شنونده رویداد (event listener) بهترین استفاده برای راه‌اندازی تجزیه و تحلیل یا یک تابع سفارشی است.

playerManager.addEventListener(cast.framework.events.category.CORE,
    event => {
        console.log(event);
    });

رهگیری پیام به شما امکان می‌دهد به یک پیام گوش دهید، آن را رهگیری کنید و داده‌های درخواست را تغییر دهید.
رهگیری پیام بهترین روش برای مدیریت منطق سفارشی در رابطه با داده‌های درخواست است.

بارگیری رسانه

MediaInformation ویژگی‌های متعددی برای بارگذاری رسانه در پیام cast.framework.messages.MessageType.LOAD از جمله entity ، contentUrl و contentId ارائه می‌دهد.

entity ، ویژگی پیشنهادی برای استفاده در پیاده‌سازی شما برای هر دو برنامه فرستنده و گیرنده است. این ویژگی یک URL لینک عمیق است که می‌تواند یک لیست پخش یا محتوای رسانه باشد. برنامه شما باید این URL را تجزیه کرده و حداقل یکی از دو فیلد دیگر را پر کند.
contentUrl مربوط به URL قابل پخشی است که پخش‌کننده برای بارگذاری محتوا از آن استفاده خواهد کرد. برای مثال، این URL می‌تواند به یک مانیفست DASH اشاره کند.
contentId می‌تواند یک URL محتوای قابل پخش (مشابه ویژگی contentUrl ) یا یک شناسه منحصر به فرد برای محتوا یا لیست پخشی که بارگذاری می‌شود باشد. اگر از این ویژگی به عنوان شناسه استفاده می‌کنید، برنامه شما باید یک URL قابل پخش را در contentUrl قرار دهد.

پیشنهاد این است که از entity برای ذخیره شناسه واقعی یا پارامترهای کلیدی و contentUrl برای URL رسانه استفاده شود. مثالی از این مورد در قطعه کد زیر نشان داده شده است که در آن entity در درخواست LOAD وجود دارد و contentUrl قابل پخش بازیابی می‌شود:

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      ...

      if (!loadRequestData.media.entity) {
        // Copy the value from contentId for legacy reasons if needed
        loadRequestData.media.entity = loadRequestData.media.contentId;
      }

      return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
                                          loadRequestData.credentials)
        .then(asset => {
          loadRequestData.media.contentUrl = asset.url;
          ...
          return loadRequestData;
        });
    });

قابلیت‌های دستگاه

متد getDeviceCapabilities اطلاعات دستگاه مربوط به دستگاه Cast متصل و دستگاه ویدیویی یا صوتی متصل به آن را ارائه می‌دهد. متد getDeviceCapabilities اطلاعات پشتیبانی برای دستیار گوگل، بلوتوث و دستگاه‌های نمایشگر و صوتی متصل را ارائه می‌دهد.

این متد یک شیء برمی‌گرداند که می‌توانید با ارسال یکی از enumهای مشخص شده، از آن پرس‌وجو کنید تا قابلیت دستگاه آن enum را دریافت کنید. enumها در cast.framework.system.DeviceCapabilities تعریف شده‌اند.

این مثال بررسی می‌کند که آیا دستگاه گیرنده وب قادر به پخش HDR و DolbyVision (DV) به ترتیب با کلیدهای IS_HDR_SUPPORTED و IS_DV_SUPPORTED است یا خیر.

const context = cast.framework.CastReceiverContext.getInstance();
context.addEventListener(cast.framework.system.EventType.READY, () => {
  const deviceCapabilities = context.getDeviceCapabilities();
  if (deviceCapabilities &&
      deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED]) {
    // Write your own event handling code, for example
    // using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED] value
  }
  if (deviceCapabilities &&
      deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED]) {
    // Write your own event handling code, for example
    // using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED] value
  }
});
context.start();

مدیریت تعامل کاربر

کاربر می‌تواند از طریق برنامه‌های فرستنده (وب، اندروید و iOS)، دستورات صوتی در دستگاه‌های دارای دستیار، کنترل‌های لمسی در نمایشگرهای هوشمند و کنترل‌های از راه دور در دستگاه‌های تلویزیون اندروید با برنامه گیرنده وب شما تعامل داشته باشد. Cast SDK رابط‌های برنامه‌نویسی مختلفی را ارائه می‌دهد تا به برنامه گیرنده وب اجازه دهد این تعاملات را مدیریت کند، رابط کاربری برنامه را از طریق حالت‌های عملکرد کاربر به‌روزرسانی کند و به صورت اختیاری تغییرات را برای به‌روزرسانی هرگونه سرویس backend ارسال کند.

دستورات رسانه‌ای پشتیبانی‌شده

وضعیت کنترل‌های رابط کاربری توسط MediaStatus.supportedMediaCommands برای کنترل‌کننده‌های توسعه‌یافته فرستنده iOS و اندروید، برنامه‌های گیرنده و کنترل از راه دور که روی دستگاه‌های لمسی اجرا می‌شوند و برنامه‌های گیرنده در دستگاه‌های تلویزیون اندروید هدایت می‌شوند. هنگامی که یک Command بیتی خاص در این ویژگی فعال می‌شود، دکمه‌های مربوط به آن عمل فعال می‌شوند. اگر مقداری تنظیم نشود، دکمه غیرفعال می‌شود. این مقادیر را می‌توان در گیرنده وب به روش‌های زیر تغییر داد:

استفاده از PlayerManager.setSupportedMediaCommands برای تنظیم Commands خاص
افزودن یک دستور جدید با استفاده از addSupportedMediaCommands
حذف یک دستور موجود با استفاده از removeSupportedMediaCommands .

playerManager.setSupportedMediaCommands(cast.framework.messages.Command.SEEK |
  cast.framework.messages.Command.PAUSE);

وقتی گیرنده، به‌روزرسانی MediaStatus را آماده می‌کند، تغییرات در ویژگی supportedMediaCommands اعمال خواهد شد. وقتی وضعیت منتشر می‌شود، برنامه‌های فرستنده متصل، دکمه‌های رابط کاربری خود را بر اساس آن به‌روزرسانی می‌کنند.

برای اطلاعات بیشتر در مورد دستورات رسانه‌ای پشتیبانی‌شده و دستگاه‌های لمسی، به راهنمای Accessing UI controls مراجعه کنید.

مدیریت وضعیت‌های عملکرد کاربر

وقتی کاربران با رابط کاربری تعامل می‌کنند یا دستورات صوتی ارسال می‌کنند، می‌توانند پخش محتوا و ویژگی‌های مربوط به آیتم در حال پخش را کنترل کنند. درخواست‌هایی که پخش را کنترل می‌کنند، به طور خودکار توسط SDK مدیریت می‌شوند. درخواست‌هایی که ویژگی‌های آیتم در حال پخش فعلی را تغییر می‌دهند، مانند دستور LIKE ، نیاز دارند که برنامه گیرنده آنها را مدیریت کند. SDK مجموعه‌ای از APIها را برای مدیریت این نوع درخواست‌ها ارائه می‌دهد. برای پشتیبانی از این درخواست‌ها، موارد زیر باید انجام شود:

هنگام بارگذاری یک آیتم رسانه‌ای، تنظیمات کاربر در بخش MediaInformation userActionStates مطابق با تنظیمات کاربر تنظیم کنید.
پیام‌های USER_ACTION را رهگیری کرده و اقدام درخواستی را تعیین کنید.
برای به‌روزرسانی رابط کاربری MediaInformation UserActionState به‌روزرسانی کنید.

قطعه کد زیر درخواست LOAD را رهگیری کرده و MediaInformation مربوط به LoadRequestData را پر می‌کند. در این حالت، کاربر محتوایی که در حال بارگذاری است را می‌پسندد.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      const userActionLike = new cast.framework.messages.UserActionState(
          cast.framework.messages.UserAction.LIKE);
      loadRequestData.media.userActionStates = [userActionLike];

      return loadRequestData;
    });

قطعه کد زیر پیام USER_ACTION را رهگیری می‌کند و فراخوانی backend را با تغییر درخواستی مدیریت می‌کند. سپس فراخوانی برای به‌روزرسانی UserActionState در گیرنده انجام می‌دهد.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.USER_ACTION,
  (userActionRequestData) => {
    // Obtain the media information of the current content to associate the action to.
    let mediaInfo = playerManager.getMediaInformation();

    // If there is no media info return an error and ignore the request.
    if (!mediaInfo) {
        console.error('Not playing media, user action is not supported');
        return new cast.framework.messages.ErrorData(messages.ErrorType.BAD_REQUEST);
    }

    // Reach out to backend services to store user action modifications. See sample below.
    return sendUserAction(userActionRequestData, mediaInfo)

    // Upon response from the backend, update the client's UserActionState.
    .then(backendResponse => updateUserActionStates(backendResponse))

    // If any errors occurred in the backend return them to the cast receiver.
    .catch((error) => {
      console.error(error);
      return error;
    });
});

قطعه کد زیر فراخوانی یک سرویس backend را شبیه‌سازی می‌کند. این تابع UserActionRequestData را بررسی می‌کند تا نوع تغییری را که کاربر درخواست کرده است، ببیند و فقط در صورتی که این اقدام توسط backend پشتیبانی شود، فراخوانی شبکه را انجام می‌دهد.

function sendUserAction(userActionRequestData, mediaInfo) {
  return new Promise((resolve, reject) => {
    switch (userActionRequestData.userAction) {
      // Handle user action changes supported by the backend.
      case cast.framework.messages.UserAction.LIKE:
      case cast.framework.messages.UserAction.DISLIKE:
      case cast.framework.messages.UserAction.FOLLOW:
      case cast.framework.messages.UserAction.UNFOLLOW:
      case cast.framework.messages.UserAction.FLAG:
      case cast.framework.messages.UserAction.SKIP_AD:
        let backendResponse = {userActionRequestData: userActionRequestData, mediaInfo: mediaInfo};
        setTimeout(() => {resolve(backendResponse)}, 1000);
        break;
      // Reject all other user action changes.
      default:
        reject(
          new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType.INVALID_REQUEST));
    }
  });
}

قطعه کد زیر UserActionRequestData را دریافت کرده و UserActionState از MediaInformation اضافه یا حذف می‌کند. به‌روزرسانی UserActionState از MediaInformation وضعیت دکمه‌ای را که با اقدام درخواستی مرتبط است، تغییر می‌دهد. این تغییر در رابط کاربری کنترل‌های نمایشگر هوشمند، برنامه کنترل از راه دور و رابط کاربری تلویزیون اندروید منعکس می‌شود. همچنین از طریق پیام‌های خروجی MediaStatus برای به‌روزرسانی رابط کاربری کنترل‌کننده توسعه‌یافته برای فرستنده‌های iOS و اندروید منتشر می‌شود.

function updateUserActionStates(backendResponse) {
  // Unwrap the backend response.
  let mediaInfo = backendResponse.mediaInfo;
  let userActionRequestData = backendResponse.userActionRequestData;

  // If the current item playing has changed, don't update the UserActionState for the current item.
  if (playerManager.getMediaInformation().entity !== mediaInfo.entity) {
    return;
  }

  // Check for existing userActionStates in the MediaInformation.
  // If none, initialize a new array to populate states with.
  let userActionStates = mediaInfo.userActionStates || [];

  // Locate the index of the UserActionState that will be updated in the userActionStates array.
  let index = userActionStates.findIndex((currUserActionState) => {
    return currUserActionState.userAction == userActionRequestData.userAction;
  });

  if (userActionRequestData.clear) {
    // Remove the user action state from the array if cleared.
    if (index >= 0) {
      userActionStates.splice(index, 1);
    }
    else {
      console.warn("Could not find UserActionState to remove in MediaInformation");
    }
  } else {
    // Add the UserActionState to the array if enabled.
    userActionStates.push(
      new cast.framework.messages.UserActionState(userActionRequestData.userAction));
  }

  // Update the UserActionState array and set the new MediaInformation
  mediaInfo.userActionStates = userActionStates;
  playerManager.setMediaInformation(mediaInfo, true);
  return;
}

دستورات صوتی

دستورات رسانه‌ای زیر در حال حاضر در Web Receiver SDK برای دستگاه‌های دارای دستیار صوتی پشتیبانی می‌شوند. پیاده‌سازی‌های پیش‌فرض این دستورات در cast.framework.PlayerManager یافت می‌شوند.

فرمان	توضیحات
بازی	پخش یا از حالت مکث شده پخش را از سر بگیرید.
مکث	محتوای در حال پخش را متوقف کنید.
قبلی	به مورد رسانه قبلی در صف رسانه خود بروید.
بعدی	به مورد رسانه بعدی در صف رسانه خود بروید.
توقف	رسانه در حال پخش را متوقف کنید.
تکرار هیچ کدام	تکرار موارد رسانه‌ای در صف را پس از اتمام پخش آخرین مورد در صف غیرفعال کنید.
تکرار تک آهنگ	پخش رسانه فعلی را به طور نامحدود تکرار کنید.
تکرار همه	به محض پخش آخرین آیتم در صف، تمام آیتم‌های موجود در صف تکرار می‌شوند.
همه را تکرار کنید و به صورت تصادفی تغییر دهید	به محض اینکه پخش آخرین آیتم در صف تمام شد، صف را بُر بزنید و پخش تمام آیتم‌های موجود در صف را تکرار کنید.
تصادفی	موارد رسانه‌ای را در صف رسانه خود جابجا کنید. نکته: همچنین می‌توانید قبل از پخش، با استفاده از پرچم `shuffle` ، رسانه‌ها را به صورت تصادفی پخش کنید، البته اگر این پرچم در `loadRequestData` پیام `LOAD` تنظیم شده باشد.
زیرنویس‌های بسته روشن/خاموش	فعال/غیرفعال کردن زیرنویس برای رسانه شما. فعال/غیرفعال کردن بر اساس زبان نیز در دسترس است.
به دنبال زمان مطلق باشید	به زمان مطلق مشخص شده پرش می‌کند.
جستجو برای زمان نسبت به زمان فعلی	نسبت به زمان پخش فعلی، به اندازه مدت زمان مشخص شده به جلو یا عقب می‌پرد.
دوباره بازی کن	اگر در حال حاضر چیزی در حال پخش نیست، رسانه در حال پخش را مجدداً راه اندازی کنید یا آخرین مورد رسانه پخش شده را پخش کنید.
تنظیم نرخ پخش	نرخ پخش رسانه را تغییر دهید. این باید به طور پیش‌فرض مدیریت شود. می‌توانید از رهگیر پیام `SET_PLAYBACK_RATE` برای لغو درخواست‌های نرخ ورودی استفاده کنید.

پشتیبانی از دستورات رسانه‌ای با صدا

برای جلوگیری از اجرای دستور صوتی در دستگاهی که دستیار گوگل (Assistant) روی آن فعال است، ابتدا باید دستورات رسانه‌ای پشتیبانی‌شده‌ای را که قصد پشتیبانی از آنها را دارید، تنظیم کنید. سپس باید با فعال کردن ویژگی CastReceiverOptions.enforceSupportedCommands ، آن دستورات را اعمال کنید. رابط کاربری در فرستنده‌های Cast SDK و دستگاه‌های لمسی برای انعکاس این تنظیمات تغییر خواهد کرد. اگر این پرچم فعال نباشد، دستورات صوتی ورودی اجرا می‌شوند.

برای مثال، اگر به برنامه‌های فرستنده و دستگاه‌های لمسی خود اجازه PAUSE می‌دهید، باید گیرنده خود را نیز طوری پیکربندی کنید که این تنظیمات را منعکس کند. پس از پیکربندی، هرگونه فرمان صوتی ورودی در صورت عدم وجود در لیست فرمان‌های پشتیبانی‌شده، حذف خواهد شد.

در مثال زیر، ما هنگام شروع CastReceiverContext گزینه CastReceiverOptions ارائه می‌دهیم. ما پشتیبانی از دستور PAUSE را اضافه کرده‌ایم و پخش‌کننده را مجبور کرده‌ایم که فقط از آن دستور پشتیبانی کند. اکنون اگر یک دستور صوتی درخواست عملیات دیگری مانند SEEK را داشته باشد، رد خواهد شد. به کاربر اطلاع داده می‌شود که این دستور هنوز پشتیبانی نمی‌شود.

const context = cast.framework.CastReceiverContext.getInstance();

context.start({
  enforceSupportedCommands: true,
  supportedCommands: cast.framework.messages.Command.PAUSE
});

شما می‌توانید برای هر دستوری که می‌خواهید محدود کنید، منطق جداگانه‌ای اعمال کنید. پرچم enforceSupportedCommands را حذف کنید و برای هر دستوری که می‌خواهید محدود کنید، می‌توانید پیام ورودی را رهگیری کنید. در اینجا ما درخواست ارائه شده توسط SDK را رهگیری می‌کنیم تا دستورات SEEK که به دستگاه‌های دارای دستیار صوتی صادر می‌شوند، در برنامه گیرنده وب شما جستجو ایجاد نکنند.

برای دستورات رسانه‌ای که برنامه شما پشتیبانی نمی‌کند، دلیل خطای مناسبی مانند NOT_SUPPORTED را برگردانید.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.SEEK,
  seekData => {
    // Block seeking if the SEEK supported media command is disabled
    if (!(playerManager.getSupportedMediaCommands() & cast.framework.messages.Command.SEEK)) {
      let e = new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType
      .INVALID_REQUEST);
      e.reason = cast.framework.messages.ErrorReason.NOT_SUPPORTED;
      return e;
    }

    return seekData;
  });

پس‌زمینه‌سازی از فعالیت صوتی

اگر پلتفرم Cast به دلیل فعالیت‌های Assistant مانند گوش دادن به صحبت‌های کاربر یا پاسخ دادن، صدای برنامه شما را در پس‌زمینه قرار دهد، هنگام شروع فعالیت، یک پیام FocusState با مقدار NOT_IN_FOCUS به برنامه Web Receiver ارسال می‌شود. هنگام پایان فعالیت، پیام دیگری با IN_FOCUS ارسال می‌شود. بسته به برنامه شما و رسانه‌ای که پخش می‌شود، ممکن است بخواهید با قطع کردن نوع پیام FOCUS_STATE ، پخش رسانه را هنگامی که FocusState برابر NOT_IN_FOCUS است، متوقف کنید.

برای مثال، اگر دستیار در حال پاسخ به یک پرسش کاربر باشد، مکث پخش کتاب صوتی یک تجربه کاربری خوب است.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.FOCUS_STATE,
  focusStateRequestData => {
    // Pause content when the app is out of focus. Resume when focus is restored.
    if (focusStateRequestData.state == cast.framework.messages.FocusState.NOT_IN_FOCUS) {
      playerManager.pause();
    } else {
      playerManager.play();
    }

    return focusStateRequestData;
  });

زبان زیرنویس مشخص‌شده توسط صدا

وقتی کاربر صراحتاً زبان زیرنویس‌ها را اعلام نمی‌کند، زبانی که برای زیرنویس‌ها استفاده می‌شود همان زبانی است که دستور با آن بیان شده است. در این سناریوها، پارامتر isSuggestedLanguage پیام دریافتی نشان می‌دهد که آیا زبان مرتبط توسط کاربر پیشنهاد شده یا صریحاً درخواست شده است.

برای مثال، isSuggestedLanguage برای دستور «OK Google, turn captions on» روی true تنظیم شده است، زیرا زبان توسط زبانی که دستور با آن گفته شده است، استنباط شده است. اگر زبان به صراحت درخواست شود، مانند «OK Google, turn on English captions»، isSuggestedLanguage روی false تنظیم می‌شود.

فراداده و تبدیل صدا

اگرچه دستورات صوتی به طور پیش‌فرض توسط گیرنده وب مدیریت می‌شوند، اما باید مطمئن شوید که فراداده‌های محتوای شما کامل و دقیق هستند. این امر تضمین می‌کند که دستورات صوتی به درستی توسط دستیار صوتی مدیریت می‌شوند و فراداده‌ها به درستی در انواع جدید رابط‌ها مانند برنامه Google Home و نمایشگرهای هوشمند مانند Google Home Hub نمایش داده می‌شوند.

انتقال جریان

حفظ وضعیت جلسه، اساس انتقال جریان است، که در آن کاربران می‌توانند جریان‌های صوتی و تصویری موجود را با استفاده از دستورات صوتی، برنامه Google Home یا نمایشگرهای هوشمند، بین دستگاه‌ها جابجا کنند. پخش رسانه در یک دستگاه (منبع) متوقف می‌شود و در دستگاه دیگر (مقصد) ادامه می‌یابد. هر دستگاه Cast با جدیدترین سیستم عامل می‌تواند به عنوان منبع یا مقصد در انتقال جریان عمل کند.

جریان رویداد برای انتقال جریان عبارت است از:

در دستگاه مبدا:
1. پخش رسانه متوقف می‌شود.
2. برنامه گیرنده وب دستوری برای ذخیره وضعیت فعلی رسانه دریافت می‌کند.
3. برنامه گیرنده وب خاموش است.
در دستگاه مقصد:
1. برنامه گیرنده وب بارگذاری شده است.
2. برنامه گیرنده وب دستوری برای بازیابی وضعیت رسانه ذخیره شده دریافت می‌کند.
3. پخش رسانه از سر گرفته می‌شود.

عناصر وضعیت رسانه‌ای عبارتند از:

موقعیت یا زمان خاص آهنگ، ویدیو یا آیتم رسانه‌ای.
جایگاه آن در یک صف گسترده‌تر (مانند لیست پخش یا رادیو هنرمندان) است.
کاربر احراز هویت شده.
وضعیت پخش (مثلاً در حال پخش یا متوقف شده).

فعال کردن انتقال جریان

برای پیاده‌سازی انتقال جریان برای گیرنده وب خود:

به‌روزرسانی supportedMediaCommands با دستور STREAM_TRANSFER :

playerManager.addSupportedMediaCommands(
cast.framework.messages.Command.STREAM_TRANSFER, true);

به صورت اختیاری، همانطور که در بخش «حفظ وضعیت جلسه» توضیح داده شده است، می‌توان از رهگیرهای پیام SESSION_STATE و RESUME_SESSION استفاده کرد. فقط در صورتی که نیاز به ذخیره داده‌های سفارشی به عنوان بخشی از تصویر لحظه‌ای جلسه باشد، می‌توان از این موارد صرف نظر کرد. در غیر این صورت، پیاده‌سازی پیش‌فرض برای حفظ وضعیت‌های جلسه، از انتقال جریان پشتیبانی می‌کند.

حفظ وضعیت جلسه

کیت توسعه نرم‌افزار (SDK) گیرنده وب، یک پیاده‌سازی پیش‌فرض برای برنامه‌های گیرنده وب فراهم می‌کند تا با گرفتن یک اسنپ‌شات از وضعیت فعلی رسانه، تبدیل وضعیت به یک درخواست بارگذاری و از سرگیری جلسه با درخواست بارگذاری، وضعیت‌های جلسه را حفظ کند.

درخواست بارگذاری تولید شده توسط گیرنده وب می‌تواند در صورت لزوم در رهگیر پیام SESSION_STATE لغو شود. اگر می‌خواهید داده‌های سفارشی را به درخواست بارگذاری اضافه کنید، پیشنهاد می‌کنیم آنها را در loadRequestData.customData قرار دهید.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.SESSION_STATE,
    function (sessionState) {
        // Override sessionState.loadRequestData if needed.
        const newCredentials = updateCredentials_(sessionState.loadRequestData.credentials);
        sessionState.loadRequestData.credentials = newCredentials;

        // Add custom data if needed.
        sessionState.loadRequestData.customData = {
            'membership': 'PREMIUM'
        };

        return sessionState;
    });

داده‌های سفارشی را می‌توان از loadRequestData.customData در رهگیر پیام RESUME_SESSION بازیابی کرد.

let cred_ = null;
let membership_ = null;

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.RESUME_SESSION,
    function (resumeSessionRequest) {
        let sessionState = resumeSessionRequest.sessionState;

        // Modify sessionState.loadRequestData if needed.
        cred_ = sessionState.loadRequestData.credentials;

        // Retrieve custom data.
        membership_ = sessionState.loadRequestData.customData.membership;

        return resumeSessionRequest;
    });

پیش بارگذاری محتوا

گیرنده وب از پیش بارگذاری موارد رسانه‌ای پس از مورد پخش فعلی در صف پشتیبانی می‌کند.

عملیات پیش‌بارگذاری، چندین بخش از آیتم‌های آینده را پیش‌دانلود می‌کند. این مشخصات بر روی مقدار preloadTime در شیء QueueItem انجام می‌شود (در صورت عدم ارائه، مقدار پیش‌فرض 20 ثانیه است). زمان بر حسب ثانیه، نسبت به پایان آیتم در حال پخش فعلی، بیان می‌شود. فقط مقادیر مثبت معتبر هستند. به عنوان مثال، اگر مقدار 10 ثانیه باشد، این آیتم 10 ثانیه قبل از پایان آیتم قبلی پیش‌بارگذاری می‌شود. اگر زمان پیش‌بارگذاری بیشتر از زمان باقی مانده برای currentItem باشد، پیش‌بارگذاری در اسرع وقت اتفاق می‌افتد. بنابراین اگر مقدار بسیار زیادی برای preload در queueItem مشخص شود، می‌توان به این نتیجه رسید که هر زمان که آیتم فعلی را پخش می‌کنیم، آیتم بعدی را از قبل پیش‌بارگذاری کرده‌ایم. با این حال، تنظیم و انتخاب این مقدار را به توسعه‌دهنده واگذار می‌کنیم زیرا این مقدار می‌تواند بر پهنای باند و عملکرد پخش آیتم در حال پخش فعلی تأثیر بگذارد.

پیش بارگذاری به طور پیش‌فرض برای محتوای پخش HLS، DASH و Smooth کار می‌کند.

فایل‌های ویدیویی و صوتی معمولی MP4 مانند MP3 از قبل بارگیری نمی‌شوند زیرا دستگاه‌های Cast فقط از یک عنصر رسانه‌ای پشتیبانی می‌کنند و نمی‌توان از آنها برای بارگیری اولیه در حالی که یک محتوای موجود هنوز در حال پخش است، استفاده کرد.

پیام‌های سفارشی

تبادل پیام، روش تعاملی کلیدی برای برنامه‌های گیرنده وب است.

یک فرستنده با استفاده از APIهای فرستنده برای پلتفرمی که فرستنده در حال اجرا دارد (اندروید، iOS، وب)، پیام‌هایی را به یک گیرنده وب ارسال می‌کند. شیء رویداد (که تجلی یک پیام است) که به شنوندگان رویداد ارسال می‌شود، دارای یک عنصر داده ( event.data ) است که در آن داده‌ها ویژگی‌های نوع رویداد خاص را به خود می‌گیرند.

یک برنامه گیرنده وب می‌تواند انتخاب کند که به پیام‌های موجود در یک فضای نام مشخص گوش دهد. به موجب انجام این کار، گفته می‌شود که برنامه گیرنده وب از پروتکل آن فضای نام پشتیبانی می‌کند. سپس به هر فرستنده متصلی که مایل به برقراری ارتباط در آن فضای نام است، بستگی دارد که از پروتکل مناسب استفاده کند.

تمام فضاهای نام توسط یک رشته تعریف می‌شوند و باید با " urn:x-cast: " شروع شوند و به دنبال آن هر رشته‌ای قرار گیرد. برای مثال، " urn:x-cast: com.example.cast.mynamespace ".

در اینجا یک قطعه کد برای گیرنده وب وجود دارد تا به پیام‌های سفارشی از فرستندگان متصل گوش دهد:

const context = cast.framework.CastReceiverContext.getInstance();

const CUSTOM_CHANNEL = 'urn:x-cast:com.example.cast.mynamespace';
context.addCustomMessageListener(CUSTOM_CHANNEL, function(customEvent) {
  // handle customEvent.
});

context.start();

به طور مشابه، برنامه‌های گیرنده وب می‌توانند با ارسال پیام به فرستندگان متصل، فرستندگان را از وضعیت گیرنده وب مطلع نگه دارند. یک برنامه گیرنده وب می‌تواند با استفاده از sendCustomMessage(namespace, senderId, message) در CastReceiverContext پیام ارسال کند. یک گیرنده وب می‌تواند پیام‌ها را به یک فرستنده خاص، چه در پاسخ به یک پیام دریافتی و چه به دلیل تغییر وضعیت برنامه، ارسال کند. فراتر از پیام‌رسانی نقطه به نقطه (با محدودیت ۶۴ کیلوبایت)، یک گیرنده وب همچنین می‌تواند پیام‌ها را به همه فرستندگان متصل پخش کند.

پخش برای دستگاه‌های صوتی

برای اطلاع از پشتیبانی از پخش فقط صدا ، به راهنمای دستگاه‌های صوتی Google Cast مراجعه کنید.

تلویزیون اندروید

این بخش به نحوه استفاده گیرنده وب گوگل از ورودی‌های شما به عنوان پخش و سازگاری با تلویزیون اندروید می‌پردازد.

ادغام برنامه شما با کنترل از راه دور

گیرنده وب گوگل که روی دستگاه تلویزیون اندروید اجرا می‌شود، ورودی‌های کنترل دستگاه (یعنی کنترل از راه دور دستی) را به عنوان پیام‌های پخش رسانه‌ای تعریف شده برای فضای نام urn:x-cast:com.google.cast.media ترجمه می‌کند، همانطور که در پیام‌های پخش رسانه توضیح داده شده است. برنامه شما باید از این پیام‌ها برای کنترل پخش رسانه برنامه پشتیبانی کند تا امکان کنترل اولیه پخش از ورودی‌های کنترل تلویزیون اندروید فراهم شود.

دستورالعمل‌های سازگاری با تلویزیون اندروید

در اینجا چند توصیه و اشتباهات رایج وجود دارد که باید از آنها اجتناب کنید تا مطمئن شوید برنامه شما با Android TV سازگار است:

توجه داشته باشید که رشته‌ی عامل کاربر شامل هر دو عبارت "Android" و "CrKey" است؛ برخی از سایت‌ها ممکن است به دلیل شناسایی برچسب "Android" به یک سایت مخصوص موبایل هدایت شوند. فرض نکنید که "Android" در رشته‌ی عامل کاربر همیشه نشان‌دهنده‌ی یک کاربر موبایل است.
ممکن است پشته رسانه اندروید از GZIP شفاف برای واکشی داده‌ها استفاده کند. مطمئن شوید که داده‌های رسانه شما می‌توانند به Accept-Encoding: gzip پاسخ دهند.
رویدادهای رسانه‌ای HTML5 اندروید تی‌وی ممکن است در زمان‌بندی‌های متفاوتی نسبت به کروم‌کست اجرا شوند، این امر ممکن است مشکلاتی را که در کروم‌کست پنهان بودند، آشکار کند.
هنگام به‌روزرسانی رسانه، از رویدادهای مرتبط با رسانه که توسط عناصر <audio>/<video> ایجاد می‌شوند، مانند timeupdate ، pause و waiting استفاده کنید. از استفاده از رویدادهای مرتبط با شبکه مانند progress ، suspend و stalled خودداری کنید، زیرا این رویدادها به پلتفرم وابسته هستند. برای اطلاعات بیشتر در مورد مدیریت رویدادهای رسانه در گیرنده خود، به رویدادهای رسانه مراجعه کنید.
هنگام پیکربندی گواهینامه‌های HTTPS سایت گیرنده خود، حتماً گواهینامه‌های CA میانی را نیز لحاظ کنید. برای تأیید به صفحه تست SSL شرکت Qualsys مراجعه کنید: اگر مسیر صدور گواهینامه معتبر برای سایت شما شامل یک گواهینامه CA با برچسب «دانلود اضافی» باشد، ممکن است روی پلتفرم‌های مبتنی بر اندروید بارگیری نشود.
در حالی که کروم‌کست صفحه گیرنده را با کیفیت گرافیکی 720p نمایش می‌دهد، سایر پلتفرم‌های کست از جمله اندروید تی‌وی ممکن است صفحه را تا 1080p نمایش دهند. مطمئن شوید که صفحه گیرنده شما با وضوح‌های مختلف به خوبی مقیاس‌بندی می‌شود.

قبلی

گیرنده وب سفارشی

بعدی

HLS در Shaka Player Migration