به گیرنده وب مهاجرت کنید

این راهنما نحوه انتقال برنامه Cast Receiver v2 را به آخرین برنامه Web Receiver توضیح می دهد.

SDK جدید Cast Application Framework (CAF) که با نام Web Receiver v3 نیز شناخته می شود، یک ارتقاء بزرگ از Receiver v2 SDK است. Web Receiver SDK یک SDK ساده و کارآمد برای توسعه برنامه‌های رسانه Web Receiver فراهم می‌کند.

گیرنده وب یک API ارائه می دهد که با API های فرستنده CAF جدید سازگارتر است. این یکپارچه سازی کامل یک پخش کننده (MPL و Shaka) و پیاده سازی و پشتیبانی کامل از رسانه Cast و دستورات صوتی Google Assistant را فراهم می کند. CAF SDK همچنین یک رابط کاربری پیش‌فرض ارائه می‌کند که می‌تواند به راحتی با استفاده از CSS استایل‌بندی شود، و یک سرویس اتصال داده برای ساده‌سازی پیاده‌سازی UI.

چرا مهاجرت کنیم؟

با انتقال یک برنامه Receiver v2 به Web Receiver، بسیاری از کدهای مربوط به پخش کننده را می توان حذف کرد، بنابراین می توانید روی نوشتن منطق تجاری برنامه خاص تمرکز کنید.

CAF به‌طور یکپارچه پخش‌کننده‌های MPL و Shaka را برای پشتیبانی از طیف وسیع‌تری از انواع محتوا از جمله پخش زنده HTTP (TS و CMAF)، MPEG-DASH، Smooth Streaming و انواع پشتیبانی شده توسط ویژگی منبع Media Element (MP3، MP4، Icecast و غیره) یکپارچه می‌کند. ..). برای فهرست کامل ، رسانه پشتیبانی شده برای Google Cast را ببینید. در حال حاضر CAF از پخش کننده ارائه شده توسط کاربر پشتیبانی نمی کند.

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

علاوه بر پشتیبانی از دستورات رسانه ای جدید - مانند "تغییر آهنگ ها بر اساس زبان" و "تغییر نرخ پخش" - CAF همچنین صف بندی بهتر، پشتیبانی از تبلیغات داخلی و پشتیبانی زنده بهتر را ارائه می دهد.

چه چیزی تغییر کرد؟

Web Receiver API سعی می کند از قراردادهایی پیروی کند که توسط فرستنده های CAF برای اندروید و iOS معرفی شده اند و کاملاً با نسخه 2 متفاوت است.

گیرنده وب از فضای نام جدید cast.framework به جای cast.receiver برای همه APIهای در معرض استفاده استفاده می کند. بسیاری از آبجکت‌های داده‌ای که توسط v2 استفاده می‌شد در CAF یکسان هستند و در فضای نام cast.framework.messages قرار می‌گیرند (اغلب تحت cast.receiver.media بودند).

سرویس‌های v2 زیر با سرویس‌های CAF مربوطه جایگزین می‌شوند:

  • کلاس CastReceiverManager با CastReceiverContext جایگزین شده است که یک تک تن است که جلسه cast، فرستنده ها، ارسال پیام های سفارشی و رویدادهای سیستم جهانی را مدیریت می کند. از CastReceiverOptions می توان برای ارائه گزینه های برنامه جهانی (مانند صف، نسخه گیرنده، پیکربندی پخش، و غیره) به متن استفاده کرد.
  • کلاس MediaManager با PlayerManager که یکی از ویژگی های CastReceiverContext singleton است جایگزین می شود و جلسه رسانه، درخواست های رسانه، درخواست های صوتی دستیار Google ( CommandAndControlManager در نسخه 2) را مدیریت می کند و رویدادهای رسانه را فعال می کند. پیکربندی برای بازیکنان ( cast.player.api.Host در MPL) توسط PlaybackConfig ارائه شده است که می تواند به صورت جهانی یا به ازای هر درخواست بار ارائه شود.

PlayerManager همچنین کلاس های مدیریت فرعی جدید را نشان می دهد:

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

// Set global options.
const options = new cast.framework.CastReceiverOptions();
options.versionCode = DEVELOPERS_APP_VERSION;

context.start(options);

منطق تجاری گیرنده

