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

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

المصطلحات

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

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

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

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

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

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

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

Framework

تستخدم حزمة Web Sender SDK مساحة الاسم cast.framework.* . تمثّل مساحة الاسم ما يلي:

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

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

• ‫CastContext هو عنصر سينغلتون يقدّم معلومات عن الـ حالة Cast الحالية، ويُطلق الأحداث لتغييرات حالة Cast وحالة جلسة Cast.
• يدير عنصر CastSession الجلسة، ويقدّم معلومات عن الحالة ويُطلق الأحداث، مثل التغييرات في مستوى صوت الجهاز، وحالة كتم الصوت وبيانات التطبيق الوصفية.
• عنصر زر البث هو عنصر HTML مخصّص بسيط يوسّع زر HTML. إذا لم يكن زر البث المقدَّم كافيًا، يمكنك استخدام حالة Cast لتنفيذ زر البث.
• يوفر 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.

إذا كنت تستخدم "مشغّل الوسائط التلقائي"، الذي لا يتطلّب التسجيل، يمكنك استخدام ثابت محدّد مسبقًا من خلال حزمة Web Sender 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;
  });

عند حدوث أحداث مثل الإيقاف المؤقت أو التشغيل أو الاستئناف أو البحث، سيحتاج التطبيق إلى التفاعل معها والمزامنة بينه وبين تطبيق Web Receiver على جهاز Cast. لمزيد من المعلومات، يمكنك الاطّلاع على مقالة تعديلات الحالة.

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

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

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

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

في حين أنّه يمكن للمستخدِم التحكّم مباشرةً في إنهاء Cast من خلال زر Cast في إطار العمل، يمكن للمرسِل نفسه إيقاف الإرسال باستخدام عنصر 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.