Cast SDK را در برنامه فرستنده وب خود ادغام کنید

این راهنمای توسعه‌دهنده نحوه‌ی افزودن پشتیبانی Google Cast به برنامه‌ی Web Sender شما را با استفاده از Cast SDK شرح می‌دهد.

اصطلاحات

دستگاه تلفن همراه یا مرورگر، فرستنده است که پخش را کنترل می‌کند؛ دستگاه Google Cast گیرنده است که محتوا را برای پخش روی صفحه نمایش می‌دهد.

کیت توسعه نرم‌افزار وب فرستنده از دو بخش تشکیل شده است: API چارچوب ( cast.framework ) و API پایه ( chrome.cast ). به طور کلی، شما فراخوانی‌هایی را روی API چارچوب سطح بالاتر و ساده‌تر انجام می‌دهید که سپس توسط API پایه سطح پایین‌تر پردازش می‌شوند.

چارچوب فرستنده به API چارچوب، ماژول و منابع مرتبط اشاره دارد که یک پوشش پیرامون قابلیت‌های سطح پایین‌تر ارائه می‌دهند. برنامه فرستنده یا برنامه Google Cast Chrome به یک برنامه وب (HTML/JavaScript) که درون یک مرورگر Chrome روی دستگاه فرستنده اجرا می‌شود، اشاره دارد. یک برنامه گیرنده وب به یک برنامه HTML/JavaScript که روی Chromecast یا دستگاه Google Cast اجرا می‌شود، اشاره دارد.

چارچوب فرستنده از یک طراحی فراخوانی ناهمزمان برای اطلاع‌رسانی به برنامه فرستنده از رویدادها و انتقال بین حالت‌های مختلف چرخه حیات برنامه Cast استفاده می‌کند.

کتابخانه را بارگذاری کنید

برای اینکه برنامه شما بتواند ویژگی‌های Google Cast را پیاده‌سازی کند، باید محل SDK مربوط به Google Cast Web Sender را بداند، همانطور که در زیر نشان داده شده است. پارامتر کوئری URL مربوط به loadCastFramework را نیز برای بارگذاری API مربوط به Web Sender Framework اضافه کنید. تمام صفحات برنامه شما باید به صورت زیر به کتابخانه ارجاع دهند:

<script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>

چارچوب

کیت توسعه نرم‌افزاری فرستنده وب از فضای نام cast.framework. * استفاده می‌کند. این فضای نام موارد زیر را نشان می‌دهد:

  • متدها یا توابعی که عملیات را روی API فراخوانی می‌کنند
  • شنونده‌های رویداد برای توابع شنونده در API

این چارچوب از اجزای اصلی زیر تشکیل شده است:

  • CastContext یک شیء تک‌لایه است که اطلاعاتی در مورد وضعیت فعلی Cast ارائه می‌دهد و رویدادهایی را برای وضعیت Cast و تغییرات وضعیت جلسه Cast فعال می‌کند.
  • شیء CastSession جلسه را مدیریت می‌کند -- اطلاعات وضعیت را ارائه می‌دهد و رویدادهایی مانند تغییرات در میزان صدای دستگاه، وضعیت بی‌صدا و ابرداده‌های برنامه را فعال می‌کند.
  • عنصر دکمه‌ی Cast، که یک عنصر سفارشی ساده‌ی HTML است که دکمه‌ی HTML را گسترش می‌دهد. اگر دکمه‌ی Cast ارائه شده کافی نباشد، می‌توانید از حالت Cast برای پیاده‌سازی یک دکمه‌ی Cast استفاده کنید.
  • RemotePlayerController اتصال داده را برای ساده‌سازی پیاده‌سازی پخش‌کننده‌ی راه دور فراهم می‌کند.

برای شرح کامل فضای نام، مرجع API فرستنده وب گوگل کست را بررسی کنید.

دکمه‌ی ارسال

کامپوننت دکمه‌ی Cast در برنامه‌ی شما کاملاً توسط فریم‌ورک مدیریت می‌شود. این شامل مدیریت نمایش و همچنین مدیریت رویداد کلیک می‌شود.

<google-cast-launcher></google-cast-launcher>

روش دیگر، ایجاد دکمه به صورت برنامه‌نویسی است:

document.createElement("google-cast-launcher");

شما می‌توانید در صورت لزوم هر گونه استایل‌بندی اضافی، مانند اندازه یا موقعیت، را به عنصر اعمال کنید. از ویژگی --connected-color برای انتخاب رنگ برای حالت گیرنده وب متصل و --disconnected-color برای حالت قطع استفاده کنید.

