النقل إلى مستقبِل الويب

يوضح هذا الدليل كيفية ترحيل تطبيق الإصدار 2 من جهاز استقبال Cast إلى أحدث تطبيق لمستقبل الويب.

تمثل حزمة تطوير البرامج (SDK) الجديدة لإطار عمل تطبيق Cast (CAF)، والمعروفة أيضًا باسم الإصدار 3 من مستقبِل الويب، ترقية كبيرة من SDK للمستلم v2 SDK. توفر SDK لمستقبل الويب مجموعة أدوات SDK سهلة الاستخدام ومتطورة لتطوير تطبيقات وسائط الويب.

يوفر مستلم الويب واجهة برمجة تطبيقات أكثر اتساقًا مع واجهات برمجة تطبيقات مرسل CAF الجديد. وتوفّر هذه الواجهة دمجًا كاملاً للمشغل (MPL وShaka) وإمكانية التنفيذ والدعم الكامل لوسائط الإرسال والطلبات الصوتية في "مساعد Google". وتوفّر حزمة تطوير البرامج CAF أيضًا واجهة مستخدم تلقائية يمكن تصميمها بسهولة باستخدام CSS وخدمة ربط بيانات لتبسيط تنفيذ واجهة المستخدم.

أسباب الترحيل

عند ترحيل تطبيق مستلم الإصدار 2 إلى جهاز استقبال الويب، يمكن التخلص من الكثير من الشفرات التي تتعامل مع المشغل، حتى تتمكن من التركيز على كتابة منطق الأعمال الخاص بالتطبيقات.

يدمج برنامج CAF بسهولة بين مشغّلات MPL وShaka لدعم مجموعة أكبر من أنواع المحتوى، بما في ذلك البث المباشر عبر HTTP (TS وCMAF) وMPEG-DASH وSmooth Streaming والأنواع المتوافقة مع موقع مصدر الوسائط (MP3 وMP4 وIcecast، إلخ...). للحصول على قائمة كاملة، يمكنك الاطلاع على الوسائط المدعومة في Google Cast. لا يتيح CAF حاليًا استخدام مشغّل يوفره المستخدم.

سيضيف الترحيل إلى CAF دعم التحكم الصوتي باستخدام مساعد Google. وسيتم تلقائيًا دعم أي أمر صوتي جديد من "مساعد Google" عند استخدام CAF.

بالإضافة إلى دعم أوامر الوسائط الجديدة، مثل "تغيير المقاطع الصوتية حسب اللغة" و"تغيير معدل التشغيل"، يوفّر CAF أيضًا قوائم انتظار أفضل ودعمًا مضمّنًا للإعلانات ودعمًا مباشرًا بشكل أفضل.

ما الذي تغيَّر؟

تحاول واجهة برمجة تطبيقات مستلم الويب اتّباع الاصطلاحات التي قدّمها مرسِلو CAF لنظامَي التشغيل Android وiOS، وهي تختلف تمامًا عن الإصدار 2.

يستخدم مستقبِل الويب مساحة اسم جديدة cast.framework بدلاً من مساحة اسم cast.receiver لجميع واجهات برمجة التطبيقات التي تم الكشف عنها. العديد من كائنات البيانات التي تم استخدامها بواسطة الإصدار 2 هي نفسها في CAF ويتم عرضها ضمن مساحة الاسم cast.framework.messages (كانت غالبًا ضمن cast.receiver.media).

تم استبدال خدمات الإصدار الثاني من Chrome التالية بخدمات CAF المقابلة:

• يتم استبدال الفئة CastReceiverManager بـ CastReceiverContext وهو إعداد فردي يدير جلسة البث والمُرسِلين ويرسل رسائل مخصّصة وأحداث النظام الشاملة. ويمكن استخدام CastReceiverOptions لتوفير خيارات عامة للتطبيق (مثل اللائحة وإصدار جهاز الاستقبال وتهيئة التشغيل وما إلى ذلك) إلى السياق.
• يتم استبدال الفئة MediaManager بالنوع PlayerManager الذي يمثّل إحدى سمات CastReceiverContext السينغلتون، ويدير الجلسة الإعلامية وطلبات الوسائط وطلبات Google Voice الصوتية (CommandAndControlManager في الإصدار 2)، ويفعّل الأحداث الإعلامية. يوفّر PlaybackConfig إعداد للمشغلات (cast.player.api.Host بتنسيق MPL) والذي يمكن توفيره على مستوى العالم أو لكل طلب تحميل.

