افزودن ویژگی‌های اصلی به گیرنده وب سفارشی

این صفحه حاوی تکه‌کدها و شرح ویژگی‌های دردسترس برای برنامه «گیرنده وب سفارشی» است.

1. عنصر cast-media-player که نشان‌دهنده واسط کاربر پخش‌کننده داخلی ارائه‌شده با «گیرنده وب» است.
2. سبک‌بندی سفارشی شبیه CSS برای عنصر cast-media-player برای سبک‌بندی عناصر مختلف میانای کاربر مثل background-image، splash-image، و font-family.
3. عنصر اسکریپت برای بار کردن چارچوب «گیرنده وب».
4. کد جاوا اسکریپت برای رهگیری پیام‌ها و مدیریت رویدادها.
5. صف برای پخش خودکار.
6. گزینه‌های پیکربندی بازپخش.
7. گزینه‌های تنظیم بافت «گیرنده وب».
8. گزینه‌هایی برای تنظیم فرمان‌هایی که برنامه «گیرنده وب» از آن‌ها پشتیبانی می‌کند.
9. یک فراخوانی جاوا اسکریپت برای راه‌اندازی برنامه «گیرنده وب».

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

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

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

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

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

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

هنگام بار کردن محتوا، «کیت توسعه نرم‌افزار گیرنده وب» روشی برای پیکربندی متغیرهای بازپخش مانند اطلاعات مدیریت حقوق دیجیتال، پیکربندی‌های تکرار، و گرداننده‌های درخواست بااستفاده از cast.framework.PlaybackConfig ارائه می‌دهد. این اطلاعات توسط PlayerManager مدیریت می‌شود و در زمان ایجاد بازیکنان ارزیابی می‌شود. هر بار که بار جدیدی به کیت توسعه نرم‌افزار «گیرنده وب» ارسال می‌شود، پخش‌کننده‌ها ایجاد می‌شوند. اصلاحات انجام‌شده در PlaybackConfig پس‌از ایجاد پخش‌کننده در بارگیری بعدی محتوا ارزیابی می‌شود. کیت توسعه نرم‌افزار روش‌های زیر را برای اصلاح PlaybackConfig ارائه می‌دهد.

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

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

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

مثال زیر نشان می‌دهد که چگونه می‌توان PlaybackConfig را بااستفاده از گیرنده و تنظیم‌کننده ارائه‌شده در 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;
});

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

کیت توسعه نرم‌افزار «گیرنده وب» به برنامه «گیرنده وب» شما اجازه می‌دهد رویدادهای پخش‌کننده را مدیریت کند. شنونده رویداد پارامتر 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();

مدیریت کردن خطا

وقتی خطایی در رهگیر پیام رخ می‌دهد، برنامه «گیرنده وب» شما باید 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;
        });
    });

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

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

• شنونده رویداد به شما اجازه نمی‌دهد داده‌های درخواست را تغییر دهید.
• بهترین کاربرد شنونده رویداد، راه‌اندازی Analytics یا عملکرد سفارشی است.

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

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

درحال بار کردن رسانه

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

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

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

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

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

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

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

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

1. استفاده از PlayerManager.setSupportedMediaCommands برای تنظیم Commands خاص
2. افزودن فرمان جدید بااستفاده از addSupportedMediaCommands
3. برداشتن فرمان موجود بااستفاده از removeSupportedMediaCommands.

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

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

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

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

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

• 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 را رهگیری می‌کند و فراخوانی بخش پشتی را با تغییر درخواست‌شده مدیریت می‌کند. سپس تماسی برقرار می‌کند تا 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;
    });
});

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

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 وضعیت دکمه‌ای را که با کنش درخواست‌شده مرتبط است تغییر می‌دهد. این تغییر در واسط کاربر کنترل‌های نمایشگر هوشمند، برنامه کنترل از راه دور، و واسط کاربر Android TV منعکس می‌شود. همچنین ازطریق پیام‌های برون‌رفت MediaStatus برای به‌روزرسانی واسط کاربر کنترل‌کننده گسترده برای فرستنده‌های iOS و Android همه‌فرستی می‌شود.

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;
}

فرمان‌های صوتی

درحال‌حاضر فرمان‌های رسانه زیر در «کیت توسعه نرم‌افزار گیرنده وب» برای دستگاه‌های مجهز به «دستیار» پشتیبانی می‌شود. پیاده‌سازی‌های پیش‌فرض این فرمان‌ها در cast.framework.PlayerManager یافت می‌شود.

