تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

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

المصطلحات

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

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

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

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

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

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

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

إطار عمل

تستخدم حزمة تطوير البرامج (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 قبل تحميل مكتبة المُرسِل.

ضمن هذا المعالج، يمكنك بدء تفاعل 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
  });
};

يسترد التطبيق أولاً مثيل singleton لكائن 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 يمكن استخدامه لإجراء أي عمليات ضرورية للحصول على نتيجة ناجحة. إذا تم رفض 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;
  });

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

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

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

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

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

الإعداد

إضافة ميزات متقدمة

دمج حزمة SDK للإرسال في تطبيق Web Sender تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

المصطلحات

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

إطار عمل

زر الإرسال

الإعداد

التحكم في الوسائط

حالة الوسائط

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

إعادة توجيه البث

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