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

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

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

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

هنگام بار کردن محتوا، «کیت توسعه نرم‌افزار گیرنده وب» روشی برای پیکربندی متغیرهای بازپخش مانند اطلاعات DRM، پیکربندی‌های تلاش مجدد، و مدیریت‌کننده‌های درخواست بااستفاده از cast.framework.PlaybackConfig ارائه می‌دهد. این اطلاعات توسط PlayerManager مدیریت می‌شود و در زمان ایجاد بازیکنان ارزیابی می‌شود. هر بار که بار جدیدی به «کیت توسعه نرم‌افزار گیرنده وب» ارسال می‌شود، بازیکنان ایجاد می‌شوند. اصلاحات PlaybackConfig پس‌از ایجاد بازیکن در بار محتوای بعدی ارزیابی می‌شود. کیت توسعه نرم‌افزار روش‌های زیر را برای اصلاح 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 را بااستفاده از گیرنده و تنظیم‌کننده ارائه‌شده در 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
});

رهگیری پیام

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

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

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

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

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» «میاناهای برنامه‌سازی کاربردی» مختلفی را ارائه می‌دهد تا به برنامه «گیرنده وب» اجازه دهد این تعاملات را مدیریت کند، میانای کاربر برنامه را ازطریق وضعیت‌های کنش کاربر به‌روز کند، و به‌صورت اختیاری تغییرات را برای به‌روزرسانی هرگونه سرویس زیرینه ارسال کند.

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

وضعیت‌های کنترل‌های میانای کاربر توسط 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 را رهگیری می‌کند و LoadRequestData مربوط به MediaInformation را تکمیل می‌کند. در این مورد، کاربر محتوایی را که درحال بار شدن است می‌پسندد.

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» و دستگاه‌های دارای صفحه لمسی تغییر خواهد کرد تا این پیکربندی‌ها را منعکس کند. اگر پرچم فعال نباشد، دستورات صوتی ورودی اجرا خواهد شد.

برای مثال، اگر 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;
  });

انتقال به پس‌زمینه از فعالیت گفتاری

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

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

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، و جاری‌سازی روان کار می‌کند.

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

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

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

فرستنده بااستفاده از APIهای فرستنده برای پلاتفرمی که فرستنده در آن اجرا می‌شود (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» از ورودی‌های شما به‌عنوان بازپخش، و سازگاری 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 سایت گیرنده، حتماً گواهینامه‌های مرکز صدور گواهی واسطه را اضافه کنید. برای تأیید اینکه مسیر گواهینامه مطمئن برای سایت شما شامل گواهینامه مرجع صدور گواهینامه با برچسب «بارگیری اضافی» است یا نه، به صفحه آزمایش Qualsys SSL مراجعه کنید. اگر این گواهینامه را داشته باشد، ممکن است در پلاتفرم‌های مبتنی بر Android بار نشود.
• درحالی‌که Chromecast صفحه گیرنده را در یک صفحه گرافیکی 720p نمایش می‌دهد، سایر پلاتفرم‌های Cast ازجمله Android TV ممکن است صفحه را تا 1080p نمایش دهند. مطمئن شوید صفحه گیرنده شما در وضوح‌های مختلف به‌خوبی مقیاس‌بندی می‌شود.