فرمان‌های رسانه‌ای پشتیبانی‌شده با صدا

برای جلوگیری از اینکه فرمان صوتی باعث راه‌اندازی فرمان رسانه در دستگاهی با قابلیت «دستیار» شود، ابتدا باید فرمان‌های رسانه پشتیبانی‌شده را که قصد پشتیبانی از آن‌ها را دارید تنظیم کنید. سپس باید آن فرمان‌ها را با فعال کردن ویژگی 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 را بردارید و برای هر فرمانی که می‌خواهید محدود کنید، می‌توانید پیام ورودی را رهگیری کنید. در اینجا درخواست ارائه‌شده توسط کیت توسعه نرم‌افزار را رهگیری می‌کنیم تا فرمان‌های 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 صدای برنامه شما را به‌دلیل فعالیت «دستیار» (مانند گوش دادن به گفتار کاربر یا پاسخ دادن) در پس‌زمینه قرار دهد، هنگام شروع فعالیت، پیام FocusState با مقدار NOT_IN_FOCUS به برنامه «گیرنده وب» ارسال می‌شود. وقتی فعالیت تمام شود، پیام دیگری با IN_FOCUS ارسال می‌شود. بسته به برنامه شما و رسانه‌ای که پخش می‌شود، ممکن است بخواهید رسانه را وقتی FocusState NOT_IN_FOCUS است با رهگیری نوع پیام FOCUS_STATE موقتاً متوقف کنید.

برای مثال، اگر «دستیار» درحال پاسخ دادن به پُرسمان کاربر باشد، توقف موقت بازپخش کتاب صوتی تجربه کاربری خوبی است.

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، زیرنویس ناشنوایان را روشن کن» روی true تنظیم شده است، زیرا زبان از روی زبانی که فرمان با آن گفته شده است استنباط شده است. اگر زبان به‌طور صریح درخواست شده باشد، مثلاً در «Ok Google، زیرنویس ناشنوایان انگلیسی را روشن کن»، isSuggestedLanguage روی false تنظیم می‌شود.

فراداده و صداپیشگی

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

انتقال جاری‌سازی

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

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

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

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

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

درحال فعال کردن انتقال جاری‌سازی

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

1. supportedMediaCommands را با فرمان STREAM_TRANSFER به‌روز کنید:

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

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

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

کیت توسعه نرم‌افزار «گیرنده وب» پیاده‌سازی پیش‌فرضی برای برنامه‌های «گیرنده وب» ارائه می‌دهد تا وضعیت‌های جلسه را با گرفتن عکس آنی از وضعیت رسانه فعلی، تبدیل وضعیت به درخواست بار کردن، و ازسر گرفتن جلسه با درخواست بار کردن حفظ کند.

درصورت لزوم، درخواست بارگیری تولیدشده توسط «گیرنده وب» را می‌توان در 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 انجام می‌شود (اگر ارائه نشود، به‌طور پیش‌فرض ۲۰ ثانیه است). زمان برحسب ثانیه و نسبت به پایان موردی که درحال پخش است بیان می‌شود . فقط مقادیر مثبت معتبر است. برای مثال، اگر مقدار ۱۰ ثانیه باشد، این مورد ۱۰ ثانیه قبل‌از پایان مورد قبلی پیش‌بارگیری می‌شود. اگر زمان پیش‌بارگیری بیشتر از زمان باقی‌مانده در currentItem باشد، پیش‌بارگیری در اسرع وقت انجام خواهد شد. بنابراین اگر مقدار بسیار بزرگی از پیش‌بارگیری در queueItem مشخص شده باشد، می‌توان به این نتیجه رسید که هرگاه درحال پخش مورد فعلی هستیم، درحال پیش‌بارگیری مورد بعدی هستیم. بااین‌حال، تنظیم و انتخاب این مورد را به توسعه‌دهنده واگذار می‌کنیم زیرا این مقدار می‌تواند بر پهنای باند و عملکرد جاری‌سازی مورد درحال پخش تأثیر بگذارد.

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

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

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

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

فرستنده بااستفاده از میاناهای برنامه‌سازی کاربردی فرستنده برای پلاتفرمی که فرستنده در آن اجرا می‌شود (Android،‏ 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 برای دستگاه‌های صوتی را ببینید.

Android TV

این بخش درباره نحوه استفاده Google Web Receiver از ورودی‌های شما به‌عنوان بازپخش، و سازگاری Android TV بحث می‌کند.

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

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

دستورالعمل‌های سازگاری Android TV

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

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