مقداردهی اولیه

پس از بارگذاری API فریم‌ورک، برنامه، هندلر window.__onGCastApiAvailable را فراخوانی می‌کند. شما باید قبل از بارگذاری کتابخانه فرستنده ، مطمئن شوید که برنامه این هندلر را روی window تنظیم کرده است.

درون این هندلر، شما با فراخوانی متد setOptions(options) از CastContext ، تعامل Cast را مقداردهی اولیه می‌کنید.

برای مثال:

<script>
window['__onGCastApiAvailable'] = function(isAvailable) {
  if (isAvailable) {
    initializeCastApi();
  }
};
</script>

سپس، API را به صورت زیر مقداردهی اولیه می‌کنید:

initializeCastApi = function() {
  cast.framework.CastContext.getInstance().setOptions({
    receiverApplicationId: applicationId,
    autoJoinPolicy: chrome.cast.AutoJoinPolicy.ORIGIN_SCOPED
  });
};

ابتدا برنامه نمونه‌ی تک‌لایه از شیء CastContext ارائه شده توسط چارچوب را بازیابی می‌کند. سپس با استفاده از setOptions(options) و با استفاده از یک شیء CastOptions applicationID را تنظیم می‌کند.

اگر از گیرنده رسانه پیش‌فرض استفاده می‌کنید که نیازی به ثبت‌نام ندارد، می‌توانید از یک ثابت از پیش تعریف‌شده توسط SDK فرستنده وب، همانطور که در زیر نشان داده شده است، به جای applicationID استفاده کنید:

cast.framework.CastContext.getInstance().setOptions({
  receiverApplicationId: chrome.cast.media.DEFAULT_MEDIA_RECEIVER_APP_ID
});

کنترل رسانه

پس از مقداردهی اولیه CastContext ، برنامه می‌تواند CastSession فعلی را در هر زمانی با استفاده از getCurrentSession() بازیابی کند.

var castSession = cast.framework.CastContext.getInstance().getCurrentSession();

می‌توان از CastSession برای بارگذاری رسانه در دستگاه Cast متصل با استفاده از loadMedia(loadRequest) استفاده کرد. ابتدا، یک MediaInfo با استفاده از contentId و contentType و همچنین هرگونه اطلاعات دیگر مربوط به محتوا ایجاد کنید. سپس یک LoadRequest از آن ایجاد کنید و تمام اطلاعات مربوط به درخواست را تنظیم کنید. در نهایت، loadMedia(loadRequest) را در CastSession خود فراخوانی کنید.

var mediaInfo = new chrome.cast.media.MediaInfo(currentMediaURL, contentType);
var request = new chrome.cast.media.LoadRequest(mediaInfo);
castSession.loadMedia(request).then(
  function() { console.log('Load succeed'); },
  function(errorCode) { console.log('Error code: ' + errorCode); });

متد loadMedia یک Promise برمی‌گرداند که می‌تواند برای انجام هرگونه عملیات لازم برای رسیدن به نتیجه‌ای موفقیت‌آمیز مورد استفاده قرار گیرد. اگر Promise رد شود، آرگومان تابع chrome.cast.ErrorCode خواهد بود.

شما می‌توانید به متغیرهای وضعیت پخش‌کننده در RemotePlayer دسترسی داشته باشید. تمام تعاملات با RemotePlayer ، از جمله فراخوانی‌های رویداد رسانه‌ای و دستورات، با RemotePlayerController مدیریت می‌شوند.

var player = new cast.framework.RemotePlayer();
var playerController = new cast.framework.RemotePlayerController(player);

RemotePlayerController به برنامه کنترل کامل رسانه مانند پخش، مکث، توقف و جستجو برای رسانه‌های بارگذاری شده را می‌دهد.

  • پخش/مکث: playerController.playOrPause();
  • توقف: playerController.stop();
  • جستجو: playerController.seek();

RemotePlayer و RemotePlayerController می‌توانند با چارچوب‌های اتصال داده، مانند Polymer یا Angular، برای پیاده‌سازی یک پخش‌کننده از راه دور استفاده شوند.

این هم یک قطعه کد برای Angular: 

<button id="playPauseButton" class="playerButton"
  ng-disabled="!player.canPause"
  ng-click="controller.playOrPause()">
    {{player.isPaused ? 'Play' : 'Pause'}}
