دمج حزمة SDK للإرسال في تطبيق Web Sender

يوضّح دليل المطوّرين هذا كيفية إضافة ميزة Google Cast إلى تطبيق Web Sender باستخدام حزمة تطوير البرامج (SDK) الخاصة بـ Cast.

المصطلحات

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

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

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

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

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

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

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

إطار عمل

تستخدم حزمة تطوير البرامج (SDK) الخاصة بـ Web Sender مساحة الاسم cast.framework.*. تمثّل مساحة الاسم ما يلي:

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

يتألف إطار العمل من المكوّنات الرئيسية التالية:

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

راجِع مرجع Google Cast Web Sender API للحصول على وصف كامل لمساحة الاسم.

زر الإرسال

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

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

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

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

يمكنك تطبيق أي تنسيق إضافي، مثل الحجم أو تحديد الموضع، على العنصر حسب الحاجة. استخدِم السمة --connected-color لاختيار لون حالة Web Receiver المتصلة، واستخدِم السمة --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.

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

يمكنك الوصول إلى متغيّرات حالة اللاعب في RemotePlayer. يتم التعامل مع جميع التفاعلات مع RemotePlayer، بما في ذلك عمليات معاودة الاتصال بأحداث الوسائط والأوامر، باستخدام RemotePlayerController.

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

يمنح الرمز RemotePlayerController التطبيق إمكانية التحكّم الكامل في الوسائط، بما في ذلك تشغيل الوسائط المحمّلة وإيقافها مؤقتًا وإيقافها والبحث فيها.

• تشغيل/إيقاف مؤقت: playerController.playOrPause();
• STOP: playerController.stop();
• SEEK: 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. لمزيد من المعلومات، يمكنك الاطّلاع على آخر الأخبار.

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

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

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

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

لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إعادة توجيه البث على تطبيق Web Receiver.