يعرض PlayerManager أيضًا فئات المدراء الفرعيين الجديدة:

• TextTracksManager: لإدارة المقاطع الصوتية النصية للوسائط
• AudioTracksManager: لإدارة المقاطع الصوتية
• QueueManager: لإدارة قائمة الانتظار
• BreakManager: إدارة الإعلانات

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

منطق الأعمال لدى المستلِم

الإصدار 2 من معالجات الأحداث المكشوفة للمستلِم (مثل CastReceiverManager.onReady أو MediaManager.onLoad) لإضافة منطق النشاط التجاري في CAF، يتم استبدال معالجات الأحداث بمستمعي الأحداث (CastReceiverContext.addEventListener) وأدوات اعتراض الرسائل (PlayerManager.setMessageInterceptor). يمكن أن يكون لدى مستلم الويب أدوات معالجة حدث متعددة لأحد الأحداث (لا يؤثر المستمع في الحدث)، وأداة اعتراض واحدة لكل رسالة. يمكن للاعتراض تحديث الطلب أو التعامل معه (عرض طلب مُعدّل أو رسالة نجاح أو رسالة خطأ)، ويمكن أن يكون معالجًا غير متزامن يؤدي إلى عرض وعد.

اعتراض طلب التحميل هو المكان الأكثر شيوعًا لإضافة منطق خاص بالتطبيق. بالنسبة إلى طلبات التحميل الواردة من مُرسِل معيّن، يمكن لأداة اعتراض التحميل تحويل Content ID إلى عنوان 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;
    });

ويتم أيضًا استبدال معالج حالة الوسائط المخصّصة للإصدار 2 بأداة اعتراض الرسائل لرسالة حالة الوسائط. يمكن لتطبيقات مستقبِل الويب التي لا تريد عرض عنوان URL للوسائط في حالة الوسائط أن توفّر برنامج تعيين عناوين URL (PlayerManager.setMediaUrlResolver)، الذي يوفّر عنوان URL للوسائط لطلب التحميل. ويستخدم CAF عنوان URL هذا داخليًا ولا يتم توفيره في حالة الوسائط.

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

الأحداث

يوفّر مستقبِل الويب مجموعة واسعة من الأحداث من CastReceiverContext و PlayerManager. يمكن أن يكون لتطبيقات مستقبل الويب عدة مستمعين في أي حدث، كما يمكن أن توفر أيضًا مستمعًا واحدًا لأحداث متعددة. (راجع cast.framework.events.category للاطّلاع على بعض مجموعات الأحداث.)

تغطي الأحداث أي طلب من المستخدمين، ومستوى تقدّم التشغيل، ومعالجة المشغل، وأي حدث من عناصر الوسائط ذات المستوى المنخفض (لا يعرض CAF عنصر الوسائط نفسه).

يمكن لتطبيق "مستقبل الويب" إضافة أدوات معالجة الحدث بناءً على ما تريد (على سبيل المثال، إضافة تعريف للمسارات النصية عند اكتمال التحميل) أو للتحليلات.

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

حافلة رسائل مخصّصة

لا يعرض CAF حافلة الرسائل في واجهة برمجة التطبيقات، بل يوفّر CastReceiverContext.addCustomMessageListener لإضافة أداة معالجة رسائل لمساحة اسم معيّنة (واحدة فقط لكل مساحة اسم) و CastReceiverContext.sendCustomMessage لإرسال رسالة على مساحة الاسم. يجب الإعلان عن جميع مساحات الأسماء قبل بدء مستقبِل الويب (أي قبل طلب CastReceiverContext.start).

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 واجهة مستخدم افتراضية لمستقبل الويب تعرض شريط تقدم التشغيل والبيانات الوصفية للوسائط عند اللزوم. يتم توفير واجهة المستخدم التلقائية كعنصر مخصّص (<cast-media-player>) يمكن تصميمه بنمط بنمط CSS.

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

للحصول على مزيد من التخصيص، يمكن لتطبيق مستلم الويب تنفيذ واجهة المستخدم التابعة له. يوفّر جهاز استقبال الويب فئة cast.framework.ui.PlayerDataBinder للمساعدة في ربط كائن واجهة المستخدم بحالة تشغيل مستقبِل الويب.