دمج حزمة 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، يجب أن يعرف موقع حزمة Google Cast Web Sender SDK، كما هو موضَّح أدناه. أضِف مَعلمة طلب البحث لعنوان URL loadCastFramework لتحميل Web Sender Framework API أيضًا. يجب أن تشير جميع صفحات تطبيقك إلى المكتبة على النحو التالي:

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

إطار العمل

تستخدِم حزمة Web Sender SDK مساحة الاسم 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 لتحديد لون حالة "مُستلِم الويب" المتصل، و--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 وعدًا يمكن استخدامه لتنفيذ أي عمليات ضرورية لتحقيق نتيجة ناجحة. إذا تم رفض الوعد، ستكون وسيطة الدالة هي chrome.cast.ErrorCode.

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

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

يمنح الرمز RemotePlayerController التطبيق إمكانية التحكّم الكامل في الوسائط من خلال رمزَي التشغيل والإيقاف المؤقت والإيقاف والتقديم أو الإيقاف للوسائط المحمَّلة.

  • تشغيل/إيقاف مؤقت: playerController.playOrPause();
  • إيقاف: 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;
  });

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

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

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

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

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

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