</button>
<script>
var player = new cast.framework.RemotePlayer();
var controller = new cast.framework.RemotePlayerController(player);
// Listen to any player update, and trigger angular data binding
update.controller.addEventListener(
  cast.framework.RemotePlayerEventType.ANY_CHANGE,
  function(event) {
    if (!$scope.$$phase) $scope.$apply();
  });
</script>

وضعیت رسانه

در طول پخش رسانه، رویدادهای مختلفی رخ می‌دهند که می‌توان با تنظیم شنونده‌ها برای رویدادهای مختلف cast.framework.RemotePlayerEventType در شیء RemotePlayerController آنها را ثبت کرد.

برای دریافت اطلاعات وضعیت رسانه، از رویداد cast.framework.RemotePlayerEventType .MEDIA_INFO_CHANGED استفاده کنید، که هنگام تغییر پخش و تغییر CastSession.getMediaSession().media فعال می‌شود. 

playerController.addEventListener(
  cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED, function() {
    // Use the current session to get an up to date media status.
    let session = cast.framework.CastContext.getInstance().getCurrentSession();

    if (!session) {
        return;
    }

    // Contains information about the playing media including currentTime.
    let mediaStatus = session.getMediaSession();
    if (!mediaStatus) {
        return;
    }

    // mediaStatus also contains the mediaInfo containing metadata and other
    // information about the in progress content.
    let mediaInfo = mediaStatus.media;
  });

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

نحوه کار مدیریت جلسه

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

جلسات توسط کلاس CastContext مدیریت می‌شوند که برنامه شما می‌تواند آن را از طریق cast.framework.CastContext.getInstance() بازیابی کند. جلسات جداگانه توسط زیرکلاس‌های کلاس Session نمایش داده می‌شوند. برای مثال، CastSession جلساتی را با دستگاه‌های Cast نشان می‌دهد. برنامه شما می‌تواند از طریق CastContext.getCurrentSession() به جلسه Cast فعال فعلی دسترسی پیدا کند.

برای نظارت بر وضعیت جلسه، یک شنونده (listener) به CastContext برای نوع رویداد CastContextEventType .SESSION_STATE_CHANGED اضافه کنید. 

var context = cast.framework.CastContext.getInstance();
context.addEventListener(
  cast.framework.CastContextEventType.SESSION_STATE_CHANGED,
  function(event) {
    switch (event.sessionState) {
      case cast.framework.SessionState.SESSION_STARTED:
      case cast.framework.SessionState.SESSION_RESUMED:
        break;
      case cast.framework.SessionState.SESSION_ENDED:
        console.log('CastContext: CastSession disconnected');
        // Update locally as necessary
        break;
    }
  })

برای قطع ارتباط، مانند زمانی که کاربر روی دکمه "توقف ارسال" از کادر محاوره‌ای ارسال کلیک می‌کند، می‌توانید یک شنونده برای نوع رویداد RemotePlayerEventType .IS_CONNECTED_CHANGED در شنونده خود اضافه کنید. در شنونده خود بررسی کنید که آیا RemotePlayer قطع شده است یا خیر. در این صورت، وضعیت پخش‌کننده محلی را در صورت لزوم به‌روزرسانی کنید. برای مثال: 

playerController.addEventListener(
  cast.framework.RemotePlayerEventType.IS_CONNECTED_CHANGED, function() {
    if (!player.isConnected) {
      console.log('RemotePlayerController: Player disconnected');
      // Update local player to disconnected state
    }
  });

در حالی که کاربر می‌تواند مستقیماً از طریق دکمه‌ی Cast فریم‌ورک، خاتمه‌ی Cast را کنترل کند، خود فرستنده می‌تواند با استفاده از شیء CastSession فعلی، Cast را متوقف کند. 

function stopCasting() {
  var castSession = cast.framework.CastContext.getInstance().getCurrentSession();
  // End the session and pass 'true' to indicate
  // that Web Receiver app should be stopped.
  castSession.endSession(true);
}

انتقال جریان

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

برای دریافت دستگاه مقصد جدید در حین انتقال استریم، هنگام فراخوانی رویداد cast.framework.SessionState .SESSION_RESUMED ، تابع CastSession#getCastDevice() را فراخوانی کنید.

برای اطلاعات بیشتر به بخش انتقال جریان در گیرنده وب مراجعه کنید.

قبلی
راه اندازی
بعدی
افزودن ویژگی های پیشرفته