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

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

المصطلحات

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

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

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

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

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

حتى يتمكّن تطبيقك من تنفيذ ميزات Google Cast، يحتاج التطبيق إلى معرفة موقع حزمة تطوير البرامج (SDK) لمرسِل Google Cast Web Sender، كما هو موضّح أدناه. أضِف معلَمة طلب البحث لعنوان 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 وعدًا يمكن استخدامه لتنفيذ أي عمليات ضرورية للحصول على نتيجة ناجحة. إذا تم رفض Promise، ستكون وسيطة الدالة هي 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 استقبال على جهاز البث. اطّلِع على تحديثات الحالة للحصول على مزيد من المعلومات.

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

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

تتم إدارة الجلسات من خلال الصف 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.

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

السابق
الإعداد
التالي
إضافة ميزات متقدمة