دمج حزمة تطوير البرامج (SDK) الخاصة بالإرسال في تطبيق "إرسال الويب"

يصف دليل مطوّر البرامج هذا كيفية إضافة دعم Google Cast إلى تطبيق "مُرسِل الويب" باستخدام حزمة تطوير البرامج (SDK) للبث.

ملاحظة: ننصحك بتجربة ما يلي:

• البرنامج التعليمي للترميز في مرسِل بث الويب: يمكنك الاطّلاع على معلومات مفصّلة حول كيفية تعديل تطبيق فيديو حالي لتشغيل المحتوى على جهاز Google Cast.
• نموذج تطبيق CastVideo-chrome (GitHub) - يمكنك تشغيل نموذج التطبيق المرجعي هذا وتصفُّحه والاطّلاع عليه والذي يتوافق مع إرشادات تجربة المستخدم وقائمة التحقّق الخاصة بالتصميم.

المصطلحات

الجهاز الجوّال أو المتصفّح هو المُرسِل الذي يتحكّم في التشغيل، وجهاز Google Cast هو المستلِم الذي يعرض المحتوى على الشاشة لتشغيله.

تتألف حزمة تطوير البرامج (SDK) لمُرسِل الويب من جزأين: واجهة برمجة تطبيقات الإطار (cast.framework) وواجهة برمجة التطبيقات الأساسية (chrome.cast) بشكل عام، أنت تُجري طلبات للحصول على واجهة برمجة تطبيقات إطار عمل أبسط وأعلى مستوى، وتعالجها بعد ذلك واجهة برمجة التطبيقات الأساسية ذات المستوى الأدنى.

يشير إطار عمل المُرسِل إلى Framework API والوحدة والموارد ذات الصلة التي توفّر برنامج تضمين حول الوظائف على المستوى الأدنى. يشير تطبيق المُرسِل أو تطبيق Google Cast على أجهزة Chrome إلى تطبيق ويب (HTML/JavaScript) يتم تشغيله داخل متصفّح Chrome على جهاز مُرسِل. يشير تطبيق مستقبِل الويب إلى تطبيق HTML/JavaScript الذي يتم تشغيله على Chromecast أو على جهاز Google Cast.

يستخدِم إطار عمل المُرسِل تصميمًا غير متزامن لمعاودة الاتصال لإعلام تطبيق المُرسِل بالأحداث والانتقال إلى حالة مختلفة من دورة حياة تطبيق البث.

تحميل المكتبة

لكي يتمكّن تطبيقك من تنفيذ ميزات Google Cast، يحتاج إلى معرفة موقع حزمة تطوير البرامج (SDK) لمُرسِل الويب على Google Cast، كما هو موضَّح أدناه. يمكنك إضافة معلَمة طلب بحث عنوان URL loadCastframework لتحميل واجهة برمجة تطبيقات Web sender Framework أيضًا. يجب أن تشير جميع صفحات تطبيقك إلى المكتبة على النحو التالي:

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

إطار العمل

تستخدم حزمة تطوير البرامج (SDK) لمُرسِل الويب cast.framework.* namespace. تمثّل مساحة الاسم ما يلي:

• الطرق أو الدوال التي تستدعي العمليات على واجهة برمجة التطبيقات
• أدوات معالجة الأحداث لوظائف المستمع في واجهة برمجة التطبيقات

ويتكون إطار العمل من هذه المكونات الرئيسية:

• CastContext كائن سينغلتون يقدم معلومات حول حالة البث الحالية، ويشغّل أحداثًا لحالة حالة البث وحالة جلسة البث.
• ويدير عنصر CastSession الجلسة، حيث يقدم معلومات عن الحالة ويؤدي إلى تشغيل الأحداث، مثل التغييرات في حجم الجهاز وحالة التجاهل والبيانات الوصفية للتطبيقات.
• عنصر الزر "إرسال"، وهو عنصر HTML مخصّص وبسيط يعمل على توسيع زر HTML. وإذا لم يكن زر البث المقدَّم كافيًا، يمكنك استخدام حالة البث لتنفيذ زر البث.
• توفّر RemotePlayerController ربط البيانات لتبسيط تنفيذ المشغّل عن بُعد.

يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات لمُرسِل الويب لتطبيق Google Cast للحصول على وصف كامل لمساحة الاسم.

زر الإرسال

ويتم التعامل مع مكوِّن زر البث في تطبيقك بالكامل من خلال إطار العمل. ويشمل ذلك إدارة أذونات الوصول، بالإضافة إلى معالجة أحداث النقرات.

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

وبدلاً من ذلك، يمكنك إنشاء الزر آليًا:

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

يمكنك تطبيق أي تصميم إضافي، مثل الحجم أو الموضع، على العنصر حسب الضرورة. استخدِم السمة --connected-color لاختيار لون حالة استقبال الويب المتّصل و--disconnected-color للحالة غير المتصلة.

الإعداد

بعد تحميل واجهة برمجة تطبيقات إطار العمل، سيطلب التطبيق المعالج window.__onGCastApiAvailable. يجب التأكد من ضبط التطبيق لهذا المعالج على window قبل تحميل مكتبة المُرسِل.

ضمن هذا المعالج، يمكنك إعداد التفاعل مع البث من خلال استدعاء طريقة 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.

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

عند وقوع أحداث مثل الإيقاف المؤقت أو التشغيل أو الاستئناف أو تقديم الفيديو أو البحث عنه، سيحتاج التطبيق إلى اتّخاذ إجراء بشأنها ومزامنتها بينه وبين تطبيق مستقبِل الويب على جهاز البث. يُرجى الاطّلاع على تحديثات الحالة لمزيد من المعلومات.

آلية عمل إدارة الجلسات

تقدم حزمة تطوير البرامج (SDK) للبث مفهوم جلسة البث الذي يجمع خطوات ربط الجهاز بجهاز أو إطلاق تطبيق على الويب (أو الانضمام إليه) والاتصال بهذا التطبيق وإعداد قناة للتحكّم بالوسائط. اطلع على دليل دورة حياة التطبيق للمستلِم على الويب للحصول على مزيد من المعلومات حول جلسات البث ودورة حياة مستقبِل الويب.

تتم إدارة الجلسات من خلال الصف CastContext، الذي يمكن لتطبيقك استرداده من خلال cast.framework.CastContext.getInstance(). يتم تمثيل الجلسات الفردية بالفئات الفرعية للصف Session. على سبيل المثال، CastSession يمثل الجلسات التي تتضمن أجهزة بث. يمكن لتطبيقك الوصول إلى جلسة البث النشطة حاليًا عبر 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 أو الشاشات الذكية. يتوقّف تشغيل الوسائط على أحد الأجهزة (المصدر) ويستمر التشغيل على جهاز آخر (الوجهة). يمكن استخدام جهاز بث يتضمّن أحدث البرامج الثابتة كمصادر أو وجهات أثناء نقل البث.

للحصول على الجهاز الوجهة الجديد أثناء نقل البث، يمكنك الاتصال بالرقم CastSession#getCastDevice() عند استدعاء cast.framework.SessionState.SESSION_RESUMED الحدث.

اطّلِع على نقل ملكية البث على مستقبِل الويب للحصول على مزيد من المعلومات.