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

این راهنمای توسعه‌دهندگان نحوه افزودن پشتیبانی Google Cast به برنامه «فرستنده وب» را بااستفاده از «کیت توسعه نرم‌افزار Cast» شرح می‌دهد.

اصطلاحات

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

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

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

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

بار کردن کتابخانه

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

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

چارچوب

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

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

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

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

برای شرح کامل فضای نام، مرجع میانای برنامه‌سازی کاربردی Google Cast Web Sender را مرور کنید.

دکمه پخش

جزء دکمه «پخش محتوا» در برنامه شما کاملاً توسط چارچوب مدیریت می‌شود. این شامل مدیریت نمایان بودن و همچنین مدیریت رویداد کلیک می‌شود.

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

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

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

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

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

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

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

برای مثال:

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

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

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

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

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

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

کنترل رسانه

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

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

از CastSession می‌توان برای بار کردن رسانه در دستگاه Cast متصل بااستفاده از loadMedia(loadRequest) استفاده کرد. ابتدا بااستفاده از contentId و contentType و همچنین هرگونه اطلاعات دیگری که به محتوا مربوط است، MediaInfo ایجاد کنید. سپس از آن 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‏ وعده‌ای برمی‌گرداند که می‌تواند برای انجام هرگونه عملیات لازم برای نتیجه موفقیت‌آمیز استفاده شود. اگر «وعده» رد شود، آرگومان تابع 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 را معرفی می‌کند که ایجاد آن مراحل اتصال به دستگاه، راه‌اندازی (یا پیوستن به) برنامه Web Receiver، اتصال به آن برنامه، و مقداردهی اولیه کانال کنترل رسانه را ترکیب می‌کند. برای اطلاعات بیشتر درباره جلسه‌های Cast و چرخه عمر «گیرنده وب»، راهنمای چرخه عمر برنامه «گیرنده وب» را ببینید.

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

برای نظارت بر وضعیت جلسه، شنونده‌ای به 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
    }
  });

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

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() تماس بگیرید.

برای اطلاعات بیشتر، انتقال جاری‌سازی در «گیرنده وب» را ببینید.

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