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

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

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

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

المصطلحات

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

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

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

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

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

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

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

إطار العمل

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

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

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

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

راجع مرجع واجهة برمجة التطبيقات Google Cast Web Sender للحصول على وصف كامل لمساحة الاسم.

زر الإرسال

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

<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) ثابتة ومحدّدة مسبقًا من خلال Web Sender، كما هو موضّح أدناه، بدلاً من 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 للتطبيق التحكم الكامل في الوسائط التي تم تحميلها، مثل "PLAY" و"PAUSE" و"STOP" و"SeeK" (البحث) للوسائط التي تم تحميلها.

• تشغيل/إيقاف مؤقت: 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) لتكنولوجيا Cast مفهوم جلسة 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.

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