Receiver v2 کنترل‌کننده‌های رویداد (مانند CastReceiverManager.onReady یا MediaManager.onLoad ) را برای افزودن منطق تجاری در معرض نمایش قرار می‌دهد. در CAF، کنترل‌کننده‌های رویداد با شنوندگان رویداد ( CastReceiverContext.addEventListener ) و رهگیرهای پیام ( PlayerManager.setMessageInterceptor ) جایگزین می‌شوند. گیرنده وب می‌تواند چندین شنونده رویداد برای یک رویداد داشته باشد (شنونده روی رویداد تأثیری نمی‌گذارد)، و یک رهگیر در هر پیام. رهگیر می تواند درخواست را به روز کند یا آن را مدیریت کند (یک درخواست اصلاح شده، یک پیام موفقیت آمیز یا پیام خطا را برگرداند)، و می تواند یک کنترل کننده همگام باشد که یک وعده را برمی گرداند.

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

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    request => {
      // Resolve entity to content id
      if (request.media.entity && !request.media.contentId) {
        return getMediaByEntity(request.media.entity).then(
            media => {
              request.media.contentId = media.url;
              return request;
            });
      }
      return request;
    });

کنترل کننده وضعیت رسانه سفارشی شده v2 نیز با یک رهگیر پیام برای پیام وضعیت رسانه جایگزین شده است. برنامه‌های گیرنده وب که نمی‌خواهند نشانی وب رسانه در وضعیت رسانه نمایش داده شود، می‌توانند یک نشانی وب حل‌کننده ( PlayerManager.setMediaUrlResolver ) ارائه دهند که URL رسانه را برای درخواست بارگیری ارائه می‌کند. آن URL به صورت داخلی توسط CAF استفاده می شود و در وضعیت رسانه ارائه نشده است. 

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.MEDIA_STATUS,
    status => {
      // Disable seek.
      status.supportedMediaCommands &=
          ~cast.framework.messages.Command.SEEK
      return status;
    });

رویدادها

Web Receiver مجموعه گسترده ای از رویدادها را از CastReceiverContext و PlayerManager ارائه می دهد. برنامه‌های گیرنده وب می‌توانند چندین شنونده در هر رویدادی داشته باشند و همچنین می‌توانند یک شنونده را به چندین رویداد ارائه دهند. (برای برخی از گروه‌های رویداد به cast.framework.events.category مراجعه کنید.)

رویدادها هرگونه درخواست کاربر، پیشرفت پخش، پردازش پخش کننده و هر رویداد عنصر رسانه سطح پایین را پوشش می دهند (CAF خود عنصر رسانه را نشان نمی دهد).

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

// Log all media commands
playerManager.addEventListener(
    cast.framework.events.category.REQUEST,
    event => logEvent(event.type));

اتوبوس پیام سفارشی

CAF گذرگاه پیام را در API نمایش نمی دهد، در عوض CastReceiverContext.addCustomMessageListener را برای اضافه کردن شنونده پیام برای یک فضای نام خاص (فقط یک در هر فضای نام) و CastReceiverContext.sendCustomMessage برای ارسال پیام در یک فضای نام فراهم می کند. همه فضاهای نام باید قبل از راه‌اندازی Web Receiver (یعنی قبل از فراخوانی CastReceiverContext.start ) اعلام شوند. فضاهای نام را می توان با افزودن یک شنونده پیام به آنها اعلام کرد یا می توان به عنوان یک گزینه شروع در CastReceiverOptions.customNamespaces ارائه کرد. 

const options = new cast.framework.CastReceiverOptions();
options.customNamespaces = {
    CUSTOM_NS: cast.framework.system.MessageType.JSON
};
context.start(options);

context.sendCustomMessage(CUSTOM_NS, {
  type: 'status'
  message: 'Playing'
});

رابط کاربری پیش فرض

CAF یک رابط پیش‌فرض Web Receiver را ارائه می‌کند که نوار پیشرفت پخش و ابرداده رسانه را در صورت نیاز نمایش می‌دهد. رابط کاربری پیش‌فرض به‌عنوان یک عنصر سفارشی ( <cast-media-player> ) ارائه می‌شود که می‌تواند با استایلی شبیه به CSS استایل دهی شود.

<style>
   cast-media-player { --splash-image: url("splash.png"); }
</style>
<cast-media-player></cast-media-player>

برای سفارشی سازی بیشتر، یک برنامه Web Receiver می تواند رابط کاربری خود را پیاده سازی کند. Web Receiver کلاس cast.framework.ui.PlayerDataBinder را برای کمک به اتصال یک شی UI به وضعیت پخش Web Receiver ارائه می دهد.